/**
* Owner-granted test-lane exceptions (GST-1595, docs/ship-policy.md#test-lane-exceptions): the owner's grant that a lane
* carries from CI although some of its inventory files are in no run's tree.json (bun registers an imported test file's
* tests under the importer, so the imported file's JUnit suite never appears). A grant is one approved gstack-approvals
* row (`gstack-approvals lane-exception`), scope `test_lane_exception
` and ask
* `test_lane_exception at : : `, where head is the full sha of the pushed head the owner granted at and
* files are exactly the uncovered files, comma-separated. It binds only at that head and only for that exact set, and
* `gstack-evidence record-ci` counts it only after a local preflight of exactly those files passes there. Like a ruled note
* (lib/ruled-notes.ts), a row by gstack itself is no grant, and the CLI refuses inside the checkout's open /ship run, so the
* lane that needs the exception cannot write it for itself.
*/
import { locate, readRecord, type ApprovalRow, type Env } from './approval-record';
import { GSTACK_ACTOR } from './ruled-notes';
export interface TestLaneException { head: string; files: string[]; by: string; reason: string; at: string; approval: string }
/** What the ledger's CI row and the receipt's ci_carried entry keep: the grant plus the preflight that backed it. */
export interface BoundLaneException extends TestLaneException { preflight: { label: string; tests_ran: number } }
const SCOPE = /^test_lane_exception ([0-9a-f]{40}) (\S+)$/;
const ASK = /^test_lane_exception at ([0-9a-f]{40}): (\S+): (\S(?:.*\S)?)$/;
export const TEST_LANE_EXCEPTION_SCOPE = /^\s*test_lane_exception\b/;
export const testLaneExceptionRow = (head: string, files: string[], reason: string) =>
({ scope: `test_lane_exception ${head} ${files.join(',')}`, ask: `test_lane_exception at ${head}: ${files.join(',')}: ${reason}` });
/** The approved grants, one per head and file set (the newest wins), so each lane at a head keeps its own grant. */
export function testLaneExceptions(rows: readonly ApprovalRow[]): TestLaneException[] {
const byGrant = new Map();
for (const r of rows) {
const scope = SCOPE.exec(r.scope), ask = ASK.exec(r.ask);
if (r.outcome !== 'approved' || !scope || !ask || ask[1] !== scope[1] || ask[2] !== scope[2] || GSTACK_ACTOR.test(r.by)) continue;
const files = scope[2]!.split(',').filter(Boolean).sort(), key = `${scope[1]} ${files.join(',')}`;
byGrant.delete(key);
byGrant.set(key, { head: scope[1]!, files, by: r.by, reason: ask[3]!, at: r.recorded_at, approval: r.id });
}
return [...byGrant.values()];
}
/** The grants in the checked-out branch's approval record (and its mirror). */
export function readTestLaneExceptions(cwd: string, env: Env = process.env): TestLaneException[] {
const loc = locate({ cwd, env });
return 'code' in loc ? [] : testLaneExceptions(readRecord(loc).rows);
}
/** The `Test-lane exception: …` lines a receipt's ci_carried entries require in the PR body, one per grant. */
export function laneExceptionBodyLines(carried: unknown): string[] {
const list = Array.isArray(carried) ? carried : [];
return [...new Set(list.flatMap(c => {
const e = (c as { exception?: BoundLaneException } | null)?.exception;
return e && Array.isArray(e.files) && typeof e.head === 'string' && e.preflight ? [`Test-lane exception: ${testLaneExceptionText(e)}`] : [];
}))];
}
/** The text after `TEST_LANE_EXCEPTION: ` in accept's output and after `Test-lane exception: ` in the PR body. */
export const testLaneExceptionText = (e: BoundLaneException) =>
`${e.files.join(', ')} at ${e.head.slice(0, 12)}: preflight ${e.preflight.label} ran ${e.preflight.tests_ran} test(s) here; granted by ${e.by} at ${e.at}: ${e.reason} (approval ${e.approval})`;