@intentius/chant 0.124.13 → 0.124.14

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

@@ -0,0 +1,629 @@
+/**
+ * lexiconUpgrade — the upgrade-detection and PR-automation activity for
+ * in-scope lexicons: every lexicon whose plugin declares `upstreamPin` (k8s,
+ * k3s, gcp, docker, gitlab, cedar, sql, ...) plus the rolling ones (aws, azure,
+ * github, fly).
+ *
+ * Classifies the lexicon as pinned or rolling, calls the right check function,
+ * then surfaces the result in the requested mode: report (default), issue, or
+ * pull-request. In pull-request mode it maintains a long-lived branch per
+ * lexicon (`lexicon-upgrade/<lexicon>`), updates the PR in place when the delta
+ * changes, and applies a semver label derived from the surface severity.
+ *
+ * For pinned lexicons in pull-request mode, the PR also bumps the lexicon's
+ * own package.json version according to the semver label (minor → minor bump,
+ * breaking → major bump). Merging the PR carries the version change so
+ * publish-on-merge can ship just that lexicon without a full monorepo release.
+ *
+ * Rolling lexicons (aws, azure, github) drift on their own cadence and are not
+ * version-bumped here — they move to drift-issues per #546.
+ *
+ * Supply-chain note: this activity never executes spec-provided content.
+ * It only reads the artifacts produced by the lexicon's own generate step,
+ * which is called through the lexicon's npm prepack chain.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { bumpForSeverity, bumpPackageJsonVersion } from "../../codegen/version-bump.js";
+import { ghHostEnv } from "./gh-host.js";
+import { restPullRequestForge } from "./forge-pull-request.js";
+import { postOrUpdateGithubIssue } from "./reconcile.js";
+export { bumpPackageJsonVersion };
+const execAsync = promisify(exec);
+// ── Package.json version bumping ──────────────────────────────────────
+/**
+ * Compute a bumped semver string from a current version and a semver label.
+ *
+ * The mapping is 0.x-aware, because promoting to 1.0.0 should signal the
+ * lexicon's own API stability, not track an upstream spec's breaking change:
+ *
+ * - Pre-1.0 (major === 0): "breaking" bumps the minor (0.13.1 → 0.14.0),
+ *   "minor" (additive) bumps the patch (0.13.1 → 0.13.2). Never auto-1.0.0.
+ * - >= 1.0.0: "minor" bumps the minor (1.2.3 → 1.3.0), "breaking" bumps the
+ *   major (1.2.3 → 2.0.0).
+ *
+ * Handles the common "MAJOR.MINOR.PATCH" form. Returns null when the
+ * current version string cannot be parsed as M.m.p.
+ */
+export function computeBumpedVersion(current, label) {
+    // Single source of truth for the 0.x-aware rule lives in core (#616). The
+    // pinned Op's "minor" label maps to an additive surface change; "breaking"
+    // maps straight through.
+    return bumpForSeverity(current, label === "breaking" ? "breaking" : "additive");
+}
+// ── Classification ────────────────────────────────────────────────────
+// Rolling lexicons follow their upstream spec with no version constant, so
+// they are a fixed list. Every other lexicon is pinned when its plugin declares
+// `upstreamPin` (cedar's CEDAR_WASM_VERSION, sql's ClickHouse version, k3s...):
+// discovered at run time, not listed here.
+const ROLLING_LEXICONS = new Set(["aws", "azure", "github", "fly"]);
+/** Return true when the lexicon follows a rolling spec (no pinned constant). */
+export function isRolling(lexicon) {
+    return ROLLING_LEXICONS.has(lexicon);
+}
+/**
+ * Return true when the lexicon's plugin declares an `upstreamPin` (loaded from
+ * `lexiconDir`, else from its installed package), the same discovery
+ * `chant dev pinned-upgrade` does.
+ */
+export async function isPinned(lexicon, lexiconDir, loadPin) {
+    if (isRolling(lexicon))
+        return false;
+    const load = loadPin ?? (async (l, d) => (await import("../../codegen/pinned-upgrade.js")).loadUpstreamPin(l, d));
+    return (await load(lexicon, lexiconDir ?? `${process.cwd()}/lexicons/${lexicon}`)) !== null;
+}
+// ── Semver labeling ───────────────────────────────────────────────────
+/**
+ * Map a surface severity to a semver label for the PR.
+ *
+ * "additive" → "minor"   (new resources/properties added)
+ * "breaking" → "breaking" (removed or changed resources/properties)
+ * "none"     → null       (surface unchanged)
+ */
+export function severityToLabel(severity) {
+    if (severity === "additive")
+        return "minor";
+    if (severity === "breaking")
+        return "breaking";
+    return null;
+}
+// ── Branch / PR naming ────────────────────────────────────────────────
+/** Long-lived branch name for a lexicon upgrade PR. */
+export function upgradeBranchName(lexicon, pin) {
+    return pin ? `lexicon-upgrade/${lexicon}-${pin}` : `lexicon-upgrade/${lexicon}`;
+}
+/** PR title for an upgrade. */
+export function upgradePrTitle(lexicon, from, to, pin) {
+    if (from && to)
+        return `feat(${lexicon}): upgrade ${pin ? `${pin} ` : "spec "}${from} to ${to}`;
+    return `feat(${lexicon}): upgrade to latest spec`;
+}
+// ── Markdown summary builder ──────────────────────────────────────────
+/** Build the PR/issue/report body from the upgrade result data. */
+export function buildUpgradeSummary(opts) {
+    const { lexicon, from, to, deltaText, semverLabel, validationOk, failures = [], manualPin } = opts;
+    // Example validation status (#604): the upgrade check lints the lexicon's
+    // examples (regenLexicon step 6), and an example failure makes validation
+    // fail. Surface it explicitly so the PR / drift issue states example health
+    // instead of leaving it implicit in CI. (The authoritative example *build*
+    // still runs in CI — the pinned PR's test job, and main's continuous build
+    // for rolling lexicons.)
+    const exampleFailures = failures.filter((f) => f.step === "lint" || f.step === "examples");
+    const lines = [`## Lexicon upgrade: ${lexicon}${opts.pin ? ` (${opts.pin})` : ""}`];
+    if (from)
+        lines.push(``, `**From:** \`${from}\`  **To:** \`${to ?? "latest"}\``);
+    if (semverLabel)
+        lines.push(`**Semver label:** \`${semverLabel}\``);
+    lines.push(exampleFailures.length > 0
+        ? `**Examples:** ⚠️ ${exampleFailures.length} check(s) failing — see Validation failures below`
+        : `**Examples:** lint clean`);
+    lines.push(``);
+    if (manualPin) {
+        lines.push(`### Manual pin bump`);
+        lines.push(``);
+        lines.push(`This pin cannot be rewritten automatically, so nothing was edited or regenerated. ` +
+            `Edit \`${manualPin.file}\`: ${manualPin.instructions}`);
+        lines.push(``);
+        return lines.join("\n");
+    }
+    if (!validationOk) {
+        lines.push(`### Validation failures`);
+        lines.push(``);
+        lines.push(`Regen or validation did not pass. Review the failures before merging.`);
+        for (const f of failures) {
+            lines.push(``, `**Step: ${f.step}**`, "```", f.output.slice(0, 2000), "```");
+        }
+        lines.push(``);
+    }
+    if (deltaText) {
+        lines.push(`### Surface delta`);
+        lines.push(``);
+        lines.push(deltaText);
+        lines.push(``);
+    }
+    else if (validationOk) {
+        lines.push(`No surface delta detected.`);
+    }
+    // #616: rolling lexicons carry no version pin, so accepting drift must also
+    // bump the package version — otherwise skip-if-unchanged strands the new
+    // surface at publish time. Spell out the `--bump` re-baseline in the issue.
+    if (deltaText && isRolling(lexicon)) {
+        lines.push(`### Accepting this drift`);
+        lines.push(``);
+        lines.push(`Re-baseline and bump the version in one step (bump matches the drift severity, 0.x-aware):`);
+        lines.push(``, "```", `chant dev surface-diff lexicons/${lexicon} --update-snapshot --bump`, "```");
+        lines.push(``);
+    }
+    return lines.join("\n");
+}
+// ── Shell helpers ─────────────────────────────────────────────────────
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+const defaultGh = async (cmd, opts) => execAsync(cmd, { ...opts });
+/**
+ * `run`, with the forge's host handed to every `gh` call that brings no
+ * environment of its own (#3780). `gh pr view`, `gh pr edit`, `gh pr create`,
+ * `gh label create` and the ambient `gh issue create` name no host, so on
+ * GitHub Enterprise Server or Forgejo they would not reach the job's own
+ * forge; see `./gh-host.ts`. A call that passes an `env` (the issue recipe's
+ * full-URL `gh api` calls, #2320) already names its host and keeps it. The
+ * environment is resolved once, on the first `gh` call. `git` calls pass
+ * through untouched.
+ */
+export function withGhHost(run, resolve = () => ghHostEnv(process.env)) {
+    let env;
+    return async (cmd, opts) => {
+        if (!cmd.startsWith("gh ") || opts?.env)
+            return run(cmd, opts);
+        env ?? (env = resolve());
+        return run(cmd, { ...opts, env: await env });
+    };
+}
+/**
+ * The hidden marker that makes this lexicon's upgrade-status issue findable
+ * across re-runs (#2297): written as the issue body's first line, matched by
+ * `startswith` — the same recipe reconcile.ts's `issueMarker` names for a
+ * reconcile finding, kept as its own function because the two activities own
+ * different issues. Keyed on `lexicon`, not on the validation outcome: a
+ * lexicon has one upgrade-status issue that flips between "validation
+ * failed" and "upgrade ready" as reality changes, rather than a second issue
+ * for the other outcome. `lexicon` is a closed set of known identifiers
+ * (see `SupportedLexicon`), so unlike `issueMarker` this needs no slugifying.
+ */
+export function lexiconUpgradeIssueMarker(lexicon) {
+    return `<!-- chant-lexicon-upgrade:${lexicon} -->`;
+}
+/**
+ * Open or update this lexicon's upgrade-status issue (#2297). On a GitHub
+ * Actions or Forgejo Actions job (`GITHUB_REPOSITORY` set) this is
+ * `postOrUpdateGithubIssue`'s sticky recipe from reconcile.ts: find the OPEN
+ * issue already carrying this lexicon's marker, edit it, open one only when
+ * there is none — see that function's own doc comment for the search
+ * mechanism and the close decision (never closed here either). Outside any
+ * known CI job, falls back to `gh`'s own ambient `gh issue create`, still
+ * marker-prefixed so a later CI run finds and edits it instead of opening a
+ * second one.
+ */
+async function postLexiconIssue(lexicon, title, body, gh) {
+    const marker = lexiconUpgradeIssueMarker(lexicon);
+    const repo = process.env.GITHUB_REPOSITORY;
+    if (repo) {
+        // `postOrUpdateGithubIssue` resolves the token itself and hands it back
+        // through `gh`'s second argument (#2320), so this runner has to forward
+        // what it is given rather than dropping it — see `GhRunner`.
+        return postOrUpdateGithubIssue(repo, marker, title, body, gh);
+    }
+    const { stdout } = await gh(`gh issue create --title ${shellQuote(title)} --body ${shellQuote(`${marker}\n\n${body}`)}`);
+    return stdout.trim();
+}
+// ── PR idempotency helpers ────────────────────────────────────────────
+/**
+ * Check whether an open PR exists for the given branch.
+ * Returns the PR URL, or null if none.
+ */
+async function openPrUrl(branch, gh, forge) {
+    if (forge)
+        return (await forge.findPullRequest(branch))?.url ?? null;
+    try {
+        const { stdout } = await gh(`gh pr view ${shellQuote(branch)} --json url,state --jq 'select(.state=="OPEN") | .url'`);
+        const url = stdout.trim();
+        return url || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the body of the open PR for `branch`, if any.
+ * Returns null when there is no open PR or gh is unavailable.
+ */
+async function currentPrBody(branch, gh, forge) {
+    if (forge)
+        return (await forge.findPullRequest(branch))?.body.trim() || null;
+    try {
+        const { stdout } = await gh(`gh pr view ${shellQuote(branch)} --json body,state --jq 'select(.state=="OPEN") | .body'`);
+        const body = stdout.trim();
+        return body || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Apply or ensure a label exists on the repo, then add it to the PR.
+ * Best-effort — never throws.
+ */
+async function ensureLabelOnPr(branch, label, gh) {
+    try {
+        const color = label === "breaking" ? "B60205" : "0075CA";
+        await gh(`gh label create ${shellQuote(label)} --color ${shellQuote(color)} --force`).catch(() => { });
+        await gh(`gh pr edit ${shellQuote(branch)} --add-label ${shellQuote(label)}`);
+    }
+    catch {
+        // Best-effort
+    }
+}
+// ── Real check function loaders ───────────────────────────────────────
+let _realCheckPinned = null;
+let _realCheckRolling = null;
+let _realApplyBump = null;
+async function getRealCheckPinned() {
+    if (!_realCheckPinned) {
+        const mod = await import("../../codegen/pinned-upgrade.js");
+        _realCheckPinned = (opts) => mod.checkPinnedUpgrades(opts);
+    }
+    return _realCheckPinned;
+}
+async function getRealCheckRolling() {
+    if (!_realCheckRolling) {
+        const mod = await import("../../codegen/rolling-upgrade.js");
+        _realCheckRolling = (opts) => mod.checkRollingUpgrade(opts);
+    }
+    return _realCheckRolling;
+}
+async function getRealApplyBump() {
+    if (!_realApplyBump) {
+        const mod = await import("../../codegen/pinned-upgrade.js");
+        _realApplyBump = (lexicon, lexiconDir, newVersion, pin) => mod.applyPinnedVersionBump(lexicon, lexiconDir, newVersion, pin);
+    }
+    return _realApplyBump;
+}
+// ── Main activity ─────────────────────────────────────────────────────
+/**
+ * Run the lexicon upgrade check for one lexicon and surface the result.
+ *
+ * Pinned lexicons (any whose plugin declares `upstreamPin`):
+ *   Calls checkPinnedUpgrade. A PR is opened only when hasUpgrade=true AND
+ *   validation passed. Validation failures produce a report or issue.
+ *   A pin that moves with other constants (`alsoMoves`, sql's version plus
+ *   digest) is report-only: the summary names the newer version and the
+ *   manual step, and no branch, bump or PR is made.
+ *
+ * Rolling lexicons (aws, azure, github):
+ *   Calls checkRollingUpgrade. A PR is opened only when the surface changed
+ *   AND validation passed. Surface unchanged = no action.
+ *
+ * In pull-request mode:
+ *   - Branch: lexicon-upgrade/<lexicon> (long-lived, one per lexicon).
+ *   - Idempotent: if the open PR body matches the new summary, skip re-push.
+ *   - Semver label: "minor" (additive) or "breaking" (changed/removed).
+ *   - Validation failure falls back to issue mode.
+ *
+ * In issue mode (#2297): one OPEN issue per lexicon, found by a hidden
+ * marker and edited in place on every re-run — the same sticky recipe
+ * reconcile.ts's `issue` mode uses, via the shared `postOrUpdateGithubIssue`.
+ * Never closed by this activity; see that function's doc comment for the
+ * close decision, which applies here unchanged.
+ *
+ * Never auto-merges or auto-publishes.
+ */
+export async function lexiconUpgrade(args) {
+    const { lexicon, mode = "report", _gh: rawGh = defaultGh, } = args;
+    const gh = withGhHost(rawGh);
+    const lexiconDir = args.lexiconDir ?? `${process.cwd()}/lexicons/${lexicon}`;
+    // ── 1. Run the appropriate check ──────────────────────────────────
+    let hasUpgrade;
+    let deltaText;
+    let severity;
+    let validationOk;
+    let failures = [];
+    let from;
+    let to;
+    let freshSnapshotJson = null;
+    // An injected check stands in for the whole pinned check, so discovery runs
+    // only on the real path.
+    const pinned = !isRolling(lexicon) && (args._checkPinned ? true : await isPinned(lexicon, lexiconDir, args._loadPin));
+    let manualPin;
+    let pinLabel;
+    let summaryOverride;
+    if (pinned) {
+        const checkPinned = args._checkPinned ?? (await getRealCheckPinned());
+        const raw = await checkPinned({ lexiconDir, lexicon, ...(args.pin ? { pin: args.pin } : {}) });
+        const results = Array.isArray(raw) ? raw : [raw];
+        const multi = results.length > 1;
+        // The pin the rest of the flow (validation, bump, PR) acts on: the first
+        // one that has a rewritable upgrade, else the first with any finding.
+        // A pin with `alsoMoves` (manualPin) is report-only, so it never leads.
+        const rewritable = (r) => r.hasUpgrade && !r.manualPin && !r.fetchError;
+        const result = results.find(rewritable) ?? results.find((r) => r.hasUpgrade || r.fetchError) ?? results[0];
+        if (multi) {
+            pinLabel = rewritable(result) ? result.pin : undefined;
+            const sections = results.map((r) => buildUpgradeSummary({
+                lexicon,
+                pin: r.pin,
+                from: r.from,
+                to: r.to,
+                deltaText: r.validation?.deltaText ?? "",
+                semverLabel: severityToLabel(r.validation?.severity ?? "none"),
+                validationOk: r.fetchError ? false : (r.validation?.ok ?? true),
+                failures: r.fetchError
+                    ? [{ step: "upstream-fetch", output: r.fetchError }]
+                    : (r.validation?.failures ?? []).map((f) => ({ step: f.step, output: f.output })),
+                manualPin: r.manualPin,
+            }));
+            const others = results.filter((r) => r !== result && rewritable(r));
+            if (others.length > 0) {
+                const names = others.map((r) => r.pin).join(", ");
+                sections.push("More than one pin has an upgrade this run can bump. This run acts on " + result.pin +
+                    "; run it again with pin set to each of the others (" + names + ").");
+            }
+            summaryOverride = sections.join("\n\n");
+        }
+        if (result.fetchError) {
+            const summary = summaryOverride ??
+                buildUpgradeSummary({
+                    lexicon,
+                    from: result.from,
+                    to: result.to,
+                    deltaText: "",
+                    semverLabel: null,
+                    validationOk: false,
+                    failures: [{ step: "upstream-fetch", output: result.fetchError }],
+                });
+            return {
+                lexicon,
+                mode,
+                hasUpgrade: false,
+                deltaText: "",
+                semverLabel: null,
+                summary,
+                validationOk: false,
+            };
+        }
+        hasUpgrade = results.some((r) => r.hasUpgrade && !r.fetchError);
+        from = result.from;
+        to = result.to;
+        manualPin = multi ? (rewritable(result) ? undefined : result.manualPin) : result.manualPin;
+        severity = result.validation?.severity ?? "none";
+        deltaText = result.validation?.deltaText ?? "";
+        validationOk = result.validation?.ok ?? true;
+        failures = (result.validation?.failures ?? []).map((f) => ({ step: f.step, output: f.output }));
+        if (result.validation?.freshSnapshot) {
+            const { serializeSnapshot } = await import("../../codegen/surface-snapshot.js");
+            freshSnapshotJson = serializeSnapshot(result.validation.freshSnapshot);
+        }
+    }
+    else if (isRolling(lexicon)) {
+        const checkRolling = args._checkRolling ?? (await getRealCheckRolling());
+        const result = await checkRolling({ lexiconDir });
+        hasUpgrade = result.hasUpgrade;
+        severity = result.severity;
+        deltaText = result.deltaText;
+        validationOk = result.validationOk;
+        failures = (result.failures ?? []).map((f) => ({ step: f.step, output: f.output }));
+        if (result.freshSnapshot) {
+            const { serializeSnapshot } = await import("../../codegen/surface-snapshot.js");
+            freshSnapshotJson = serializeSnapshot(result.freshSnapshot);
+        }
+    }
+    else {
+        throw new Error(`Lexicon "${lexicon}" is not supported by LexiconUpgradeOp. ` +
+            `Supported: the rolling lexicons (${[...ROLLING_LEXICONS].join(", ")}) and any lexicon whose plugin declares upstreamPin.`);
+    }
+    const semverLabel = severityToLabel(severity);
+    const summary = summaryOverride ??
+        buildUpgradeSummary({
+            lexicon,
+            from,
+            to,
+            deltaText,
+            semverLabel,
+            validationOk,
+            failures,
+            manualPin,
+        });
+    // ── 2. No upgrade ─────────────────────────────────────────────────
+    if (!hasUpgrade) {
+        return {
+            lexicon,
+            mode,
+            hasUpgrade: false,
+            deltaText,
+            semverLabel: null,
+            summary,
+            validationOk,
+        };
+    }
+    // ── 3. Validation failure: surface as report or issue, never PR ───
+    if (!validationOk) {
+        const effectiveMode = mode === "pull-request" ? "issue" : mode;
+        if (effectiveMode === "issue") {
+            const title = `chore(${lexicon}): spec upgrade validation failed`;
+            const issueUrl = await postLexiconIssue(lexicon, title, summary, gh);
+            return {
+                lexicon,
+                mode,
+                hasUpgrade: true,
+                deltaText,
+                semverLabel,
+                issueUrl,
+                summary,
+                validationOk: false,
+            };
+        }
+        return {
+            lexicon,
+            mode,
+            hasUpgrade: true,
+            deltaText,
+            semverLabel,
+            summary,
+            validationOk: false,
+        };
+    }
+    // ── 4. Upgrade ready: surface according to mode ───────────────────
+    const title = upgradePrTitle(lexicon, from, to, pinLabel);
+    // #546: rolling lexicons have no version pin, so a "pull-request" would only
+    // refresh the baseline snapshot — low signal, no build-output change. Surface
+    // rolling drift as an issue instead; re-baselining stays a deliberate
+    // maintainer action (`chant dev surface-diff <lexicon> --update-snapshot --bump`).
+    // Pinned lexicons keep opening version-bump PRs.
+    // A pin that moves with other constants cannot be bumped here, so it is
+    // report-only whatever the mode.
+    const effectiveMode = manualPin
+        ? "report"
+        : mode === "pull-request" && isRolling(lexicon)
+            ? "issue"
+            : mode;
+    if (effectiveMode === "report") {
+        return {
+            lexicon,
+            mode: effectiveMode,
+            hasUpgrade: true,
+            deltaText,
+            semverLabel,
+            summary,
+            validationOk: true,
+        };
+    }
+    if (effectiveMode === "issue") {
+        const issueUrl = await postLexiconIssue(lexicon, title, summary, gh);
+        return {
+            lexicon,
+            mode: effectiveMode,
+            hasUpgrade: true,
+            deltaText,
+            semverLabel,
+            issueUrl,
+            summary,
+            validationOk: true,
+        };
+    }
+    // ── 5. pull-request mode: idempotent branch + PR management ──────
+    const branch = upgradeBranchName(lexicon, pinLabel);
+    // Idempotency check: if the open PR already has this summary, nothing changed.
+    // Compare trimmed — gh/git round-trips can alter trailing whitespace.
+    // `gh pr` speaks GraphQL, which Forgejo does not serve: a Forgejo or
+    // GitLab job finds, opens and labels the pull request over REST (#3798).
+    const forge = args._forge !== undefined ? (args._forge ?? undefined) : await restPullRequestForge(process.env);
+    const existingPrBody = await currentPrBody(branch, gh, forge);
+    if (existingPrBody !== null && existingPrBody.trim() === summary.trim()) {
+        const existingUrl = await openPrUrl(branch, gh, forge);
+        return {
+            lexicon,
+            mode,
+            hasUpgrade: true,
+            deltaText,
+            semverLabel,
+            prUrl: existingUrl ?? undefined,
+            summary,
+            validationOk: true,
+        };
+    }
+    // Reset/create the long-lived branch from main and commit the changes.
+    // All git shell-outs go through the injectable `gh` runner (which defaults to
+    // execAsync) so tests can mock them — a test must never touch the real repo
+    // or push to origin.
+    await gh(`git fetch origin main`);
+    await gh(`git branch -f ${shellQuote(branch)} origin/main`).catch(async () => {
+        await gh(`git branch ${shellQuote(branch)} origin/main`);
+    });
+    // Save current branch, switch to upgrade branch.
+    const { stdout: currentBranch } = await gh(`git rev-parse --abbrev-ref HEAD`);
+    const savedBranch = currentBranch.trim();
+    await gh(`git stash --include-untracked`).catch(() => { });
+    try {
+        await gh(`git checkout ${shellQuote(branch)}`);
+        // For pinned lexicons: apply the spec version bump permanently on this branch.
+        if (pinned && to) {
+            const applyBump = args._applyBump ?? (await getRealApplyBump());
+            const { filePath } = await (pinLabel ? applyBump(lexicon, lexiconDir, to, pinLabel) : applyBump(lexicon, lexiconDir, to));
+            await gh(`git add ${shellQuote(filePath)}`).catch(() => { });
+            // Bump the lexicon's package.json version so merging this PR causes
+            // publish-on-merge to ship exactly this lexicon (minor → minor bump,
+            // breaking → major bump). Rolling lexicons are excluded — they use
+            // drift-issues (#546) and do not pin to a version constant.
+            if (semverLabel) {
+                const pkgJsonPath = join(lexiconDir, "package.json");
+                const raw = readFileSync(pkgJsonPath, "utf-8");
+                const pkg = JSON.parse(raw);
+                const currentVersion = pkg.version ?? "0.0.0";
+                const bumpedVersion = computeBumpedVersion(currentVersion, semverLabel);
+                if (bumpedVersion) {
+                    const doBump = args._bumpPackageVersion ?? bumpPackageJsonVersion;
+                    doBump(pkgJsonPath, bumpedVersion);
+                    await gh(`git add ${shellQuote(pkgJsonPath)}`).catch(() => { });
+                }
+            }
+        }
+        // Write and stage the fresh surface snapshot.
+        if (freshSnapshotJson) {
+            const { SNAPSHOT_FILENAME } = await import("../../codegen/lexicon-regen.js");
+            const snapshotPath = join(lexiconDir, SNAPSHOT_FILENAME);
+            writeFileSync(snapshotPath, freshSnapshotJson, "utf-8");
+            await gh(`git add ${shellQuote(snapshotPath)}`).catch(() => { });
+        }
+        await gh(`git commit -m ${shellQuote(title)} --allow-empty`);
+        // Push to origin — force-with-lease, then fall back to force on first push.
+        await gh(`git push -u origin ${shellQuote(branch)} --force-with-lease`).catch(async () => {
+            await gh(`git push -u origin ${shellQuote(branch)} --force`);
+        });
+        // Open or update the PR.
+        let prUrl;
+        const open = forge ? await forge.findPullRequest(branch) : undefined;
+        const existingUrl = forge ? null : await openPrUrl(branch, gh);
+        if (forge) {
+            let pr = open;
+            if (pr) {
+                const edited = await forge.editPullRequest(pr.number, { title, body: summary });
+                prUrl = edited?.url ?? pr.url ?? "";
+            }
+            else {
+                pr = await forge.openPullRequest({ head: branch, base: "main", title, body: summary });
+                prUrl = pr.url ?? "";
+            }
+            // Best-effort, as below. Forgejo adds only a label the repository
+            // already has; GitHub and GitLab make one.
+            if (semverLabel)
+                await forge.addLabels(pr.number, [semverLabel]).catch(() => { });
+        }
+        else if (existingUrl) {
+            await gh(`gh pr edit ${shellQuote(branch)} --title ${shellQuote(title)} --body ${shellQuote(summary)}`);
+            prUrl = existingUrl;
+        }
+        else {
+            const { stdout } = await gh(`gh pr create --title ${shellQuote(title)} --body ${shellQuote(summary)} --head ${shellQuote(branch)} --base main`);
+            prUrl = stdout.trim();
+        }
+        if (semverLabel && !forge) {
+            await ensureLabelOnPr(branch, semverLabel, gh);
+        }
+        return {
+            lexicon,
+            mode,
+            hasUpgrade: true,
+            deltaText,
+            semverLabel,
+            prUrl,
+            summary,
+            validationOk: true,
+        };
+    }
+    finally {
+        await gh(`git checkout ${shellQuote(savedBranch)}`).catch(() => { });
+        await gh(`git stash pop`).catch(() => { });
+    }
+}