/** * ship-receipt-depth — what the /ship receipt says about how deeply the * review read the head, and what the queue checks against it * (docs/review-policy.md#review-depth, docs/ship-policy.md#ship-receipt). * * `review_depth`: the depth the reviewed head needs, recomputed by * `gstack-ship-receipt write` (receiptDepthAtHead: the committed range from * git objects, gstack-diff-scope on that range and the gate scan of the clean * checkout at that head), with the runtime lines, the rules hash, the base and * registry commits and the gate scan bound to the head. * `review_loop_exception`: the owner's acceptance of a stop after a * fix-check edit under frozen scope (#3559), shaped like the docs exception. * The queue recomputes the depth the head needs from git objects * (lib/review-collect.ts) and refuses a receipt below it. * `review_targeted`: the targeted pass on money, gate, auth and secret code * (lib/review-targeted.ts); the queue reports it beside the depth and refuses * a head whose required classes the pass did not cover (GST-966). Kept beside * lib/ship-receipt.ts so that module stays under the size ratchet. */ import { spawnSync } from 'node:child_process'; import * as path from 'node:path'; import { baseContainsHead } from './default-base'; import type { ShipReceipt } from './headless-artifacts'; import { collectCommit } from './review-collect'; import { reviewExclude, type Exclusion } from './review-exclude'; import { isUnavailable } from './ship-policy'; import { loadPolicyAt } from './ship-policy-at'; import { depthOfCommitInput, gateScanNeeded, type Depth } from './review-depth'; import { TARGETED_CLASSES, classList, targetedClasses, type TargetedClass } from './review-targeted'; import { runScriptSync } from './script-invocation'; import { bindReceipt, type ReceiptBindingCode } from './ship-receipt'; import { docsExceptionLine, parseReceiptDocs } from './ship-receipt-docs'; export type ReceiptDepth = NonNullable; export type ReviewLoopException = NonNullable; const RANK: Record = { light: 0, standard: 1, full: 2 }; const text = (v: unknown): v is string => typeof v === 'string' && v.trim().length > 0 && !/[\x00-\x1f\x7f]/.test(v); const sha = (v: unknown): v is string => typeof v === 'string' && /^[0-9a-f]{40}$/.test(v); const BIN_DIR = path.join(import.meta.dir, '..', 'bin'); const short = (s: string | null | undefined) => (s ? s.slice(0, 12) : 'none'); function git(root: string, args: string[]): { ok: boolean; out: string } { const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: 60_000 }); return { ok: r.status === 0, out: (r.stdout ?? '').trim() }; } /** A base as a commit; origin/ reads refs/remotes/origin/ by its full name, so a tag named origin/main cannot stand in for it (GST-884). */ const baseCommit = (root: string, ref: string) => git(root, ['rev-parse', '--verify', '--quiet', `${/^origin\//.test(ref) ? `refs/remotes/${ref}` : ref}^{commit}`]); /** gstack-diff-scope on the committed range `base`...`head` (`--head`): the same signals at write, carry and the queue; `merged` (`--merged`) for a head GitHub already merged into the base. */ function scopeOfRange(root: string, binDir: string, base: string, head: string, merged = false): Record { const sr = runScriptSync(path.join(binDir, 'gstack-diff-scope'), [base, '--head', head, ...(merged ? ['--merged'] : [])], { cwd: root, encoding: 'utf8', timeout: 60_000, maxBuffer: 16 * 1024 * 1024 }); const scope: Record = {}; for (const l of (sr.stdout ?? '').split('\n')) { const m = /^(SCOPE_[A-Z_]+)=(.*)$/.exec(l); if (m) scope[m[1]!] = m[2]!; } if (sr.status !== 0 && !scope.SCOPE_ERROR) scope.SCOPE_ERROR = `exit ${sr.status}`; return scope; } export type ReceiptExclude = NonNullable; /** The receipt's copy of an active exclusion: counts and hashes, plus the gate-tagged kept paths the queue cannot recompute. */ export function receiptExclude(x: Exclusion): ReceiptExclude | undefined { if (x.state !== 'active') return undefined; const { source, patterns, applied, excluded, excluded_bytes, kept, gate_tagged, patterns_sha256, list_sha256, digest } = x.record; return { source, patterns, applied, excluded, excluded_bytes, kept, gate_tagged, patterns_sha256, list_sha256, digest }; } /** The exclusion for the committed range `baseSha`...`head` (collectCommit's), with the gate-tagged paths the caller knows. */ function exclusionAt(root: string, ref: string, baseSha: string | null, head: string, c: ReturnType, gateTagged: ReadonlySet | null, context: string): Exclusion { if (!baseSha || !c.mergeBase) return { state: 'none' }; return reviewExclude({ root, baseSha, ref, mergeBase: c.mergeBase, head, perPath: c.perPath, added: c.added, classRoot: c.root ?? [], gateTagged, context }); } /** Whether the base policy declares patterns, so the gate scan's per-path tags are worth reading. */ const declaresExclude = (root: string, ref: string, sha: string | null) => { if (!sha) return false; const l = loadPolicyAt(root, sha, ref); return !isUnavailable(l) && l.policy.review_exclude_paths.length > 0; }; /** * The depth record for `head`: the range from git objects (collectCommit) and * its diff-scope, as the queue recomputes them, plus, for a tests or code diff, * the gate scan of this checkout. The scan reads the working tree, so it counts * only when the checkout is `head` with no tracked edits; otherwise it is * unavailable and the depth fails closed to full. */ export function receiptDepthAtHead(repoRoot: string, base: string, binDir: string, head: string): ReceiptDepth { return receiptReviewAtHead(repoRoot, base, binDir, head).depth; } /** receiptDepthAtHead plus the exclusion the head's review read under: the depth classifies excluded paths as docs (GST-508). */ export function receiptReviewAtHead(repoRoot: string, base: string, binDir: string, head: string): { depth: ReceiptDepth; exclude: Exclusion } { const branch = base.replace(/^origin\//, ''); const baseSha = baseCommit(repoRoot, `origin/${branch}`); const baseRev = baseSha.ok ? baseSha.out : branch; const ref = baseSha.ok ? `origin/${branch}` : branch; const sha = baseSha.ok ? baseSha.out : (git(repoRoot, ['rev-parse', '--verify', '--quiet', `${branch}^{commit}`]).out || null); const c = collectCommit(repoRoot, baseRev, head); const scope = scopeOfRange(repoRoot, binDir, baseRev, head); const declares = declaresExclude(repoRoot, ref, sha); let tagged: number | null = 0; let paths: Set | null = declares ? new Set() : null; if (declares || gateScanNeeded(c.paths, c.root)) { const atHead = git(repoRoot, ['rev-parse', 'HEAD']).out === head && git(repoRoot, ['diff', '--quiet', 'HEAD', '--']).ok; const g = atHead ? runScriptSync(path.join(binDir, 'gstack-gate-diff'), [baseRev, ...(declares ? ['--format', 'jsonl'] : [])], { cwd: repoRoot, encoding: 'utf8', timeout: 120_000, maxBuffer: 64 * 1024 * 1024 }) : null; const m = /GATE_SUMMARY: .*?tagged=\{([^}]*)\}/.exec(g?.stdout ?? ''); tagged = g?.status === 0 && m ? m[1]!.split(',').reduce((n, kv) => n + (Number(kv.split(':')[1]) || 0), 0) : null; paths = declares && tagged !== null ? taggedPaths(g?.stdout ?? '') : null; } const exclude = exclusionAt(repoRoot, ref, sha, head, c, paths, 'gstack-ship-receipt'); const d = depthOfCommitInput({ ...c, scope, gateTagged: tagged, ...(exclude.state === 'active' ? { excluded: exclude.excluded } : {}) }); return { depth: { depth: d.depth, class: d.class, runtime_lines: d.runtimeLines, rules: d.rules, base: baseRev, registry: c.registry.sha, gate_scan: { tagged, head }, reasons: d.reasons.slice(0, 12), risk: d.risk }, exclude }; } /** The paths of the hunks a `gstack-gate-diff --format jsonl` run tagged. */ export function taggedPaths(jsonl: string): Set { return new Set(jsonl.split('\n').slice(1).flatMap(l => { try { const h = JSON.parse(l) as { path?: string; tags?: unknown[] }; return h.path && h.tags?.length ? [h.path] : []; } catch { return []; } })); } export const depthBelow = (have: Depth, need: Depth) => RANK[have] < RANK[need]; export const deeper = (a: Depth, b: Depth): Depth => (RANK[a] >= RANK[b] ? a : b); /** `write --review-loop-exception` input and the queue's check: who accepted the stop, when, where, why, and the fix-check it followed. */ export function parseReviewLoopException(value: unknown): { ok: true; exception: ReviewLoopException } | { ok: false; message: string } { const bad = (message: string) => ({ ok: false as const, message }); if (!value || typeof value !== 'object' || Array.isArray(value)) return bad('review_loop_exception must be { accepted_by, date, via, reason, fix_check: { head, findings[, files] } }'); const v = value as Record; for (const key of Object.keys(v)) if (!['accepted_by', 'date', 'via', 'reason', 'fix_check'].includes(key)) return bad(`review_loop_exception: unknown key ${JSON.stringify(key)}`); for (const key of ['accepted_by', 'date', 'via', 'reason']) if (!text(v[key])) return bad(`review_loop_exception.${key} must be a non-empty one-line string`); if (!/^\d{4}-\d{2}-\d{2}$/.test(v.date as string)) return bad('review_loop_exception.date must be YYYY-MM-DD'); const f = v.fix_check as Record | null; if (!f || typeof f !== 'object' || Array.isArray(f)) return bad('review_loop_exception.fix_check must be { head, findings[, files] }'); for (const key of Object.keys(f)) if (!['head', 'findings', 'files'].includes(key)) return bad(`review_loop_exception.fix_check: unknown key ${JSON.stringify(key)}`); if (!sha(f.head)) return bad('review_loop_exception.fix_check.head must be the full commit the fix-check reviewed'); if (typeof f.findings !== 'number' || !Number.isInteger(f.findings) || f.findings < 0) return bad('review_loop_exception.fix_check.findings must be an integer >= 0 (what the fix-check reported)'); if (f.files !== undefined && (!Array.isArray(f.files) || !f.files.every(text))) return bad('review_loop_exception.fix_check.files must be a list of paths'); const files = (f.files as string[] | undefined)?.slice(0, 50); return { ok: true, exception: { accepted_by: (v.accepted_by as string).trim(), date: v.date as string, via: (v.via as string).trim(), reason: (v.reason as string).trim(), fix_check: { head: f.head, findings: f.findings, ...(files?.length ? { files } : {}) } } }; } /** The line the PR body must carry, word for word, while the exception stands. */ export function reviewLoopExceptionLine(e: ReviewLoopException): string { return `Review-loop exception: accepted by ${e.accepted_by} ${e.date} via ${e.via}: ${e.reason} (fix-check at ${e.fix_check.head.slice(0, 12)}, ${e.fix_check.findings} finding${e.fix_check.findings === 1 ? '' : 's'})`; } const carries = (body: string, line: string) => body.split(/\r?\n/).some(l => l.trim() === line); /** * The owner exceptions a receipt records, checked the same way: valid shape, and the body carries each line verbatim. * `isAncestor`, when given, also requires the review-loop exception's fix-check head to be the receipt head or its ancestor. */ export function exceptionProblems(body: string, r: ShipReceipt, isAncestor?: (commit: string) => boolean): string[] { const out: string[] = []; const raw = r as ShipReceipt & { docs?: unknown }; if (raw.docs !== undefined) { const d = parseReceiptDocs(raw.docs); if (!d.ok) out.push(`docs: ${d.message}`); else { const line = docsExceptionLine(d.docs); if (line && !carries(body, line)) out.push(`the body does not carry the documentation exception line verbatim: ${JSON.stringify(line)}`); } } if (r.review_loop_exception !== undefined) { const e = parseReviewLoopException(r.review_loop_exception); if (!e.ok) out.push(e.message); else { if (!r.review_loop?.fix_checks) out.push('review_loop_exception needs review_loop.fix_checks >= 1 (the stop it accepts follows a fix-check)'); if (isAncestor && !isAncestor(e.exception.fix_check.head)) out.push(`review_loop_exception.fix_check.head ${e.exception.fix_check.head.slice(0, 12)} is not the receipt head or an ancestor of it`); const line = reviewLoopExceptionLine(e.exception); if (!carries(body, line)) out.push(`the body does not carry the review-loop exception line verbatim: ${JSON.stringify(line)}`); } } return out; } export type ReviewTargeted = NonNullable; /** * `write --review-targeted` input (gstack-review-dispatch verify --targeted-out), bound to the receipt's product patch-id here. * `head` is the commit the reader read; `productPatchOf` gives that commit's product patch-id by the receipt's own rules. The * record binds only on an equal product patch, and with `classesSince` also only when nothing changed after the read carries a * targeted class (a test change the gate scan tags is gate class though the product patch leaves tests out), so a record never * vouches for work it did not read (GST-986). */ export function parseReviewTargeted(value: unknown, productPatchId: string, productPatchOf: (head: string) => string | undefined, classesSince?: (read: string) => readonly TargetedClass[] | null): { ok: true; targeted: ReviewTargeted } | { ok: false; message: string } { const bad = (message: string) => ({ ok: false as const, message }); if (!value || typeof value !== 'object' || Array.isArray(value)) return bad('review_targeted must be { classes, rules, brief_sha, status, findings, raised_by, head }'); const v = value as Record; for (const key of Object.keys(v)) if (!['classes', 'rules', 'brief_sha', 'status', 'findings', 'raised_by', 'head'].includes(key)) return bad(`review_targeted: unknown key ${JSON.stringify(key)}${key === 'product_patch_id' ? ' (write binds the pass to the receipt\'s product_patch_id)' : ''}`); if (!Array.isArray(v.classes) || !v.classes.every(c => (TARGETED_CLASSES as readonly unknown[]).includes(c))) return bad(`review_targeted.classes must list ${TARGETED_CLASSES.join(', ')}`); if (!text(v.rules) || !text(v.raised_by)) return bad('review_targeted.rules and raised_by must be non-empty one-line strings'); if (typeof v.brief_sha !== 'string' || !/^[0-9a-f]{64}$/.test(v.brief_sha)) return bad('review_targeted.brief_sha must be the sha256 of review/specialists/targeted.md'); if (!['done', 'failed', 'not-run'].includes(v.status as string)) return bad('review_targeted.status must be done, failed or not-run'); if (typeof v.findings !== 'number' || !Number.isInteger(v.findings) || v.findings < 0) return bad('review_targeted.findings must be an integer >= 0'); if (typeof v.head !== 'string' || !/^[0-9a-f]{40,64}$/.test(v.head)) return bad('review_targeted.head must be the commit the targeted reader read (rerun gstack-review-dispatch verify --targeted-out with this gstack)'); const read = productPatchOf(v.head); if (read !== productPatchId || (classesSince && classesSince(v.head)?.length !== 0)) return bad(`the targeted reader read ${v.head.slice(0, 12)}, whose product patch ${read?.slice(0, 12) ?? 'cannot be read'} is not this receipt's ${productPatchId.slice(0, 12)}: the product changed after the read, so run the targeted reader on HEAD and verify again`); const classes = TARGETED_CLASSES.filter(c => (v.classes as string[]).includes(c)); return { ok: true, targeted: { classes, rules: v.rules as string, brief_sha: v.brief_sha, product_patch_id: productPatchId, status: v.status as ReviewTargeted['status'], findings: v.findings, raised_by: (v.raised_by as string).trim() } }; } export interface DepthVerdict { ok: boolean; line: string; message?: string } /** * The classes the head needs against the classes a done targeted pass covered; a required class left uncovered (no pass, * a failed or unrun pass, or a pass on other classes) is refused (GST-966). A receipt with neither gstack_version nor * review_depth predates targeted receipts, as receiptDepthVerdict treats it, and is accepted as legacy. */ export function receiptTargetedVerdict(required: readonly TargetedClass[], r: ShipReceipt): DepthVerdict { const rt = r.review_targeted; const covered: readonly string[] = rt?.status === 'done' ? rt.classes : []; const missing = required.filter(c => !covered.includes(c)); const verdict = !missing.length ? 'ok' : rt?.status === 'failed' ? 'failed' : 'missing'; const line = `REVIEW_TARGETED: required=${classList(required)} receipt=${rt ? classList(covered) : 'legacy'} verdict=${verdict}`; if (!missing.length) return { ok: true, line }; if (!rt && !r.review_depth && !r.gstack_version) return { ok: true, line: `${line} (legacy receipt, written before receipts recorded review_targeted; accepted)` }; const why = !rt ? 'records no targeted pass' : rt.status === 'failed' ? 'records that its targeted pass failed' : rt.status === 'not-run' ? 'records that its targeted pass did not run' : `covers ${classList(covered)} only`; return { ok: false, line, message: `the head requires the targeted reader on ${missing.join(', ')}, but the receipt ${why}` }; } /** The head's committed range against the base, read once for the depth verdict and the targeted line. */ interface HeadInputs { baseSha: { ok: boolean; out: string }; c: ReturnType; scope: Record; x: Exclusion } function headInputs(root: string, baseRef: string, head: string, r?: ShipReceipt, merged = false): HeadInputs { const baseSha = baseCommit(root, baseRef); const baseRev = baseSha.ok ? baseSha.out : baseRef; const c = collectCommit(root, baseRev, head); const tagged = r && boundScan(r, head) !== null ? new Set(r.review_exclude?.gate_tagged ?? []) : null; return { baseSha, c, scope: scopeOfRange(root, BIN_DIR, baseRev, head, merged), x: exclusionAt(root, baseRef, baseSha.ok ? baseSha.out : null, head, c, tagged, 'gstack-ship-queue') }; } /** * The queue's exclusion check: the digest the receipt recorded (none when absent) against the one `head` has under the current * base policy. Only the digest counts (the policy's patterns and the excluded list), so a base merge or a moved base that leaves * both unchanged binds; a changed selection needs the review rerun (write checks the same digest and does not read the * review ledger). */ export function excludeMismatch(x: Exclusion, r: ShipReceipt, head: string, base: string): string | null { const expected = x.state === 'active' ? x.record.digest : 'none'; const recorded = r.review_exclude?.digest ?? 'none'; if (expected === recorded) return null; const source = x.state === 'active' ? x.record.source : r.review_exclude?.source ?? base; const h = head.slice(0, 12); return `field=review_exclude expected=${expected} recorded=${recorded} source=${source}: the receipt records another selection than ${base}'s review_exclude_paths gives ${h}; the receipt is unchanged; fix: rerun /ship's review on ${h} (gstack-review-dispatch pass --base ${base.replace(/^(refs\/remotes\/)?origin\//, '')}), then gstack-ship-receipt write --pr --review-exclude --body with the digest gstack-review-dispatch verify --ledger prints on REVIEW_EXCLUDE_RECORD: (write checks the digest against the base policy and does not read the review ledger, so only the rerun shows the reviewers read this selection)`; } /** The receipt's recorded gate scan when it names this head; otherwise null (unavailable). */ const boundScan = (r: ShipReceipt, head: string): number | null => { const g = r.review_depth?.gate_scan; return g && g.tagged !== null && /^[0-9a-f]{40,64}$/.test(g.head) && g.head === head.toLowerCase() ? g.tagged : null; }; /** * The depth the bound head needs against `baseRef`, recomputed from git * objects; the recorded gate scan counts only when it names the receipt's * head, otherwise the scan is unavailable and the head needs full. A receipt * with no review_depth and no gstack_version predates depth receipts and is * accepted as legacy; one from a writer that records depth but lacks it is not. */ export function receiptDepthVerdict(root: string, baseRef: string, r: ShipReceipt, head: string, at?: HeadInputs): DepthVerdict { const rd = r.review_depth; if (!rd && !r.gstack_version) return { ok: true, line: 'REVIEW_DEPTH: legacy receipt (written before receipts recorded review_depth); accepted' }; const { baseSha, c, scope, x } = at ?? headInputs(root, baseRef, head, r); const tagged = boundScan(r, head); const scanBound = tagged !== null; const need = depthOfCommitInput({ ...c, scope, gateTagged: tagged, ...(x.state === 'active' ? { excluded: x.excluded } : {}) }); const have = rd?.depth; const inputs = `base@${short(baseSha.ok ? baseSha.out : null)},registry@${short(c.registry.sha)},gate_scan@${scanBound ? short(rd!.gate_scan.head) : 'missing'}`; const line = `REVIEW_DEPTH: receipt=${have ?? 'none'} required=${need.depth} runtime_lines=${need.runtimeLines} class=${need.class} reasons=${need.reasons.join(',')} inputs=${inputs} rounds=${r.review_loop?.rounds ?? (r.review_loop ? r.review_loop.passes + (r.review_loop.fix_checks ?? 0) : 'none')}`; if (have && !depthBelow(have, need.depth)) return { ok: true, line }; const why = have ? `was reviewed at ${have} depth` : 'records no review_depth though its writer records one'; const errs = need.errors.map(e => `${e.code} (${e.input})`).join('; '); return { ok: false, line, message: `the receipt ${why}, but head ${head.slice(0, 12)} needs ${need.depth} (${need.reasons.join(', ')}${errs ? `; ${errs}` : ''}); the receipt is unchanged; run /ship on ${head.slice(0, 12)}` }; } /** bindReceipt plus the owner exceptions, the review depth and the targeted pass: what READY, train build and land accept. A base that already contains the head refuses (BASE_CONTAINS_HEAD, GST-774) before any depth is computed, except for a PR GitHub already merged (`merged`: land resuming after a merge-only true merge), whose depth then reads the range with diff-scope's `--merged` and whose exclusion digest is not recomputed over that emptied range. */ export function bindShippedReceipt(root: string, baseRef: string, body: string, pr: string | undefined, accepted: readonly string[], merged = false): | { ok: true; receipt: ShipReceipt; head: string; line: string; depthLine: string; targetedLine: string } | { ok: false; code: ReceiptBindingCode | 'BASE_CONTAINS_HEAD' | 'QUEUE_RECEIPT_DEPTH_RAISED' | 'QUEUE_RECEIPT_EXCEPTION_INVALID' | 'RECEIPT_INVALID' | 'QUEUE_RECEIPT_TARGETED_MISSING' | Extract['code']; message: string; line: string; depthLine?: string; targetedLine?: string } { const b = bindReceipt(body, pr, accepted); if (!b.ok) return b; const self = merged ? null : baseContainsHead(root, baseRef, b.head); if (self) return { ok: false, code: 'BASE_CONTAINS_HEAD', message: self, line: b.line }; const ancestor = (commit: string) => b.receipt.carry?.ancestry === 'rewritten' || git(root, ['merge-base', '--is-ancestor', commit, b.head]).ok; const problems = exceptionProblems(body, b.receipt, ancestor); if (problems.length) return { ok: false, code: 'QUEUE_RECEIPT_EXCEPTION_INVALID', message: `the receipt's owner exception does not stand: ${problems.join('; ')}`, line: b.line }; const at = headInputs(root, baseRef, b.head, b.receipt, merged); if (at.x.state === 'refused') return { ok: false, code: at.x.code, message: at.x.lines.join('; '), line: b.line }; const mismatch = merged ? null : excludeMismatch(at.x, b.receipt, b.head, baseRef); if (mismatch) return { ok: false, code: 'RECEIPT_INVALID', message: mismatch, line: b.line }; const d = receiptDepthVerdict(root, baseRef, b.receipt, b.head, at); const gateTagged = boundScan(b.receipt, b.head) ?? (gateScanNeeded(at.c.paths, at.c.root) ? null : 0); const x = at.x.state === 'active' ? at.x.excluded : null; const without = (rec: Record) => (x ? Object.fromEntries(Object.entries(rec).filter(([p]) => !x.has(p))) : rec); const t = receiptTargetedVerdict(targetedClasses({ ...at.c, ...(x ? { paths: at.c.paths.filter(p => !x.has(p)), added: without(at.c.added), removed: without(at.c.removed) } : {}), scope: at.scope, gateTagged }).classes, b.receipt); if (!d.ok) return { ok: false, code: 'QUEUE_RECEIPT_DEPTH_RAISED', message: d.message!, line: b.line, depthLine: d.line, targetedLine: t.line }; if (!t.ok) return { ok: false, code: 'QUEUE_RECEIPT_TARGETED_MISSING', message: `${t.message}; the receipt is unchanged; run /ship on ${b.head.slice(0, 12)}`, line: b.line, depthLine: d.line, targetedLine: t.line }; return { ...b, depthLine: d.line, targetedLine: t.line }; } /** * The targeted classes of what changed from `from` to the checked-out `head`, with gstack-gate-diff run over that range whenever * a non-docs path changed (a test edit that skips a case is gate class); null when `from` is not an ancestor of `head`, the gate * scan did not run, or a class input is unreadable. */ export function targetedClassesSince(root: string, from: string, head: string): readonly TargetedClass[] | null { if (!git(root, ['merge-base', '--is-ancestor', from, head]).ok) return null; const at = headInputs(root, from, head, undefined, true); let gateTagged: number | null = 0; if (gateScanNeeded(at.c.paths, at.c.root)) { const g = runScriptSync(path.join(BIN_DIR, 'gstack-gate-diff'), [from], { cwd: root, encoding: 'utf8', timeout: 120_000, maxBuffer: 16 * 1024 * 1024 }); const m = /GATE_SUMMARY: .*?tagged=\{([^}]*)\}/.exec(g.stdout ?? ''); if (g.status !== 0 || !m) return null; gateTagged = m[1]!.split(',').reduce((n, kv) => n + (Number(kv.split(':')[1]) || 0), 0); } const t = targetedClasses({ ...at.c, scope: at.scope, gateTagged }); return t.errors.length ? null : t.classes; } /** * receiptTargetedVerdict at the receipt's head, with the classes the queue computes: what write and carry check before they * publish (#3854). Classes that failed closed on an input this checkout cannot read (no origin base, no gate scan) are reported, * never refused on here: the queue reads its own inputs at ready and refuses there if the head needs the reader. */ export function receiptTargetedAtHead(root: string, baseRef: string, r: ShipReceipt, head: string): DepthVerdict { const at = headInputs(root, baseRef, head); const gateTagged = boundScan(r, head) ?? (gateScanNeeded(at.c.paths, at.c.root) ? null : 0); const t = targetedClasses({ ...at.c, scope: at.scope, gateTagged }); const v = receiptTargetedVerdict(t.classes, r); return v.ok || !t.errors.length ? v : { ok: true, line: `${v.line} (unchecked: ${t.errors.join('; ')}; the queue decides at ready)` }; }