/ship reuses CI's passing run when a base merge changed no file, and stops before long local test runs or an unknown base (GST-3019) (#4461)

/ship's preflight and its CI-run lookup now reuse a passing CI test run
when a base merge left the files unchanged, stop instead of quietly
starting an hour-long test suite on the local machine, and refuse a
`--base` that names no commit instead of reporting an empty diff.

Why: gbrain #9662 lost a green CI run to a no-op base merge, then ran a
50-minute suite on a 4-CPU box, and its audit read a commit sha as a
branch and saw zero changed files.

Nothing to do: `--run-uncarried-here` restores running an uncovered
suite locally under `--tests-only`.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Review-Finding: s11/outside-voice#1 reader=outside-voice
Review-Finding: s11/outside-voice#2 reader=outside-voice
This commit is contained in:
Garry Tanandcapy-ai[bot] authored and GitHub committed 2026-11-17 20:56:07 +00:00
1 parent 76535826f5
commit da98d0a0eb
18 files changed
+354 -45

No files matched your search

+47
View File
@@ -79,6 +79,53 @@ describe('findCarry', () => {
});
});
describe('GST-3019: a run at another commit whose tree git reads as HEAD\'s carries', () => {
const TWIN = 'c'.repeat(40);
const ELSE = 'e'.repeat(40);
const twins = (runs: ApiRun[], records: Record<number, TreeRecord>, trees: Record<string, string> = { [HEAD]: TREE, [TWIN]: TREE, [ELSE]: 'f'.repeat(40) }): RunSource => {
const src = source(runs, records);
return { ...src, deps: { ...src.deps, commitTree: sha => trees[sha] ?? null, ancestors: (sha, max) => [sha, TWIN, ELSE].slice(0, max) } };
};
const atTwin = (id: number, over: Partial<ApiRun> = {}) => run(id, { head_sha: TWIN, ...over });
const recTwin = (id: number, over: Partial<TreeRecord> = {}) => record(id, { sha: TWIN, ...over });
// Value: protects=a base merge that changed no file keeps the green CI run of the commit before it (gbrain #9662: 0dc0d1d had 5840295's tree 369fa767 and carried nothing);
// fails_when=only runs on HEAD's own sha are listed, or the carried run's commit is not the one git read; why_new=GST-3019; seam=RunDeps.ancestors and commitTree
test('a green run of the same workflow at an ancestor with HEAD\'s tree carries, and the evidence names that commit', () => {
const v = carry(twins([atTwin(4)], { 4: recTwin(4) }), { inventory: () => ['test/a.test.ts', 'test/b.test.ts'] });
expect(why(v)).toBe('ok');
if (!v.ok) return;
expect(v.runs.map(e => [e.run_id, e.head_sha, e.tree])).toEqual([[4, TWIN, TREE]]);
expect(v.receipt).toContain(`runs=4/1 profiles=ci-reuse/free-tests heads=${TWIN.slice(0, 12)} `);
const both = carry(twins([atTwin(4), run(5)], { 4: recTwin(4), 5: record(5) }));
expect(both.ok && both.runs.map(e => [e.run_id, e.head_sha])).toEqual([[5, HEAD]]);
});
// Value: protects=tree identity comes from git, and every other carry rule still holds at the other commit; fails_when=a different tree, a failed or cancelled run,
// another workflow, or a newer red run at HEAD carries; why_new=GST-3019 negative controls; seam=verifyRun
test('negative controls: another tree, a failed or cancelled run, another workflow and a newer red run at HEAD never carry', () => {
expect(why(carry(twins([run(4, { head_sha: ELSE })], { 4: record(4, { sha: ELSE, tree: TREE }) })))).toBe('no_run');
expect(why(carry(twins([atTwin(4)], { 4: recTwin(4) }, { [HEAD]: TREE, [TWIN]: 'd'.repeat(40) })))).toBe('no_run');
const failed = carry(twins([atTwin(4, { conclusion: 'failure' })], { 4: recTwin(4) }));
expect([why(failed), failed.ok ? '' : failed.detail]).toEqual(['no_verified_run', expect.stringContaining('run 4: run_not_success')]);
const cancelled = carry(twins([atTwin(4, { conclusion: 'cancelled' })], { 4: recTwin(4) }));
expect([why(cancelled), cancelled.ok ? '' : cancelled.detail]).toEqual(['no_verified_run', expect.stringContaining('run 4: run_not_success')]);
const other = carry(twins([atTwin(4, { path: '.github/workflows/other.yml' })], { 4: recTwin(4) }));
expect([why(other), other.ok ? '' : other.detail]).toEqual(['no_verified_run', expect.stringContaining('run 4: workflow_mismatch')]);
const vetoed = carry(twins([atTwin(4), run(6, { conclusion: 'failure' })], { 4: recTwin(4), 6: record(6) }));
expect([why(vetoed), vetoed.ok ? '' : vetoed.detail]).toEqual(['no_verified_run', expect.stringContaining('run 4: newer_run_vetoes')]);
expect(why(carry(twins([atTwin(4)], { 4: recTwin(4, { tree: 'd'.repeat(40) }) })))).toBe('no_verified_run');
});
// Value: protects=gstack-ci-carry wait sees the green run at the commit with HEAD's tree instead of waiting out its timeout; fails_when=wait reads HEAD's sha alone;
// why_new=GST-3019; seam=waitForRun
test('waitForRun reads runs at the commits with HEAD\'s tree too', async () => {
const src = twins([atTwin(4)], { 4: recTwin(4) });
const w = await waitForRun(src.deps, { workflow: 'free-tests.yml', events: ['workflow_dispatch'], head: HEAD, also: [TWIN], timeoutMs: 0, intervalMs: 60_000, sleep: async () => {}, clock: () => 0 });
expect(w.state === 'green' && w.run.id).toBe(4);
});
});
describe('waitForRun', () => {
const clockAt = () => { let t = 0; return { clock: () => t, sleep: async (ms: number) => { t += ms; } }; };
// Value: protects=the bounded wait reports green, red with failing jobs, still running and none; fails_when=it waits forever or calls a red run green
+14
View File
@@ -55,3 +55,17 @@ test('a run whose gate job failed never counts its skipped suites', () => {
const v = verifyRun(failed, { repo: REPO, runRef: '7', profileName: 'ci-reuse/free-tests', profile: PROFILE, now: NOW, unchanged: () => null, docsOnly: () => true });
expect(v.ok ? 'ok' : v.reason).toBe('job_skipped');
});
// Value: protects=a docs-only skipped run at a commit with HEAD's tree (GST-3019) carries as not owed only when HEAD itself is docs-only;
// fails_when=the ancestor's classification exempts a HEAD whose base merge changed runtime code against the new base; why_new=GST-3019 review; seam=RunDeps.ancestors
test('a docs-only run at a same-tree ancestor carries only when HEAD is docs-only too', () => {
const TWIN = 'c'.repeat(40);
const atTwin: ApiRun = { ...RUN, head_sha: TWIN };
const twinDeps: RunDeps = { ...deps, run: () => atTwin, runsForHead: (_wf, sha) => (sha === TWIN ? [atTwin] : []), commitTree: sha => (sha === HEAD || sha === TWIN ? TREE : null), ancestors: sha => [sha, TWIN] };
const at = (docsOnly: (h: string) => boolean) => carry({ ...source(docsOnly), deps: twinDeps });
const ancestorOnly = at(h => h === TWIN);
expect(ancestorOnly.ok).toBe(false);
if (!ancestorOnly.ok) expect(ancestorOnly.detail).toContain('artifact_missing');
const both = at(() => true);
expect(both.ok && both.notOwed).toContain('docs-only change');
});
+74 -4
View File
@@ -41,7 +41,9 @@ function world(f: ShipFx, over: { run?: Record<string, unknown>; tree?: Record<s
fs.writeFileSync(file, JSON.stringify(w));
f.gh(fakeGhScript(file));
}
const preflight = (f: ShipFx, lanes = [`free=${FREE}`, `unit=${UNIT}`]) => f.run(PREFLIGHT, ['--tests-only', '--base', 'main', ...lanes.flatMap(l => ['--lane', l])]);
const preflight = (f: ShipFx, lanes = [`free=${FREE}`, `unit=${UNIT}`], extra: string[] = []) => f.run(PREFLIGHT, ['--tests-only', '--base', 'main', ...extra, ...lanes.flatMap(l => ['--lane', l])]);
/** --tests-only with --run-uncarried-here: a mapped lane whose carry refuses runs here (GST-3019; without the flag it stops). */
const UNCARRIED_HERE = ['--run-uncarried-here'];
const lane = (out: string, label: string) => out.split('\n').find(l => l.startsWith(`LANE: ${label} `)) ?? '';
describe('Step 5 lanes: CI carry and the tree cache', () => {
@@ -75,7 +77,7 @@ describe('Step 5 lanes: CI carry and the tree cache', () => {
let expected = 0;
for (const [reason, setup] of cases) {
setup();
const out = preflight(f, [`free=${FREE}`]).stdout;
const out = preflight(f, [`free=${FREE}`], UNCARRIED_HERE).stdout;
expect([reason, out]).toEqual([reason, expect.stringContaining('CI_CARRY: none label=free (')]);
expect(out).toContain(reason);
expect(lane(out, 'free')).toMatch(/^LANE: free pass exit=0 tests_ran=3 /);
@@ -424,7 +426,7 @@ describe('GST-1190: a file whose every test skipped on CI is not carried', () =>
world(f, { tree: { skipped_files: ['test/b.test.ts'] } });
const rec = f.run(path.join(BIN, 'gstack-evidence'), ['record-ci', '--label', 'free', '--base', 'main', '--', FREE]);
expect([rec.status, rec.stderr]).toEqual([1, expect.stringMatching(/^CARRY_NONE: inventory_skipped: 1 of 2 inventory file\(s\) skipped every test in CI and the lane declares no per_file runner: test\/b\.test\.ts$/m)]);
const out = preflight(f, [`free=${FREE}`]);
const out = preflight(f, [`free=${FREE}`], UNCARRIED_HERE);
expect(out.stdout).toContain('CI_CARRY: none label=free (inventory_skipped');
expect(runs(f, 'free-runs')).toBe(1);
world(f, { tree: { skipped_files: [] } });
@@ -538,10 +540,21 @@ describe('GST-1190: a lane carries the covered files and runs only the skipped r
const rec = f.run(path.join(BIN, 'gstack-evidence'), ['record-ci', '--label', 'free', '--base', 'main', '--', FREE]);
expect([rec.status, rec.stderr]).toEqual([1, expect.stringMatching(/^CARRY_NONE: skipped_failed: the per_file run of test\/b\.test\.ts exited 1 \(label=free\.skipped\)$/m)]);
expect(rows(f).filter(r => r.source === 'ci')).toEqual([]);
expect(preflight(f, [`free=${FREE}`]).stdout).toContain('CI_CARRY: none label=free (skipped_failed');
expect(preflight(f, [`free=${FREE}`], UNCARRIED_HERE).stdout).toContain('CI_CARRY: none label=free (skipped_failed');
expect(runs(f, 'free-runs')).toBe(1);
});
// Value: protects=--tests-only decides its hold before any lane's record-ci runs a per_file remainder here (GST-3019 review: the hold ran
// remainders, then said nothing ran); fails_when=the carrying lane's skipped file runs while another mapped lane refuses; why_new=GST-3019; seam=fake gh, gstack-ci-carry find
test('a refused mapped lane stops --tests-only before another lane runs its skipped remainder here', () => {
const f = shipFixture({ ...BASE, '.gstack/pregate.json': JSON.stringify({ run_profiles: { 'ci/free': PROFILE }, ship_lanes_from: { [FREE]: { profiles: ['ci/free'], inventory: "printf 'test/a.test.ts\\ntest/b.test.ts\\n'", per_file: PER(0) }, [UNIT]: { profiles: ['ci/free'], jobs: ['lint'] } } }, null, 2) + '\n' }); fixtures.push(f);
world(f, { tree: { skipped_files: ['test/b.test.ts'] } });
const held = preflight(f);
expect(held.status, held.stdout + held.stderr).toBe(3);
expect(lineOf(held.stdout, 'STOP')).toMatch(/^STOP: SHIP_LANE_NOT_CARRIED: lane unit did not carry /);
expect([args(f), runs(f, 'free-runs'), runs(f, 'unit-runs')]).toEqual(['', 0, 0]);
});
test('a remainder file that registers no test here carries nothing: the lane runs whole', () => {
const zero = { ...BASE, '.gstack/pregate.json': JSON.stringify({ run_profiles: { 'ci/free': PROFILE }, ship_lanes_from: { [FREE]: { profiles: ['ci/free'], inventory: "printf 'test/a.test.ts\\ntest/b.test.ts\\n'", per_file: "printf ' 0 pass\\n 0 fail\\nRan 0 tests across 1 file. [1.00ms]\\n' >&2 # {files}" } } }, null, 2) + '\n' };
const f = shipFixture(zero); fixtures.push(f);
@@ -716,3 +729,60 @@ describe('GSTA-258 L6 review fixes: gate inputs, ledger CI rows, simulate consen
expect(yes.stdout).toContain('SIMULATION: LANE: free would carry run=7/1 tests_ran=2 unit=files');
});
});
describe('GST-3019: a commit that changes no file carries the green run of the commit with its tree', () => {
// Value: protects=a base merge that changed no file reuses the passed CI run of the identical tree, and every surface says which commit and run it came from
// (gbrain #9662: 0dc0d1d, tree 369fa767, printed no_run beside 5840295's green run); fails_when=find, wait or Step 5 reads HEAD's sha alone, or a changed tree,
// an unmapped command or a red run carries; why_new=GST-3019; seam=fake gh, git rev-list and rev-parse in the fixture
test('find, wait and Step 5 carry from the earlier commit and name it; a changed tree, another command or a red run does not', () => {
const f = fx();
world(f);
const before = f.git('rev-parse', 'HEAD').stdout.trim();
const tree = f.git('rev-parse', 'HEAD^{tree}').stdout.trim();
expect(f.git('commit', '--allow-empty', '-m', 'merge main: no file changes').status).toBe(0);
const head = f.git('rev-parse', 'HEAD').stdout.trim();
expect([head !== before, f.git('rev-parse', 'HEAD^{tree}').stdout.trim()]).toEqual([true, tree]);
const cli = (args: string[]) => f.run(path.join(BIN, 'gstack-ci-carry'), args);
const found = cli(['find', '--base', 'main', '--command', FREE, '--allow-repo-commands']);
expect([found.status, lineOf(found.stdout, 'CI_CARRY')]).toEqual([0, expect.stringMatching(new RegExp(`^CI_CARRY: accepted ci-carry tree=${tree.slice(0, 12)} files=2 runs=7/1 profiles=ci/free heads=${before.slice(0, 12)} `))]);
expect(lineOf(found.stdout, 'CI_CARRY_FROM')).toBe(`CI_CARRY_FROM: run 7/1 at commit ${before.slice(0, 12)}, not HEAD ${head.slice(0, 12)}; git rev-parse reads the same tree ${tree.slice(0, 12)} for both`);
expect(cli(['wait', '--base', 'main', '--timeout', '0']).stdout).toContain('CI_WAIT: green ci/free run=7/1');
const step5 = preflight(f, [`free=${FREE}`]);
expect([step5.status, lane(step5.stdout, 'free')]).toEqual([0, `LANE: free carried run=7/1 tests_ran=2 (files) from=${before.slice(0, 12)} (same tree as HEAD)`]);
expect(runs(f, 'free-runs')).toBe(0);
expect(cli(['find', '--base', 'main', '--command', 'bun run test', '--allow-repo-commands']).stdout).toContain('CI_CARRY: none (not_mapped');
world(f, { run: { head_sha: before, conclusion: 'failure' }, tree: { sha: before } });
expect(cli(['find', '--base', 'main', '--command', FREE, '--allow-repo-commands']).stdout).toContain('CI_CARRY: none (no_verified_run: ci/free: run 7: run_not_success');
world(f, { run: { head_sha: before, conclusion: 'cancelled' }, tree: { sha: before } });
expect(cli(['find', '--base', 'main', '--command', FREE, '--allow-repo-commands']).stdout).toContain('run 7: run_not_success');
world(f, { run: { head_sha: before }, tree: { sha: before } });
f.write({ 'src/c.ts': 'export const c = 1;\n' });
expect(f.git('add', '-A').status).toBe(0);
expect(f.git('commit', '-m', 'a real change').status).toBe(0);
expect(cli(['find', '--base', 'main', '--command', FREE, '--allow-repo-commands']).stdout).toContain('CI_CARRY: none (no_run: no free.yml run (pull_request, workflow_dispatch) on ');
});
});
describe('GST-3019: --tests-only never starts a lane on its own when its carry refuses', () => {
// Value: protects=a refused carry under --tests-only stops with SHIP_LANE_NOT_CARRIED and the next command instead of quietly running the lane here
// (gbrain #9662: a 50-minute unit lane on a 4-CPU box); fails_when=the mapped lane or any other lane runs, the stop has no code, or --run-uncarried-here
// does not run it; why_new=GST-3019; seam=fake gh, gstack-evidence ledger
test('a refused carry stops before any lane runs and names the CI dispatch; --run-uncarried-here runs it here', () => {
const f = fx();
world(f, { run: { head_sha: '0'.repeat(40) } });
const branch = f.git('branch', '--show-current').stdout.trim();
const held = preflight(f);
expect(held.status).toBe(3);
expect(held.stdout).toContain('CI_CARRY: none label=free (no_run: ');
expect(lineOf(held.stdout, 'STOP')).toBe('STOP: SHIP_LANE_NOT_CARRIED: lane free did not carry from a verified CI run at this tree, and --tests-only never starts a lane on its own: nothing ran here (docs/troubleshooting.md#ship-lane-not-carried)');
expect(held.stdout).toContain(`NEXT: commit and push this tree, then gh workflow run free.yml --ref ${branch} and gstack-ci-carry wait --base main; once it prints CI_WAIT: green, rerun this command`);
expect(held.stdout).toContain('NEXT: or rerun this command with --run-uncarried-here to run lane free on this machine');
expect([runs(f, 'free-runs'), runs(f, 'unit-runs')]).toEqual([0, 0]);
const here = preflight(f, undefined, UNCARRIED_HERE);
expect(here.status).toBe(0);
expect(here.stdout).toContain('CI_CARRY: none label=free (no_run: ');
expect(lane(here.stdout, 'free')).toMatch(/^LANE: free pass exit=0 tests_ran=3 /);
expect([runs(f, 'free-runs'), runs(f, 'unit-runs')]).toEqual([1, 1]);
expect(f.run(PREFLIGHT, ['--base', 'main', '--run-uncarried-here', '--lane', `free=${FREE}`]).status).toBe(2);
});
});
+17
View File
@@ -339,6 +339,23 @@ describe('gstack-ship-preflight --audit (GSTA-167 variant G)', () => {
expect(lineOf(r.stdout, 'READER')).toBe('READER: coverage=none plan=needed');
expect(f.run(PREFLIGHT, ['--audit', '--base', 'main']).status).toBe(2);
});
// Value: protects=--audit --base <sha> diffs against that commit, and a base that resolves to nothing stops with SHIP_BASE_UNKNOWN instead of an empty diff (gbrain #9662);
// fails_when=a commit sha is read as origin/<sha>, or an unknown base prints CONTEXT files=0; why_new=GST-3019; seam=git
test('a commit sha is a base; a base that resolves to nothing stops with SHIP_BASE_UNKNOWN, never files=0', () => {
const f = fx({}, { 'src/budget.ts': 'export const budget = 1;\n', 'src/other.ts': 'export const o = 1;\n' });
const base = f.git('rev-parse', 'origin/main').stdout.trim();
for (const sha of [base, base.slice(0, 12)]) {
const r = f.run(PREFLIGHT, ['--audit', '--base', sha, '--out', path.join(f.root, `a-${sha.length}`)], { HOME: f.root });
expect(r.status, r.stdout + r.stderr).toBe(0);
expect(lineOf(r.stdout, 'CONTEXT')).toMatch(/ files=2 commits=1 /);
}
for (const bad of ['0'.repeat(40), 'no-such-branch']) {
const u = f.run(PREFLIGHT, ['--audit', '--base', bad, '--out', path.join(f.root, 'bad')], { HOME: f.root });
expect([u.status, lineOf(u.stdout, 'STOP')]).toEqual([3, `STOP: SHIP_BASE_UNKNOWN: --base ${bad} names no commit here (not a commit this checkout holds, and no origin/${bad}); pass the base branch fetched into origin/<name>, or a commit sha after git fetch origin <sha>, then rerun (docs/troubleshooting.md#ship-base-unknown)`]);
expect(u.stdout).not.toContain('CONTEXT');
}
});
});
describe('GSTA-167 part 4a: RUNTIME_LINES and REVIEW_DEPTH share one owner', () => {
@@ -0,0 +1,4 @@
{
"bytes": 192,
"why": "GST-3019: Step 5 prose names the SHIP_LANE_NOT_CARRIED stop under --tests-only and the --run-uncarried-here flag"
}