feat: git-based version allocator when the PR queue is unreachable (#2545)

When the host query (gh/glab) failed, gstack-next-version returned offline:true with an EMPTY claim set, and /ship's documented fallback was local BUMP_LEVEL arithmetic. Local arithmetic cannot see a sibling's claim, so the fallback allocated a version another open PR already held — observed in a downstream repo where two merged PRs both read v0.1.57.0 (and an audit found four such duplicate pairs over three weeks). New fetchGitClaimed() degrades the QUEUE VIEW without degrading the ALLOCATION: git already knows what the API was asked for. It reads every remote-tracking branch's pinned version file (through extractVersion, so JSON version-paths resolve on remote refs too and each branch's own digit width is preserved) plus the versions already shipped in the base's last 400 commit subjects (3- or 4-digit; the cap announces itself in warnings when it truncates). The fallback runs only when the host told us nothing — the online path is untouched — and the output gains a load-bearing `fallback: "git" | null` field that /ship can branch on, plus explicit warnings for both the recovered-from-git and the nothing-found cases. Tests: end-to-end stub-gh offline contract (fallback:'git' + a valid version + the warning), sibling-claim discovery from remote-tracking refs, the pick advancing past the sibling's claim, shipped-subject scanning, JSON version-path claims on remote refs, and non-repo degradation to a warning (45 pass in test/gstack-next-version.test.ts). Re-derived from PR #2545 by @CarringtonCreative under the wave plan's version-tooling end-state spec; the PR's own VERSION/CHANGELOG stamping is stripped (release stamping happens at /ship time, not per commit). Co-authored-by: Carrington Dennis <carrdenn3@gmail.com> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-09 14:38:59 +02:00 · 2026-08-16 10:02:32 -07:00
parent 7b5fdab8cb
commit da0e28e686
2 changed files with 266 additions and 1 deletions
@@ -72,6 +72,7 @@ type Output = {
  bump: Bump;
  host: "github" | "gitlab" | "unknown";
  offline: boolean;
+  fallback: "git" | null;
  claimed: ClaimedPR[];
  siblings: Sibling[];
  active_siblings: Sibling[];
@@ -445,6 +446,84 @@ function autoDetectExcludePR(): number | null {
  return Number.isFinite(n) && n > 0 ? n : null;
 }

+// ── git-only fallback (#2545) ────────────────────────────────────────────
+//
+// When the host query fails this util used to return `offline:true` with an
+// EMPTY claim set, and /ship's instruction was "fall back to local BUMP_LEVEL
+// arithmetic". Local arithmetic cannot see a sibling's claim, so the fallback
+// allocated a version another open PR already held.
+//
+// That is not hypothetical. On 2026-08-12 in a downstream repo, `gh pr list`
+// failed during a ship, this util reported offline, the bump fell back to
+// local arithmetic, and 0.1.57.0 was allocated to a second PR while an open
+// one already claimed it — both merged, and main carries two commits reading
+// v0.1.57.0. Auditing that repo's history found FOUR such pairs going back
+// three weeks, so the silent fallback had been mis-allocating for a while.
+//
+// Git already knows what the API was asked for. Remote-tracking refs carry
+// each branch's VERSION file, and the base's own history records every version
+// already shipped. Neither needs a token, a network round-trip, or a working
+// `gh`. So "offline" degrades the QUEUE VIEW (no PR numbers, no draft status)
+// without degrading the ALLOCATION.
+function fetchGitClaimed(
+  base: string,
+  versionPath: string,
+  warnings: string[],
+): ClaimedPR[] {
+  const claims: ClaimedPR[] = [];
+
+  // 1. Every remote-tracking branch's VERSION file. These are the open PRs'
+  //    branches, whether or not the API can be reached to enumerate them.
+  //    Read through extractVersion so a JSON version-path (#2501) resolves on
+  //    remote refs too, and the branch's own width is preserved in the claim.
+  const refs = runCommand("git", [
+    "for-each-ref",
+    "--format=%(refname:short)",
+    "refs/remotes",
+  ]);
+  if (refs.ok) {
+    const baseShort = base.replace(/^origin\//, "");
+    for (const ref of refs.stdout.split("\n").map((r) => r.trim()).filter(Boolean)) {
+      if (ref.endsWith("/HEAD")) continue;
+      if (ref === base || ref.replace(/^origin\//, "") === baseShort) continue;
+      const show = runCommand("git", ["show", `${ref}:${versionPath}`]);
+      if (!show.ok) continue;
+      const raw = extractVersion(show.stdout, versionPath);
+      if (!raw || !parseVersion(raw)) continue;
+      claims.push({ pr: 0, branch: ref, version: raw });
+    }
+  } else {
+    warnings.push("git for-each-ref failed; branch claims unavailable");
+  }
+
+  // 2. Versions already shipped, read from the base's commit subjects. Catches
+  //    the case the VERSION file cannot: a number that merged and was then
+  //    re-picked. Bounded, and it says so rather than implying full history.
+  const SUBJECT_SCAN = 400;
+  const log = runCommand("git", ["log", `-n${SUBJECT_SCAN}`, "--format=%s", base]);
+  if (log.ok) {
+    for (const subject of log.stdout.split("\n")) {
+      const m = subject.trim().match(/^v(\d+\.\d+\.\d+(?:\.\d+)?)\b/);
+      if (!m) continue;
+      if (!parseVersion(m[1])) continue;
+      claims.push({ pr: 0, branch: `(shipped on ${base})`, version: m[1] });
+    }
+    // A cap that does not announce itself reads as "checked all history".
+    // Only fires when the log came back exactly full, which is the only
+    // observable signal that older commits went unread.
+    if (log.stdout.trim().split("\n").length >= SUBJECT_SCAN) {
+      warnings.push(
+        `shipped-version scan stopped at ${SUBJECT_SCAN} commits on ${base}; ` +
+          `a version shipped before that is not counted as claimed`,
+      );
+    }
+  } else {
+    warnings.push(`git log ${base} failed; shipped-version scan unavailable`);
+  }
+
+  return claims;
+}
+
 async function main() {
  const args = parseArgs(process.argv.slice(2));
  if (args.help) {
@@ -485,6 +564,28 @@ async function main() {
    warnings.push("host unknown; queue-awareness unavailable");
  }

+  // Degraded host query → fall back to git, which needs no API. Additive: it
+  // only runs when the host told us nothing, so the online path is untouched.
+  let fallback: "git" | null = null;
+  if (offline || host === "unknown") {
+    const gitClaims = fetchGitClaimed(args.base, versionPath, warnings);
+    if (gitClaims.length) {
+      claimed = [...claimed, ...gitClaims];
+      fallback = "git";
+      warnings.push(
+        `host queue unavailable — allocated from git instead ` +
+          `(${gitClaims.length} claim(s) from remote refs + shipped subjects). ` +
+          `PR numbers and draft status are unavailable, but the version is safe.`,
+      );
+    } else {
+      warnings.push(
+        "host queue unavailable AND git found no claims — the pick rests on " +
+          "the base VERSION alone. Verify no sibling branch holds it before " +
+          "shipping.",
+      );
+    }
+  }
+
  // Only count PRs that actually bumped VERSION past base as real "claims".
  // A PR whose VERSION equals base's VERSION hasn't claimed anything.
  const realClaims = claimed.filter((c) => {
@@ -522,6 +623,7 @@ async function main() {
    bump: args.bump,
    host,
    offline,
+    fallback,
    claimed: realClaims,
    siblings,
    active_siblings: activeSiblings,
@@ -535,7 +637,7 @@ async function main() {
 // from lib/version-source so existing importers of this module keep working
 // unchanged.
 export { parseVersion, fmtVersion, bumpVersion, cmpVersion, versionWidth, extractVersion };
-export { pickNextSlot, markActiveSiblings, resolveVersionPath };
+export { pickNextSlot, markActiveSiblings, resolveVersionPath, fetchGitClaimed };

 // Only run main() when invoked as a script, not when imported by tests.
 if (import.meta.main) {
@@ -18,6 +18,7 @@ import {
  pickNextSlot,
  markActiveSiblings,
  resolveVersionPath,
+  fetchGitClaimed,
 } from "../bin/gstack-next-version";

 describe("parseVersion", () => {
@@ -379,6 +380,168 @@ describe("default-base detection (no --base)", () => {

 // Integration smoke — only runs if gh is available and authenticated. Confirms
 // the CLI executes end-to-end against real APIs without crashing.
+describe("offline output contract (what /ship branches on, #2545)", () => {
+  // /ship's Step 12 reads `.fallback` to decide whether the pick is
+  // trustworthy when the PR queue is unreachable. That field is therefore
+  // load-bearing prose-to-code coupling: if it silently stopped being emitted,
+  // /ship would read undefined, treat the run as fully online, and lose the
+  // "verify no sibling holds it" prompt. Asserted end-to-end with a stub `gh`
+  // that always fails, which is what an expired token or an offline laptop
+  // looks like from here.
+  test("emits fallback:'git' and still returns a version when gh fails", async () => {
+    const stubDir = mkdtempSync(join(tmpdir(), "nextver-stubgh-"));
+    writeFileSync(join(stubDir, "gh"), "#!/bin/sh\nexit 1\n", { mode: 0o755 });
+    const proc = Bun.spawnSync(
+      ["bun", "run", "./bin/gstack-next-version", "--base", "main",
+       "--bump", "patch", "--current-version", "1.0.0.0", "--workspace-root", "null"],
+      { env: { ...process.env, PATH: `${stubDir}:${process.env.PATH}` } },
+    );
+    rmSync(stubDir, { recursive: true, force: true });
+    const out = JSON.parse(new TextDecoder().decode(proc.stdout));
+    expect(out.offline).toBe(true);
+    expect(out.fallback).toBe("git");
+    // The whole point: degraded queue view, NOT a degraded allocation.
+    expect(out.version).toMatch(/^\d+\.\d+\.\d+\.\d+$/);
+    expect(out.warnings.join(" ")).toContain("allocated from git");
+  }, 30000);
+
+  test("online runs leave fallback null", async () => {
+    const proc = Bun.spawnSync(
+      ["bun", "run", "./bin/gstack-next-version", "--base", "main",
+       "--bump", "patch", "--current-version", "1.0.0.0", "--workspace-root", "null"],
+    );
+    const out = JSON.parse(new TextDecoder().decode(proc.stdout));
+    if (out.offline) return; // no network / no gh auth on this machine: nothing to assert
+    expect(out.fallback).toBe(null);
+  }, 30000);
+});
+
+describe("fetchGitClaimed (offline allocation — the anti-duplicate fallback, #2545)", () => {
+  // Why this exists: when `gh pr list` failed, the util returned
+  // `offline:true` with an EMPTY claim set and /ship's instruction was
+  // "fall back to local BUMP_LEVEL arithmetic". Local arithmetic cannot see a
+  // sibling's claim, so it re-allocated a version an open PR already held.
+  // That produced two commits reading v0.1.57.0 on a downstream repo's main
+  // (plus three earlier pairs found in the same audit). Git knows what the API
+  // was asked for, so offline now degrades the QUEUE VIEW, not the ALLOCATION.
+  function git(cwd: string, ...args: string[]) {
+    return Bun.spawnSync(["git", "-c", "user.email=t@t", "-c", "user.name=t", ...args], { cwd });
+  }
+
+  function fixture(): string {
+    const dir = mkdtempSync(join(tmpdir(), "nextver-git-"));
+    git(dir, "init", "-q", "-b", "main");
+    writeFileSync(join(dir, "VERSION"), "0.1.66.0\n");
+    git(dir, "add", "-A");
+    git(dir, "commit", "-qm", "v0.1.66.0 chore: base");
+    // A sibling PR branch that already claimed 0.1.67.0, present as a fetched
+    // remote-tracking ref — which is the shape a real `git fetch` leaves.
+    git(dir, "checkout", "-q", "-b", "sibling");
+    writeFileSync(join(dir, "VERSION"), "0.1.67.0\n");
+    git(dir, "add", "-A");
+    git(dir, "commit", "-qm", "v0.1.67.0 feat: sibling claimed this");
+    const sha = new TextDecoder().decode(git(dir, "rev-parse", "HEAD").stdout).trim();
+    git(dir, "checkout", "-q", "main");
+    git(dir, "update-ref", "refs/remotes/origin/sibling", sha);
+    git(dir, "update-ref", "refs/remotes/origin/main", "main");
+    return dir;
+  }
+
+  test("finds a sibling branch's claim from remote-tracking refs", () => {
+    const dir = fixture();
+    const cwd = process.cwd();
+    try {
+      process.chdir(dir);
+      const warnings: string[] = [];
+      const claims = fetchGitClaimed("main", "VERSION", warnings);
+      const versions = claims.map((c) => c.version);
+      expect(versions).toContain("0.1.67.0");
+    } finally {
+      process.chdir(cwd);
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("the sibling's claim is enough to push the pick past it", () => {
+    // The end-to-end consequence: with the claim visible, pickNextSlot lands
+    // on 0.1.68.0 instead of re-issuing the sibling's 0.1.67.0.
+    const dir = fixture();
+    const cwd = process.cwd();
+    try {
+      process.chdir(dir);
+      const claims = fetchGitClaimed("main", "VERSION", []);
+      const base = parseVersion("0.1.66.0")!;
+      const claimed = claims
+        .map((c) => parseVersion(c.version))
+        .filter((v): v is [number, number, number, number] => v !== null)
+        .filter((v) => cmpVersion(v, base) > 0);
+      const { version } = pickNextSlot(base, claimed, "patch");
+      expect(fmtVersion(version)).toBe("0.1.68.0");
+    } finally {
+      process.chdir(cwd);
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("also reports versions already shipped on the base", () => {
+    // Catches a number that merged and was then re-picked — the VERSION file
+    // alone cannot see that, because it only holds the newest value.
+    const dir = fixture();
+    const cwd = process.cwd();
+    try {
+      process.chdir(dir);
+      const claims = fetchGitClaimed("main", "VERSION", []);
+      const shipped = claims.filter((c) => c.branch.startsWith("(shipped on"));
+      expect(shipped.map((c) => c.version)).toContain("0.1.66.0");
+    } finally {
+      process.chdir(cwd);
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("reads a JSON version-path on remote refs and keeps the branch's own width", () => {
+    // A sibling repo pinned to frontend/package.json (#2501): its claim is the
+    // JSON .version, not the whitespace-stripped file bytes.
+    const dir = mkdtempSync(join(tmpdir(), "nextver-gitjson-"));
+    const cwd = process.cwd();
+    try {
+      git(dir, "init", "-q", "-b", "main");
+      mkdirSync(join(dir, "frontend"), { recursive: true });
+      writeFileSync(join(dir, "frontend", "package.json"), JSON.stringify({ name: "f", version: "0.99.2" }, null, 2) + "\n");
+      git(dir, "add", "-A");
+      git(dir, "commit", "-qm", "base");
+      git(dir, "checkout", "-q", "-b", "sibling");
+      writeFileSync(join(dir, "frontend", "package.json"), JSON.stringify({ name: "f", version: "0.99.3" }, null, 2) + "\n");
+      git(dir, "add", "-A");
+      git(dir, "commit", "-qm", "sibling claim");
+      const sha = new TextDecoder().decode(git(dir, "rev-parse", "HEAD").stdout).trim();
+      git(dir, "checkout", "-q", "main");
+      git(dir, "update-ref", "refs/remotes/origin/sibling", sha);
+      process.chdir(dir);
+      const claims = fetchGitClaimed("main", "frontend/package.json", []);
+      expect(claims.map((c) => c.version)).toContain("0.99.3");
+    } finally {
+      process.chdir(cwd);
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("degrades to a warning, never a throw, outside a git repo", () => {
+    const dir = mkdtempSync(join(tmpdir(), "nextver-nogit-"));
+    const cwd = process.cwd();
+    try {
+      process.chdir(dir);
+      const warnings: string[] = [];
+      const claims = fetchGitClaimed("main", "VERSION", warnings);
+      expect(claims).toEqual([]);
+      expect(warnings.length).toBeGreaterThan(0);
+    } finally {
+      process.chdir(cwd);
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
 describe("integration (smoke)", () => {
  // Bumps timeout to 30s — the test spawns a real `bun run` subprocess that
  // does a `gh pr list` against the live GitHub API to inspect claimed slots.