KbRemotePlan.java

/*
 * Copyright © 2026 IKE Network (support@ike.network)
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package network.ike.plugin;

import network.ike.workspace.ManifestWriter;

import java.nio.file.Path;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

/**
 * What giving a project its remote does (IKE-Network/ike-issues#1370, decision 4): a
 * knowledge-base project is created with no remote and its own folder, as a {@code file:}
 * URL, in the {@code <scm>} of its POM and in the {@code repo:} of a working set's
 * {@code workspace.yaml}. Adding a remote sets {@code origin}, replaces those URLs, commits
 * the change, and pushes. The remote is the project's own: the Maven project that builds
 * the knowledge base, not the knowledge base it builds.
 *
 * <p>The plan is pure: everything it is made from was read beforehand, so it can be
 * checked and shown before anything is changed. Publish applies exactly this plan.
 */
final class KbRemotePlan {

    /** A URL with a scheme git reads. */
    private static final Pattern URL = Pattern.compile("^(https?|ssh|git|file)://\\S+$");

    /** The short form, {@code user@host:path}. */
    private static final Pattern SCP = Pattern.compile("^([\\w.-]+)@([\\w.-]+):(\\S+)$");

    /** {@code ssh://user@host[:port]/path}. */
    private static final Pattern SSH = Pattern.compile("^ssh://(?:[\\w.-]+@)?([\\w.-]+)(?::\\d+)?/(\\S+)$");

    /**
     * What a POM's {@code <scm>} names.
     *
     * @param url                 where a person reads the repository
     * @param connection          how it is read, as {@code scm:git:…}
     * @param developerConnection how it is written to, as {@code scm:git:…}
     */
    record Scm(String url, String connection, String developerConnection) {

        /**
         * The values by the name of their element.
         *
         * @return element name to value
         */
        Map<String, String> values() {
            Map<String, String> values = new LinkedHashMap<>();
            values.put("url", url);
            values.put("connection", connection);
            values.put("developerConnection", developerConnection);
            return values;
        }
    }

    /**
     * What the remote answered when it was asked for its branches.
     *
     * @param reachable  whether it answered
     * @param error      why it did not, or blank
     * @param branchHead the commit its branch of the project's name is at, when it has one
     * @param contained  whether the project's history already contains that commit, so a
     *                   push only adds to it
     * @param branches   how many branches it has
     */
    record Probe(boolean reachable, String error, Optional<String> branchHead, boolean contained, int branches) {

        /** A remote that was not asked: the push is skipped. */
        static final Probe NOT_ASKED = new Probe(false, "", Optional.empty(), false, 0);
    }

    /**
     * Everything the plan is made from.
     *
     * @param root            the project's folder, the root of its git repository
     * @param pom             the text of its {@code pom.xml}
     * @param remote          the remote's URL, as given
     * @param origin          the URL {@code origin} already names, when there is one
     * @param branch          the branch checked out
     * @param pomUncommitted  whether {@code pom.xml} has uncommitted changes
     * @param probe           what the remote answered
     * @param manifest        the {@code workspace.yaml} of the working set the project is a
     *                        member of, when it is one
     * @param manifestYaml    that file's text
     * @param push            whether the branch is pushed once the remote is set
     */
    record Inputs(Path root, String pom, String remote, Optional<String> origin, String branch, boolean pomUncommitted,
                  Probe probe, Optional<Path> manifest, Optional<String> manifestYaml, boolean push) {
    }

    private final Inputs in;
    private final String remote;
    private final Scm current;
    private final Scm wanted;
    private final String newPom;
    private final Optional<String> newManifest;

    /**
     * Builds and checks the plan.
     *
     * @param inputs everything it is made from
     * @throws IllegalArgumentException if the remote is no git URL, the POM has no
     *                                  {@code <scm>} or already names another remote,
     *                                  {@code origin} already names another remote, or
     *                                  {@code pom.xml} has uncommitted changes
     */
    KbRemotePlan(Inputs inputs) {
        this.in = Objects.requireNonNull(inputs, "inputs");
        this.remote = inputs.remote() == null ? "" : inputs.remote().strip();
        if (remote.isEmpty()) {
            throw new IllegalArgumentException("Name the remote with -Dremote=<git URL>, such as"
                    + " -Dremote=https://github.com/my-org/my-kb.git");
        }
        if (!URL.matcher(remote).matches() && !SCP.matcher(remote).matches()) {
            throw new IllegalArgumentException("-Dremote is not a git URL: " + remote + ". Use https://…,"
                    + " ssh://…, or user@host:path.");
        }
        Map<String, String> scm = PomRewriter.readScm(inputs.pom());
        if (scm.isEmpty()) {
            throw new IllegalArgumentException("pom.xml has no <scm> to point at the remote. A project made"
                    + " by ike:kb-create-publish has one.");
        }
        this.current = new Scm(scm.getOrDefault("url", ""), scm.getOrDefault("connection", ""),
                scm.getOrDefault("developerConnection", ""));
        this.wanted = scmFor(remote);
        boolean local = current.connection().startsWith("scm:git:file:") || current.url().startsWith("file:");
        if (!local && !current.equals(wanted)) {
            throw new IllegalArgumentException("pom.xml already names a remote, " + current.url()
                    + ". To move the project to another, change its <scm> and origin by hand.");
        }
        if (inputs.origin().isPresent() && !inputs.origin().get().equals(remote)) {
            throw new IllegalArgumentException("origin is already " + inputs.origin().get()
                    + ". To move the project to another remote, change origin by hand.");
        }
        this.newPom = PomRewriter.updateScm(inputs.pom(), wanted.values());
        if (pomChanges() && inputs.pomUncommitted()) {
            throw new IllegalArgumentException("pom.xml has uncommitted changes. Commit them first, so the"
                    + " commit that names the remote contains nothing else.");
        }
        String member = inputs.root().getFileName().toString();
        this.newManifest = inputs.manifestYaml()
                .map(yaml -> ManifestWriter.updateSubprojectField(yaml, member, "repo", remote))
                .filter(yaml -> !yaml.equals(inputs.manifestYaml().get()));
    }

    /**
     * What a POM's {@code <scm>} names for a remote: the URL as given to read from and
     * write to, and the address a person opens, which for an SSH remote is the same
     * repository over HTTPS.
     *
     * @param remote the remote's URL
     * @return the three values
     */
    static Scm scmFor(String remote) {
        String browse = remote;
        Matcher scp = SCP.matcher(remote);
        Matcher ssh = SSH.matcher(remote);
        if (scp.matches()) {
            browse = "https://" + scp.group(2) + "/" + scp.group(3);
        } else if (ssh.matches()) {
            browse = "https://" + ssh.group(1) + "/" + ssh.group(2);
        }
        if (!browse.startsWith("file:") && browse.endsWith(".git")) {
            browse = browse.substring(0, browse.length() - ".git".length());
        }
        return new Scm(browse, "scm:git:" + remote, "scm:git:" + remote);
    }

    /**
     * What the plan is made from.
     *
     * @return the inputs
     */
    Inputs inputs() {
        return in;
    }

    /**
     * The remote, as it is given to git.
     *
     * @return the URL
     */
    String remote() {
        return remote;
    }

    /**
     * Whether {@code pom.xml} is rewritten and committed.
     *
     * @return {@code false} when it already names the remote
     */
    boolean pomChanges() {
        return !newPom.equals(in.pom());
    }

    /**
     * The POM with its {@code <scm>} naming the remote.
     *
     * @return the POM's text
     */
    String newPom() {
        return newPom;
    }

    /**
     * Whether {@code origin} is added.
     *
     * @return {@code false} when it already names the remote
     */
    boolean addOrigin() {
        return in.origin().isEmpty();
    }

    /**
     * The working set's {@code workspace.yaml} with the member's {@code repo:} naming the
     * remote, when the project is a member and the file changes.
     *
     * @return the file's new text
     */
    Optional<String> newManifest() {
        return newManifest;
    }

    /**
     * Why the push would fail, known before anything is changed: the remote did not
     * answer, or its branch has commits the project does not.
     *
     * @return the reason, a sentence, or empty when the push can go ahead or is skipped
     */
    Optional<String> pushProblem() {
        if (!in.push()) {
            return Optional.empty();
        }
        Probe probe = in.probe();
        if (!probe.reachable()) {
            return Optional.of("The remote could not be read" + (probe.error().isBlank() ? "" : ": " + probe.error())
                    + ". Create the repository on the git host first, empty, and check that you are signed in.");
        }
        if (probe.branchHead().isPresent() && !probe.contained()) {
            return Optional.of("The remote already has a branch " + in.branch() + " with commits this project"
                    + " does not have. Use an empty repository, or one that is this project's own.");
        }
        return Optional.empty();
    }

    /**
     * The commit message for the POM.
     *
     * @return the message
     */
    String commitMessage() {
        return "Point " + in.root().getFileName() + " at its remote\n\n"
                + "Generated by ike:kb-remote-publish: the <scm> of pom.xml names " + remote
                + " in place of the project's own folder.";
    }

    /**
     * The report the draft and publish goals both print.
     *
     * @return the report's lines
     */
    List<String> report() {
        List<String> lines = new ArrayList<>();
        lines.add("Add remote: " + in.root().getFileName());
        lines.add("  Folder:       " + in.root());
        lines.add("  Remote:       " + remote + "  (" + remoteState() + ")");
        lines.add("  origin:       " + (addOrigin() ? "added" : "already set"));
        if (pomChanges()) {
            lines.add("  pom.xml scm:  url                  " + current.url() + " → " + wanted.url());
            lines.add("                connection           " + current.connection() + " → " + wanted.connection());
            lines.add("                developerConnection  " + current.developerConnection() + " → "
                    + wanted.developerConnection());
            lines.add("  Commit:       Point " + in.root().getFileName() + " at its remote (pom.xml alone)");
        } else {
            lines.add("  pom.xml scm:  already names the remote");
        }
        newManifest.ifPresent(yaml -> lines.add("  Working set:  repo: of " + in.root().getFileName() + " in "
                + in.manifest().map(Path::toString).orElse("workspace.yaml") + " → " + remote + ", committed there"));
        lines.add("  Push:         " + (in.push() ? "branch " + in.branch() + " to origin, which it then tracks"
                : "skipped (-DskipPush); push it with git push -u origin " + in.branch()));
        return lines;
    }

    private String remoteState() {
        Probe probe = in.probe();
        if (!in.push()) {
            return "not asked";
        }
        if (!probe.reachable()) {
            return "could not be read";
        }
        if (probe.branchHead().isEmpty()) {
            return probe.branches() == 0 ? "empty" : "has no branch " + in.branch();
        }
        return probe.contained() ? "has branch " + in.branch() + ", which this project already contains"
                : "has branch " + in.branch() + " with other commits";
    }
}