From da0e28e6866938a2c31177a459578bc2553a6fa5 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sun, 16 Aug 2026 09:34:36 -0700 Subject: [PATCH] feat: git-based version allocator when the PR queue is unreachable (#2545) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Co-Authored-By: Claude Fable 5 --- bin/gstack-next-version | 104 +++++++++++++++++++- test/gstack-next-version.test.ts | 163 +++++++++++++++++++++++++++++++ 2 files changed, 266 insertions(+), 1 deletion(-) diff --git a/bin/gstack-next-version b/bin/gstack-next-version index c59a9dcaa..e19781594 100755 --- a/bin/gstack-next-version +++ b/bin/gstack-next-version @@ -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) { diff --git a/test/gstack-next-version.test.ts b/test/gstack-next-version.test.ts index 81cd180d0..ec3c34b2b 100644 --- a/test/gstack-next-version.test.ts +++ b/test/gstack-next-version.test.ts @@ -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.