@intentius/chant 0.124.12 → 0.124.14

package/dist/op/activities/propose-upgrade.js

@@ -0,0 +1,165 @@
+/**
+ * proposeWorkspaceUpgrade — the propose-only activity behind scheduled
+ * template upgrades (#2550, D9, ws-032).
+ *
+ * `chant workspace upgrade` is a core command. An Op, including a workspace Op
+ * later (#2554), schedules it through this activity, which stages the same
+ * upgrade (fetch, migrate, merge per file, build, lint and `workspace check`
+ * in a worktree) and then only proposes it:
+ *
+ * - `report` (default): stage and check, and return the summary.
+ * - `branch`: commit the patch on a proposal branch, by default
+ *   `chant/upgrade/<scope>`, and push it when the repository has the remote.
+ * - `pull-request`: the branch, plus an open pull request against the default
+ *   branch, created once and edited on later runs.
+ *
+ * It never writes the default branch or the checked-out branch, and it never
+ * applies the patch to the working tree, so an Op cannot rewrite itself or
+ * the gates that judge it. Review and merge of the pull request are the
+ * approval. The PR body names the patch digest, the value `chant workspace
+ * upgrade` binds its gate to, so the two paths approve the same thing.
+ *
+ * The workspace code loads on first call, so importing core's activities
+ * loads nothing under `workspace/` (#2525 rule 5).
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { ghHostEnv } from "./gh-host.js";
+import { restPullRequestForge, upsertPullRequest } from "./forge-pull-request.js";
+const execFileAsync = promisify(execFile);
+// `gh pr list/edit/create` name no host, so they are told the job's forge or
+// `origin`'s host (#3780); see `./gh-host.ts`.
+const defaultRun = async (bin, args, cwd) => (await execFileAsync(bin, args, { cwd, maxBuffer: 64 * 1024 * 1024, ...(bin === "gh" ? { env: await ghHostEnv(process.env, cwd) } : {}) })).stdout;
+/** The proposal branch for a scope. */
+export function proposalBranch(scope) {
+    return `chant/upgrade/${scope === "." ? "root" : scope.replace(/[^A-Za-z0-9._/-]/g, "-")}`;
+}
+/** The marker that finds this scope's pull request again. */
+export function proposalMarker(scope) {
+    return `<!-- chant-workspace-upgrade:${scope} -->`;
+}
+function body(staged, lines) {
+    return [
+        proposalMarker(staged.gate),
+        `## Template upgrade: \`${staged.gate}\``,
+        "",
+        `\`${staged.template}\` from \`${staged.from ?? "(no ref)"}\` to \`${staged.to ?? "(no ref)"}\`.`,
+        "",
+        `Patch digest: \`${staged.digest}\``,
+        "",
+        "```",
+        ...lines,
+        "```",
+        "",
+        staged.manualSteps.length > 0
+            ? `${staged.manualSteps.length} file(s) did not merge cleanly and are kept as they were, each with a manual step. \`chant workspace check\` fails until each is merged and resolved with \`chant workspace lineage resolve <path>\`.`
+            : "Every file merged cleanly.",
+        staged.governance ? "\nThis upgrade changes governance files. Review it under the rules on the default branch, not the ones it proposes." : "",
+        "",
+        "Proposed by the `proposeWorkspaceUpgrade` activity. It never writes the default branch.",
+    ].join("\n");
+}
+async function defaultBranch(run, repo, remote) {
+    try {
+        const ref = (await run("git", ["symbolic-ref", "--short", `refs/remotes/${remote}/HEAD`], repo)).trim();
+        return ref.startsWith(`${remote}/`) ? ref.slice(remote.length + 1) : ref;
+    }
+    catch {
+        return null;
+    }
+}
+/** Stage a workspace upgrade and propose it as a branch or pull request. Never writes the default branch. */
+export async function proposeWorkspaceUpgrade(args) {
+    const mode = args.mode ?? "report";
+    const run = args._run ?? defaultRun;
+    const remote = args.remote ?? "origin";
+    const { stageUpgrade, describeStaged, commitStagedUpgrade } = await import("../../workspace/lineage-upgrade.js");
+    const staged = await stageUpgrade({
+        root: args.cwd ?? process.cwd(),
+        scope: args.scope,
+        to: args.to,
+        allowCode: args.allowCode,
+        ...(args.source !== undefined ? { source: args.source } : {}),
+        ...(args._runChant ? { runChant: args._runChant } : {}),
+    });
+    try {
+        const lines = describeStaged(staged);
+        const result = {
+            scope: staged.gate,
+            mode,
+            changed: staged.changed,
+            proposed: false,
+            checksOk: staged.checksOk,
+            from: staged.from,
+            to: staged.to,
+            digest: staged.digest,
+            manualSteps: staged.manualSteps.length,
+            governance: staged.governance !== null,
+            summary: lines.join("\n"),
+        };
+        if (!result.changed || !result.checksOk || mode === "report")
+            return result;
+        const branch = args.branch ?? proposalBranch(staged.gate);
+        const remoteDefault = await defaultBranch(run, staged.repo, remote);
+        const base = args.base ?? remoteDefault;
+        let current = null;
+        try {
+            current = (await run("git", ["symbolic-ref", "--short", "HEAD"], staged.repo)).trim();
+        }
+        catch {
+            // Detached HEAD: nothing checked out to protect.
+        }
+        for (const [what, name] of [["default branch", remoteDefault], ["base branch", base], ["checked-out branch", current]]) {
+            if (name && branch === name) {
+                throw new Error(`proposeWorkspaceUpgrade only proposes: it will not write the ${what} "${name}". Choose another branch.`);
+            }
+        }
+        if (mode === "pull-request" && !base) {
+            throw new Error(`proposeWorkspaceUpgrade: cannot tell the default branch of "${remote}"; pass base`);
+        }
+        const title = `chore(upgrade): ${staged.template} ${staged.to ?? ""} (${staged.gate})`.replace(/\s+/g, " ").replace(" )", ")");
+        result.commit = commitStagedUpgrade(staged, branch, `${title}\n\nPatch digest: ${staged.digest}\n`);
+        result.branch = branch;
+        result.proposed = true;
+        let hasRemote = false;
+        try {
+            await run("git", ["remote", "get-url", remote], staged.repo);
+            hasRemote = true;
+        }
+        catch {
+            hasRemote = false;
+        }
+        if (hasRemote) {
+            // The proposal branch is rebuilt from the default branch on every run, so it is replaced.
+            await run("git", ["push", "--force", remote, `${result.commit}:refs/heads/${branch}`], staged.repo);
+            result.pushed = true;
+        }
+        else {
+            result.pushed = false;
+        }
+        if (mode !== "pull-request")
+            return result;
+        if (!hasRemote)
+            throw new Error(`proposeWorkspaceUpgrade: no remote "${remote}" to open a pull request on`);
+        const text = body(staged, lines);
+        // `gh pr` speaks GraphQL, which Forgejo does not serve (#3798).
+        const forge = args._forge !== undefined ? args._forge : await restPullRequestForge(process.env, { cwd: staged.repo, remote });
+        if (forge) {
+            result.prUrl = (await upsertPullRequest(forge, { head: branch, base: base, title, body: text })).pr.url;
+            return result;
+        }
+        const existing = (await run("gh", ["pr", "list", "--head", branch, "--state", "open", "--json", "url", "--jq", ".[0].url // empty"], staged.repo)).trim();
+        if (existing) {
+            await run("gh", ["pr", "edit", existing, "--title", title, "--body", text], staged.repo);
+            result.prUrl = existing;
+        }
+        else {
+            const out = await run("gh", ["pr", "create", "--base", base, "--head", branch, "--title", title, "--body", text], staged.repo);
+            result.prUrl = out.trim().split("\n").pop();
+        }
+        return result;
+    }
+    finally {
+        staged.dispose();
+    }
+}