Merge remote-tracking branch 'origin/main' into gsta258-l6-carry-followup

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

# Conflicts:
#	docs/pregate.md
#	lib/pregate/index.ts
#	lib/pregate/run-check.ts
#	lib/run-evidence.ts
#	test/ship-ci-carry.test.ts
This commit is contained in:
garrytan committed 2026-11-03 14:15:53 +00:00
commit f4a5b59f91
98 files changed
+5705 -228

No files matched your search

+35 -1
View File
@@ -223,8 +223,42 @@ export function cell(text: string, cap = 400): string {
export const APPROVALS_TABLE_HEADER = '| Date | Asked | Exact words | Outcome | Covers | Still pending |';
export const APPROVALS_FOOTER_END = '(display only; not an approval citation).';
export function renderRecord(read: ReadResult, loc: StoreLocation, o: { heading?: boolean } = {}): string {
export type RepoVisibility = 'public' | 'private' | 'unknown';
/**
* The repository's visibility as GitHub reports it through gh, for the repository gh acts on by default (GH_REPO, its
* default repo, an upstream remote) and for the origin remote a PR is opened against: private only when every one
* asked is private, public when any is public, and unknown for anything gh cannot answer.
*/
export function repoVisibility(cwd: string, env: Env = process.env): RepoVisibility {
const ask = (repo: string[]): RepoVisibility => {
const r = spawnSync('gh', ['repo', 'view', ...repo, '--json', 'visibility', '-q', '.visibility'], { cwd, env, encoding: 'utf8', timeout: 15_000 });
if (r.status !== 0) return 'unknown';
const v = (r.stdout ?? '').trim().toLowerCase();
return v === 'private' || v === 'internal' ? 'private' : v === 'public' ? 'public' : 'unknown';
};
const origin = spawnSync('git', ['remote', 'get-url', 'origin'], { cwd, env, encoding: 'utf8', timeout: 15_000 });
const slug = origin.status === 0 ? /([^/:]+\/[^/]+?)(?:\.git)?\/*$/.exec(origin.stdout.trim())?.[1] : undefined;
const seen = [ask([]), ...(slug ? [ask([slug])] : [])];
return seen.includes('public') ? 'public' : seen.every(v => v === 'private') ? 'private' : 'unknown';
}
/**
* Full rows only where the repository is known private, or --full asks for them and GitHub does not report it public.
* A PR description keeps every earlier version in its edit history, so a public or unknown repository gets the
* redacted block: whether anything was approved and an opaque id of the record (a hash of its row ids), nothing else.
*/
export function renderMode(visibility: RepoVisibility, full: boolean): 'full' | 'redacted' {
return visibility === 'private' || (full && visibility === 'unknown') ? 'full' : 'redacted';
}
export function renderRecord(read: ReadResult, loc: StoreLocation, o: { heading?: boolean; mode?: 'full' | 'redacted' } = {}): string {
const head = o.heading === false ? [] : ['## Approvals', ''];
if (o.mode === 'redacted' && read.rows.length) {
const approved = read.rows.some(r => r.outcome === 'approved' || r.outcome === 'standing');
const id = 'r-' + createHash('sha256').update(read.rows.map(r => r.id).sort().join('\n')).digest('hex').slice(0, 12);
return [...head, `Approved: ${approved ? 'yes' : 'no'} (record ${id}). The full approval record stays private: this repository is public or its visibility is unknown.`, ''].join('\n');
}
if (read.state === 'unavailable') return [...head, `Record unavailable on this machine: no approval record for branch ${cell(loc.branch)} here, and the state root is ephemeral with no Drive mirror, so this is not proof that nothing was approved.`, ''].join('\n');
if (!read.rows.length) return [...head, `No approvals recorded for branch ${cell(loc.branch)}.`, ''].join('\n');
const lines = [APPROVALS_TABLE_HEADER, '|---|---|---|---|---|---|'];
+25 -8
View File
@@ -16,6 +16,7 @@ import * as fs from 'node:fs';
import * as path from 'node:path';
import { OUTSIDE_ROLE, sectionLoadFor, type Phase, type Scope } from './autoplan-prompts';
import { RunError, type RunState } from './autoplan-state';
import { redactFindingSpans } from './redact-engine';
export const KINDS = ['fix', 'feature'] as const;
export type AutoplanKind = typeof KINDS[number];
@@ -33,7 +34,7 @@ export const FIX_LINES = [
const LENS: Record<Phase, string> = { ceo: 'CEO', design: 'Design', dx: 'DX', eng: 'Eng' };
const INLINE_DRAFT_BYTES = 100_000;
const UNTRACKED_MAX = 200;
const SECRET_NAME = /(^|\/)(\.env(\.[^/]*)?|[^/]*\.(pem|key|p12|pfx|keystore)|id_(rsa|dsa|ecdsa|ed25519)|\.netrc|\.npmrc|\.pypirc|credentials(\.[^/]*)?|[^/]*secret[^/]*)$/i;
const SECRET_NAME = /(^|\/)(\.env[^/]*|[^/]*\.(pem|key|p12|pfx|keystore|jks)|id_(rsa|dsa|ecdsa|ed25519)(_sk)?|[._]netrc|\.npmrc|\.pypirc|\.pgpass|[^/]*credentials[^/]*|[^/]*secret[^/]*)$/i;
/** The first next's mode: lean for --kind feature, or for an unattended Capy run that names no kind; --full and --ceo-only keep today's run. */
export function leanMode(o: { kind?: AutoplanKind; full?: boolean; ceoOnly?: boolean; base?: string; sessionKind: string; env: NodeJS.ProcessEnv }): LeanMode | undefined {
@@ -56,7 +57,9 @@ export const draftLine = (d: DraftInput) =>
/**
* The draft code against the base: tracked changes since the merge base (committed and not) plus untracked files,
* the run directory excluded, written once to <dir>/draft.diff (read-only) and hashed. No git, no merge base, no
* change or a git command that failed is an honest none with its reason, never a partial draft.
* change or a git command that failed is an honest none with its reason, never a partial draft. The draft goes to
* a model provider, so a file whose name looks like a secret is never diffed (tracked or untracked), and every
* file's patch passes through the redact engine; one it cannot redact is left out with a note (GST-1164, #3914).
*/
export function captureDraft(cwd: string, dir: string, out: string, base?: string): DraftInput {
const git = (args: string[], at = cwd) => spawnSync('git', ['-c', 'core.quotepath=off', ...args], { cwd: at, encoding: 'utf8', timeout: 60_000, maxBuffer: 256 * 1024 * 1024 });
@@ -73,19 +76,33 @@ export function captureDraft(cwd: string, dir: string, out: string, base?: strin
const failed = (r: ReturnType<typeof git>, what: string, ok = [0]) => r.error || r.status === null || !ok.includes(r.status)
? `draft capture failed: ${what} ${r.error ? `errored (${r.error.message})` : `exited ${r.status ?? r.signal}`}${r.stderr?.trim() ? `: ${r.stderr.trim().split('\n')[0]}` : ''}` : undefined;
const raw = ['diff', '--no-color', '--no-ext-diff', '--no-textconv'];
const tracked = git([...raw, mergeBase, '--'], root);
const names = git(['diff', '--name-only', mergeBase, '--'], root);
const names = git(['diff', '--name-status', '-z', '-M', '-C', mergeBase, '--'], root);
const others = git(['ls-files', '--others', '--exclude-standard', '-z'], root);
const broken = failed(tracked, 'git diff') ?? failed(names, 'git diff --name-only') ?? failed(others, 'git ls-files');
const listed = failed(names, 'git diff') ?? failed(others, 'git ls-files');
if (listed) return { base: ref, none: listed };
const fields = names.stdout.split('\0');
const changed: string[] = [];
const secretTracked: string[][] = [];
for (let i = 0; fields[i];) {
const entry = /^[RC]/.test(fields[i++]!) ? [fields[i++]!, fields[i++]!] : [fields[i++]!];
changed.push(...entry);
if (entry.some(f => SECRET_NAME.test(f))) secretTracked.push(entry);
}
const tracked = git([...raw, '-M', mergeBase, '--', '.', ...secretTracked.flat().map(f => `:(exclude,literal)${f}`)], root);
const broken = failed(tracked, 'git diff');
if (broken) return { base: ref, none: broken };
const redacted = (patch: string, what: string) => redactFindingSpans(patch) ?? `# draft: ${what} left out (it could not be redacted safely)\n`;
const untracked = others.stdout.split('\0').filter(f => f && !inRun(f)).sort();
const parts = [tracked.stdout];
const parts = [
...tracked.stdout.split(/^(?=diff --git )/m).map(p => redacted(p, p.slice(0, p.indexOf('\n')))),
...secretTracked.map(e => `# draft: ${e.join(' -> ')} left out (${e.length > 1 ? 'a rename or copy of a file whose name looks like a secret' : 'its name looks like a secret'})\n`),
];
for (const f of untracked.slice(0, UNTRACKED_MAX)) {
if (SECRET_NAME.test(f)) { parts.push(`# draft: untracked ${f} left out (its name looks like a secret)\n`); continue; }
const d = git([...raw, '--no-index', '--', '/dev/null', f], root);
const bad = failed(d, `git diff --no-index ${f}`, [0, 1]);
if (bad) return { base: ref, none: bad };
parts.push(d.stdout);
parts.push(redacted(d.stdout, `untracked ${f}`));
}
if (untracked.length > UNTRACKED_MAX) parts.push(`# draft: ${untracked.length - UNTRACKED_MAX} more untracked files not shown\n`);
const text = parts.join('');
@@ -94,7 +111,7 @@ export function captureDraft(cwd: string, dir: string, out: string, base?: strin
fs.writeFileSync(file, text, process.platform === 'win32' ? { flag: 'wx' } : { flag: 'wx', mode: 0o444 });
const bytes = fs.readFileSync(file);
return { base: ref, root, merge_base: mergeBase, sha256: crypto.createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length,
...(bytes.length > INLINE_DRAFT_BYTES ? { shown_bytes: INLINE_DRAFT_BYTES } : {}), files: [...new Set([...names.stdout.split('\n').filter(Boolean), ...untracked])].sort() };
...(bytes.length > INLINE_DRAFT_BYTES ? { shown_bytes: INLINE_DRAFT_BYTES } : {}), files: [...new Set([...changed, ...untracked])].sort() };
}
/** The merged brief (before the shared blocks) and the receipt line (after RESULT FORMAT) a lean phase's native prompt adds. */
+21
View File
@@ -137,6 +137,27 @@ export function resolveBase(ref: string, cwd: string, head?: string): { ref: str
return sha ? { ref, sha } : null;
}
export type ResolvedBase = NonNullable<ReturnType<typeof resolveBase>>;
/** Why resolveBase read another ref than the name given (`local main is behind origin/main; base is origin/main`); null when the name stood as given. */
export function baseNote(name: string, base: ResolvedBase): string | null {
if (base.local === 'fallback') return `${base.unrelatedRemote ? `${base.unrelatedRemote} shares no history with HEAD` : `no remote-tracking branch for ${name}`}; base is the local ${name}, which may lag its remote`;
if (!base.local) return null;
return `${{ unrelated: `local ${name} shares no history with HEAD`, missing: `no local branch ${name}`, behind: `local ${name} is behind ${base.ref}`, ahead: `local ${name} is ahead of ${base.ref}`, diverged: `local ${name} has diverged from ${base.ref}` }[base.local]}; base is ${base.ref}`;
}
/**
* A --base argument as the commit a review or ship bin reads (GST-1036): resolveBase against HEAD, so a bare `main`
* reads origin/main over a stale local main, with the note on stderr as `<bin>: <note>` when it read another ref than
* the name. An unresolvable name comes back as given, so the caller's own git error still names it.
*/
export function baseArg(bin: string, name: string, cwd: string): string {
const base = resolveBase(name, cwd, 'HEAD');
const note = base && baseNote(name, base);
if (note) process.stderr.write(`${bin}: ${note}\n`);
return base?.sha ?? name;
}
/** A word for a printed shell line: as is when it is plain, single-quoted otherwise (ref names may hold `;`, `$`, `(`, `{1,2}`). */
function shellWord(s: string): string {
return /^[A-Za-z0-9._\/@^~+:-]+$/.test(s) ? s : `'${s.replace(/'/g, "'\\''")}'`;
+8
View File
@@ -83,6 +83,8 @@ export interface PregateCheck {
/** A remote_gate receipt accepted from a stamp-only predecessor tree (lib/pregate/remote-receipt.ts): the gated tree, the tree it was accepted for, the policy, and every differing path with its stamp rule. */
export interface PregateReceiptSubstitution { gated_tree: string; accepted_for: string; policy: string; files: Array<{ path: string; rule: string }> }
export interface PregateRemote { lane: string; platform: string; workflow: string; job: string; tests: string[]; receipt: string | null; cleared_by?: string; command?: string; substitution?: PregateReceiptSubstitution }
/** An owner-granted flaky exception (lib/pregate/flaky-exception.ts): the runs, cases and grant that cleared one obligation, bound to one head and tree. */
export interface PregateException { lane: string; repo: string; pr: number; head: string; tree: string; runs: string[]; cases: string[]; grant: string; by: string; words: string; binding: string }
export interface PregateFile {
schema_version: 1; tree: string; checks: PregateCheck[]; run?: string; stage1_ms?: number; stage2_ms?: number;
// C-pregate (C8): head/base identity, the policy sources, persisted requires-remote obligations and the one-line verdict.
@@ -93,6 +95,8 @@ export interface PregateFile {
policy_user_path?: string;
/** This run's scratch directory under the state root (logs, scan files). */
scratch?: string;
/** Obligations cleared from runs with failures under an owner's grant (`clear --flaky-exception`). */
exceptions?: PregateException[];
}
export interface ShipReceipt {
schema_version: 1; head: string; base: string; pr?: number; version?: string; gated_tree?: string;
@@ -123,6 +127,8 @@ export interface ShipReceipt {
review_targeted?: { classes: string[]; rules: string; brief_sha: string; product_patch_id: string; status: 'done' | 'failed' | 'not-run'; findings: number; raised_by: string };
/** Step 5 failures gstack-base-red proved are the base's own (lib/base-red.ts): a conditional receipt the queue refuses until /ship --resume rewrites it without this block. */
base_red?: { cases: string[]; files: string[]; base: string; lane: string; expires_at: string };
/** The pregate's owner-granted flaky exceptions (gstack-pregate clear --flaky-exception): pregate only, never a required CI check. */
flaky_exception?: Array<{ lane: string; runs: string[]; cases: string[]; grant: string; by: string }>;
/** The base policy's review_exclude_paths at the reviewed head (lib/review-exclude.ts); absent when the base declares none. Carry and the queue compare `digest`. */
review_exclude?: { source: string; patterns: string[]; applied: string[]; excluded: number; excluded_bytes: number; kept: number; gate_tagged: string[]; patterns_sha256: string; list_sha256: string; digest: string };
}
@@ -234,6 +240,7 @@ export const ARTIFACT_SCHEMAS = {
head: str, base: str, generated_at: str, policy: str, policy_digest: str, policy_user_path: str, registry: str, verdict: str, scratch: str,
requires_remote: { type: 'array', items: { type: 'object', required: ['lane', 'platform', 'tests', 'receipt'], properties: { lane: str, platform: str, workflow: str, job: str, tests: strList, receipt: nullableStr, cleared_by: str, command: str,
substitution: { type: 'object', required: ['gated_tree', 'accepted_for', 'policy', 'files'], properties: { gated_tree: str, accepted_for: str, policy: str, files: { type: 'array', items: { type: 'object', required: ['path', 'rule'], properties: { path: str, rule: str } } } } } } } },
exceptions: { type: 'array', items: { type: 'object', required: ['lane', 'repo', 'pr', 'head', 'tree', 'runs', 'cases', 'grant', 'by', 'words', 'binding'], properties: { lane: str, repo: str, pr: { type: 'integer' }, head: str, tree: str, runs: strList, cases: strList, grant: str, by: str, words: str, binding: str } } },
},
},
'ship-receipt': {
@@ -250,6 +257,7 @@ export const ARTIFACT_SCHEMAS = {
carry: { type: 'object', required: ['from', 'reason', 'product_patch_id'], properties: { from: str, reason: str, product_patch_id: str, changed_paths: strList, merge_commits: { type: 'integer', minimum: 0 }, range_diff: str, covers: strList, reruns: strList, trees: strList, ancestry: { enum: ['linear', 'rewritten'] } } },
head_tree: str, product_patch_id: str, gstack_version: str,
base_red: { type: 'object', required: ['cases', 'files', 'base', 'lane', 'expires_at'], properties: { cases: strList, files: strList, base: str, lane: str, expires_at: str } },
flaky_exception: { type: 'array', items: { type: 'object', required: ['lane', 'runs', 'cases', 'grant', 'by'], properties: { lane: str, runs: strList, cases: strList, grant: str, by: str } } },
review_depth: { type: 'object', required: ['depth', 'class', 'runtime_lines', 'rules', 'base', 'gate_scan'], properties: { depth: { enum: ['light', 'standard', 'full'] }, class: { enum: ['docs', 'tests', 'code', 'gate'] }, runtime_lines: { type: 'integer', minimum: 0 }, rules: str, base: str, registry: nullableStr, gate_scan: { type: 'object', required: ['tagged', 'head'], properties: { tagged: { type: ['integer', 'null'], minimum: 0 }, head: str } }, reasons: strList, risk: { type: 'array', items: { enum: ['money', 'auth', 'secret', 'security', 'data'] } } } },
review_targeted: { type: 'object', required: ['classes', 'rules', 'brief_sha', 'product_patch_id', 'status', 'findings', 'raised_by'], properties: { classes: { type: 'array', items: { enum: ['money', 'gate', 'auth', 'secret'] } }, rules: str, brief_sha: str, product_patch_id: str, status: { enum: ['done', 'failed', 'not-run'] }, findings: { type: 'integer', minimum: 0 }, raised_by: str } },
review_exclude: { type: 'object', required: ['source', 'patterns', 'applied', 'excluded', 'excluded_bytes', 'kept', 'gate_tagged', 'patterns_sha256', 'list_sha256', 'digest'], properties: { source: str, patterns: strList, applied: strList, excluded: { type: 'integer', minimum: 0 }, excluded_bytes: { type: 'integer', minimum: 0 }, kept: { type: 'integer', minimum: 0 }, gate_tagged: strList, patterns_sha256: str, list_sha256: str, digest: str } },
+7 -3
View File
@@ -6,7 +6,10 @@
*
* Verdict file: <state root>/install-verdicts/<sha256(checkout realpath)>/<sha256(project realpath | "none")>.json,
* then the path the GSTACK_LAUNCH line names as GSTACK_INSTALL_VERDICT, then
* the schema 1 file keyed by the checkout alone (<sha256(checkout)>.json).
* the schema 1 file keyed by the checkout alone (<sha256(checkout)>.json). An
* install-profile verdict (for=review-voice) at the first path yields to the
* launched GSTACK_INSTALL_VERDICT, so a reviewer's install on a shared machine
* never shadows the session's own verdict (GST-1161).
* The project is the working directory's git toplevel unless that is the
* checkout itself. It is the one record the bun shim, the Bash twin,
* lib/pregate/runtime.ts and admission read.
@@ -102,11 +105,12 @@ export function installProject(checkout: string, cwd: string = process.cwd()): s
try { const real = fs.realpathSync(top); return real === checkout ? null : real; } catch { return null; }
}
/** The verdict file admission reads: (checkout, project), then GSTACK_INSTALL_VERDICT, then the schema 1 file. */
/** The verdict file admission reads: (checkout, project), then GSTACK_INSTALL_VERDICT, then the schema 1 file. An install-profile verdict at (checkout, project) admits no workflow, so the launched GSTACK_INSTALL_VERDICT outranks it (GST-1161). */
export function findInstallVerdict(checkout: string, project: string | null, env: Env): string {
const stateRoot = resolveStateRoot(env);
const keyed = installVerdictPath(checkout, stateRoot, project);
if (fs.existsSync(keyed)) return keyed;
if (fs.existsSync(keyed) && !INSTALL_PROFILES.includes(readInstallVerdict(keyed)?.for ?? '')) return keyed;
if (fs.existsSync(keyed) && (!env.GSTACK_INSTALL_VERDICT || !fs.existsSync(env.GSTACK_INSTALL_VERDICT))) return keyed;
if (env.GSTACK_INSTALL_VERDICT && fs.existsSync(env.GSTACK_INSTALL_VERDICT)) return env.GSTACK_INSTALL_VERDICT;
const legacy = legacyInstallVerdictPath(checkout, stateRoot);
return fs.existsSync(legacy) ? legacy : keyed;
+4 -1
View File
@@ -17,6 +17,7 @@
import { spawnSync } from 'node:child_process';
import * as fs from 'node:fs';
import * as path from 'node:path';
import { resolveBase } from './gate-diff/git';
import { findSection } from './markdown-sections';
import { scan } from './redact-engine';
import type { ResultCodeName } from './result-codes';
@@ -55,9 +56,11 @@ export function readCapture(file: string, roots: string[], what: string): string
return cleanText(fs.readFileSync(real), `${what} file`);
}
/** Resolve `ref` to a commit sha without letting it be read as an option. */
/** Resolve `ref` to a commit sha without letting it be read as an option; a bare branch name reads origin's tracking branch first (resolveBase, GST-1036). */
export function resolveCommit(cwd: string, ref: string): string | ShotError {
if (!ref || ref.startsWith('-') || /\s/.test(ref)) return { code: 'PR_SHOTS_INPUT_REFUSED', message: `ref ${JSON.stringify(ref)} is not a plain ref` };
const base = resolveBase(ref, cwd, 'HEAD');
if (base) return base.sha;
const r = git(cwd, ['rev-parse', '--verify', '--quiet', '--end-of-options', `${ref}^{commit}`]);
return r.status === 0 ? r.stdout.trim() : { code: 'PR_SHOTS_INPUT_NOT_FOUND', message: `base ref ${ref}` };
}
+403
View File
@@ -0,0 +1,403 @@
/**
* pregate flaky exception (GST-1096, docs/pregate.md#flaky-exception): an owner-granted exception that lets GitHub
* Actions runs with failures clear one requires-remote obligation. `gstack-pregate clear --remote <lane> --run <run>
* --flaky-exception "<test file>::<case>" … --pr <n> --grant <approval id>` (lib/pregate/index.ts clearByRuns) takes
* the runs only when:
*
* - every failure is named from the run's own records: each job of the attempt reconciles (only test-shard jobs, and
* the aggregate that needs them, may fail), the plan and every shard's strict result are present and complete (a
* timed-out or unattributed shard is incomplete evidence), and each failed shard's log names no failure its result
* omits;
* - the named cases are exactly the failures, at most three, none in a paid test file or a test of a security scan,
* and each file is outside the PR's diff and the diff's import closure (lib/pregate/import-graph.ts);
* - the runs tested pregate.json's own head and tree (no stamp-only substitution), the PR's head is that head, and an
* approved gstack-approvals row in the owner's words carries the scope `exceptionBinding` computes over repository,
* PR, head, tree, lane, runs with their attempts and cases, so it cannot be rebound to another head or case list.
*
* It is pregate only: nothing here touches a required CI check, which still needs its own green run at the head.
* base_red is not used: it proves a failure by reproducing it on the base, and a timing flake passes there.
*/
import { createHash } from 'node:crypto';
import { spawnSync } from 'node:child_process';
import * as path from 'node:path';
import { locate, readRecord } from '../approval-record';
import type { PregateException, PregateFile } from '../headless-artifacts';
import { parseRunRef, verifyRun, type ApiJob, type ApiRun, type RunArtifactDeps, type RunDeps, type RunEvidence, type RunProfile } from '../run-evidence';
import { wtreeFingerprint } from '../script-invocation';
import { resolveBaseBranch } from '../ship-policy';
import type { FreeCiPlan, FreeCiResult, FreeShardOutcome } from '../../scripts/test-free-shards';
import { isConfigUnavailable, loadConfigFromBase } from './config';
import { buildGraph, testsFor } from './import-graph';
export type FailureDeps = RunArtifactDeps;
export interface GrantRow { id: string; outcome: string; scope: string; words: string; by: string }
export interface FlakyInput { cases: string[]; pr?: number; grant?: string; grantRow?: (id: string) => GrantRow | null }
export type FlakyRefusal = { refused: 'usage' | 'PREGATE_RECEIPT_INVALID'; message: string; fix?: string };
/** What a flaky exception is granted for; `exceptionBinding` hashes exactly these fields. */
export type ExceptionSubject = Pick<PregateException, 'lane' | 'repo' | 'pr' | 'head' | 'tree' | 'runs' | 'cases'>;
export interface FlakyRuns { evidence: RunEvidence[]; red: Array<{ evidence: RunEvidence; failures: string[] }> }
export const MAX_FLAKY_CASES = 3;
export const FLAKY_SCOPE_PREFIX = 'flaky-exception:';
/** The receipt field an exception clear adds; verify and verdictOf read it back. */
export const EXCEPTION_RECEIPT = / exception=(\S+)/;
/** The strict shard runner's artifacts and job names (scripts/test-free-shards.ts --ci-run) in the workflows that upload them. */
interface ShardLayout { plan: string; result: string; logs: string; shardJob: string; aggregate: string }
const SHARD_LAYOUTS: Record<string, ShardLayout> = {
'free-tests.yml': { plan: 'free-plan', result: 'free-result-', logs: 'free-test-shard-logs-', shardJob: 'free-suite', aggregate: 'free-tests' },
'windows-free-tests.yml': { plan: 'windows-plan', result: 'windows-result-', logs: 'windows-free-test-shard-logs-', shardJob: 'windows-free-shard', aggregate: 'windows-free-tests' },
};
/** A test of a security scanner (/cso, secrets, gitleaks, the sealed guard, redaction, OSV): never excepted. */
const SECURITY_TEST = /(?:^|[-_.])(?:cso|secrets?|gitleaks|sealed|redact\w*|osv|security|sanitize\w*|injection|inject)(?=[-_.])/;
const SHA = /^[0-9a-f]{40}$/;
const LOG_FILE_HEADER = /^(\S.*\.test\.(?:[cm]?[jt]s|tsx|jsx)):$/;
const sha256 = (text: string) => createHash('sha256').update(text).digest('hex');
const short = (s: string | undefined) => (s ?? '').slice(0, 12);
const shellQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`;
/** The gstack-approvals scope that grants one exception: a digest of every field it binds, cases in sorted order. */
export function exceptionBinding(e: ExceptionSubject): string {
const lines = [`lane=${e.lane}`, `repo=${e.repo}`, `pr=${e.pr}`, `head=${e.head}`, `tree=${e.tree}`, ...e.runs.map(r => `run=${r}`), ...[...e.cases].sort().map(c => `case=${c}`)];
return FLAKY_SCOPE_PREFIX + sha256(lines.join('\n'));
}
/** The approvals rows of this checkout's branch record (lib/approval-record.ts), looked up by id. */
export function approvalGrants(repoRoot: string, env: NodeJS.ProcessEnv = process.env): (id: string) => GrantRow | null {
return id => {
const loc = locate({ cwd: repoRoot, env });
return 'code' in loc ? null : readRecord(loc).rows.find(r => r.id === id) ?? null;
};
}
/** The `--flaky-exception` values as `<file>::<case>` strings, or the usage refusal. */
export function parseCases(cases: string[]): string[] | FlakyRefusal {
if (cases.length > MAX_FLAKY_CASES) return { refused: 'usage', message: `--flaky-exception names at most ${MAX_FLAKY_CASES} cases; got ${cases.length}` };
const bad = cases.find(c => { const i = c.indexOf('::'); return i <= 0 || i + 2 >= c.length; });
if (bad !== undefined) return { refused: 'usage', message: `--flaky-exception takes "<test file>::<case>", the file and the test name as the run printed them; got ${JSON.stringify(bad)}` };
if (new Set(cases).size !== cases.length) return { refused: 'usage', message: '--flaky-exception names each case once' };
return cases;
}
/** One-line summary for verify's PREGATE line: `pass-with-exception (<cases>; grant <id>)`. */
export function describeExceptions(file: PregateFile): string | null {
const list = file.exceptions ?? [];
if (!list.length) return null;
return `pass-with-exception (${list.flatMap(e => e.cases).join(', ')}; grant ${list.map(e => e.grant).join(', ')})`;
}
/** READY's line for each exception: it waives the pregate obligation, never a required CI check. */
export function flakyExceptionLines(file: PregateFile): string[] {
return (file.exceptions ?? []).map(e => `FLAKY_EXCEPTION: ${e.lane} cases=${e.cases.join(' | ')} run=${e.runs.join(',')} grant=${e.grant} by=${e.by} (pregate only; every required CI check still needs its own green run at this head)`);
}
/** verify's offline check: every exception receipt has its entry, bound to this head and tree, with an intact binding; null when all hold. */
export function exceptionProblem(file: PregateFile): string | null {
const list = file.exceptions ?? [];
const remote = file.requires_remote ?? [];
for (const r of remote) {
const grant = EXCEPTION_RECEIPT.exec(r.receipt ?? '')?.[1];
if (!grant) continue;
const e = list.find(x => x.lane === r.lane && x.grant === grant);
if (!e) return `${r.lane}'s receipt names flaky exception grant ${grant}, but pregate.json has no exceptions entry for it; clear again`;
if (e.head !== file.head || e.tree !== file.tree) return `${r.lane}'s flaky exception (grant ${grant}) is bound to head ${short(e.head)} tree ${short(e.tree)}, not pregate.json's head ${short(file.head)} tree ${short(file.tree)}; a new head needs a new run and a new grant`;
if (exceptionBinding(e) !== e.binding) return `${r.lane}'s flaky exception (grant ${grant}): the binding does not match its recorded fields (granted scope ${e.binding}); clear again`;
const runs = / runs=(\S+)/.exec(r.receipt ?? '')?.[1];
if (runs !== e.runs.join(',')) return `${r.lane}'s receipt names runs ${runs ?? 'none'}, but its flaky exception (grant ${grant}) was granted for ${e.runs.join(',')}; clear again`;
}
const orphan = list.find(e => !remote.some(r => r.lane === e.lane && EXCEPTION_RECEIPT.exec(r.receipt ?? '')?.[1] === e.grant));
return orphan ? `pregate.json records a flaky exception for ${orphan.lane} (grant ${orphan.grant}) that no receipt uses; clear again` : null;
}
/** Why `file`'s exceptions cannot stand for this PR head: each binds the PR and head it was granted for, and a same-tree commit or another PR reusing the record never inherits it. */
export function exceptionConsumerProblem(file: PregateFile, head: string, pr?: string): string | null {
const e = (file.exceptions ?? []).find(x => x.head !== head || (pr !== undefined && String(x.pr) !== pr));
return e ? `flaky exception grant ${e.grant} is bound to PR #${e.pr} at ${short(e.head)}, not ${pr ? `PR #${pr} at ` : ''}${short(head)}; a new head needs a new run and a new grant` : null;
}
/** Why red run `id` no longer stands as completed, failed attempt `attempt`; read again once the whole clear is assembled. */
export function redRunChanged(deps: RunDeps, id: number, attempt: number): string | null {
const again = deps.run(id);
return again.run_attempt === attempt && again.status === 'completed' && again.conclusion === 'failure' ? null : `run ${id} moved to attempt ${again.run_attempt} (${again.status === 'completed' ? again.conclusion : again.status}) while it was being verified`;
}
/** verify's ok-line suffix naming each exception. */
export function exceptionSummary(file: PregateFile): string {
return (file.exceptions ?? []).map(e => `flaky exception ${e.cases.join(', ')} (grant ${e.grant}, by ${e.by}, run ${e.runs.join(',')})`).join('; ');
}
const invalid = (lane: string, reason: string, detail: string, fix?: string): FlakyRefusal => ({ refused: 'PREGATE_RECEIPT_INVALID', message: `FLAKY_EXCEPTION: refused reason=${reason} — ${detail}; ${lane} stays uncleared`, ...(fix ? { fix } : {}) });
const errText = (e: unknown) => String((e as Error)?.message ?? e).slice(0, 300);
/**
* The runs for `names` (one per profile, matched by workflow): a green run verifies as `clear --run` verifies it, a red
* run through `readRunFailures`. At least one must be red, or no exception is needed.
*/
export function flakyRuns(lane: string, check: { repo: string; deps: RunDeps; profiles: Record<string, RunProfile>; now: Date; failures?: FailureDeps }, names: string[], refs: string[], vetoHead: string | undefined): FlakyRuns | FlakyRefusal {
if (!check.failures) return { refused: 'usage', message: 'the run artifacts cannot be read here (no GitHub origin), so failures cannot be named' };
const runs: Array<{ ref: string; id: number; run: ApiRun }> = [];
for (const ref of refs) {
const id = parseRunRef(ref, check.repo);
if (id === null) return invalid(lane, 'run_ref_invalid', `${JSON.stringify(ref)} is not a run id or a run URL on ${check.repo}`);
try { runs.push({ ref, id, run: check.deps.run(id) }); }
catch (e) { return invalid(lane, 'api_error', `reading run ${id} failed: ${errText(e)}`, `check gh auth status and that gh can read ${check.repo}'s Actions runs, then rerun the same clear`); }
}
if (runs.every(r => r.run.status === 'completed' && r.run.conclusion === 'success')) return invalid(lane, 'run_green', `${runs.map(r => `run ${r.id} attempt ${r.run.run_attempt}`).join(', ')} passed; clear with --run alone, no exception is needed`);
const out: FlakyRuns = { evidence: [], red: [] };
const used = new Set<number>();
for (const name of names) {
const profile = check.profiles[name]!;
const pick = runs.find(r => !used.has(r.id) && r.run.path === `.github/workflows/${profile.workflow}`) ?? runs.find(r => !used.has(r.id));
if (!pick) return { refused: 'usage', message: `${lane} needs one run per profile (${names.join(', ')})` };
used.add(pick.id);
if (pick.run.conclusion === 'success') {
const v = verifyRun(check.deps, { repo: check.repo, runRef: pick.ref, profileName: name, profile, vetoHeads: vetoHead ? [vetoHead] : [], now: check.now });
if (!v.ok) return invalid(lane, v.reason, `${name}: ${v.detail}`);
out.evidence.push(v.evidence);
continue;
}
const r = readRunFailures(check.deps, check.failures, { repo: check.repo, id: pick.id, run: pick.run, profileName: name, profile, now: check.now });
if (!r.ok) return invalid(lane, r.reason, r.detail);
out.evidence.push(r.evidence);
out.red.push({ evidence: r.evidence, failures: r.failures });
}
return out;
}
type Read<T> = { ok: true } & T | { ok: false; reason: string; detail: string };
const fail = (reason: string, detail: string) => ({ ok: false as const, reason, detail });
/** The one JSON file of artifact `name`, parsed; a message when it is missing, ambiguous or unreadable. */
function jsonArtifact<T>(art: FailureDeps, id: number, name: string): T | { error: string } {
let files: Record<string, string>;
try { files = art.artifactFiles(id, name); } catch (e) { return { error: errText(e) }; }
const json = Object.entries(files).filter(([f]) => f.endsWith('.json'));
if (json.length !== 1) return { error: `${name} holds ${json.length} JSON files, not one` };
try { return JSON.parse(json[0]![1]) as T; } catch (e) { return { error: `${json[0]![0]} is not JSON: ${errText(e)}` }; }
}
const isError = (v: unknown): v is { error: string } => !!v && typeof v === 'object' && 'error' in v && typeof (v as { error: unknown }).error === 'string';
const escapeRe = (s: string) => s.replace(/[.*+?^${{}()|[\]\\]/g, '\\$&');
/**
* A red run under `profile` read from its own records (B8: a red run uploads no tree.json): every job of the attempt, the
* plan, every shard's strict result and each failed shard's logs. Returns the evidence (the plan's files, the tests the
* shards ran) and the failed cases as `<file>::<test name>`, or the refusal naming what could not be reconciled.
*/
function readRunFailures(deps: RunDeps, art: FailureDeps, o: { repo: string; id: number; run: ApiRun; profileName: string; profile: RunProfile; now: Date }): Read<{ evidence: RunEvidence; failures: string[] }> {
const { run, profile: p, id } = o;
const layout = SHARD_LAYOUTS[p.workflow];
if (!layout) return fail('no_shard_results', `${p.workflow} uploads no strict shard results gstack can read (only ${Object.keys(SHARD_LAYOUTS).join(' and ')} do), so its failures cannot be named`);
const at = `run ${id} attempt ${run.run_attempt}`;
try {
if ((run.repository?.full_name ?? '').toLowerCase() !== o.repo.toLowerCase()) return fail('other_repository', `${at} belongs to ${run.repository?.full_name ?? 'an unknown repository'}, not ${o.repo}`);
if ((run.head_repository?.full_name ?? '').toLowerCase() !== o.repo.toLowerCase()) return fail('fork_run', `${at} ran for ${run.head_repository?.full_name ?? 'an unknown repository'}, not ${o.repo}`);
if (run.path !== `.github/workflows/${p.workflow}`) return fail('workflow_mismatch', `${at} ran ${run.path ?? 'an unknown workflow'}, not .github/workflows/${p.workflow}`);
if (!p.events.includes(run.event)) return fail('event_mismatch', `${at} is a ${run.event} run; ${o.profileName} accepts ${p.events.join(', ')}`);
if (run.status !== 'completed') return fail('run_in_progress', `${at} is ${run.status}`);
if (run.conclusion !== 'failure') return fail('run_not_failure', `${at} concluded ${run.conclusion}; only a run that finished with test failures can carry an exception (a cancelled or timed-out run is incomplete evidence)`);
if (!SHA.test(run.head_sha)) return fail('api_error', `${at} has no head commit`);
const jobs = deps.jobs(id, run.run_attempt);
const finishedAt = jobs.map(j => j.completed_at).filter((t): t is string => !!t).sort().pop() ?? run.updated_at;
const finished = Date.parse(finishedAt ?? '');
const maxAge = p.max_age_hours ?? 24;
if (!Number.isFinite(finished)) return fail('api_error', `${at} has no completion time`);
if (o.now.getTime() - finished > maxAge * 3600_000) return fail('run_stale', `${at} finished ${finishedAt}, more than ${maxAge} h before now`);
const newer = deps.runsForHead(p.workflow, run.head_sha).find(r => r.id !== id && (r.run_started_at ?? r.created_at ?? '') >= (run.created_at ?? ''));
if (newer) return fail('newer_run', `run ${newer.id} of ${p.workflow} on ${short(run.head_sha)} started after ${at}; clear with the newest run`);
const shardJobs = reconcileJobs(jobs, layout, p, at);
if ('reason' in shardJobs) return fail(shardJobs.reason, shardJobs.detail);
const plan = jsonArtifact<FreeCiPlan>(art, id, layout.plan);
if (isError(plan)) return fail('shard_incomplete', `${at} has no readable ${layout.plan} (${plan.error})`);
if (plan.version !== 1 || typeof plan.id !== 'string' || typeof plan.revision !== 'string' || !Array.isArray(plan.shards) || !plan.shards.length
|| plan.shards.some((s, i) => s.shard !== i + 1 || !Array.isArray(s.files) || s.files.some(f => typeof f !== 'string'))) return fail('result_mismatch', `${at}'s ${layout.plan} is not a strict shard plan`);
const headTree = deps.commitTree(run.head_sha);
if (!headTree) return fail('api_error', `git cannot read the tree of ${run.head_sha}`);
if (plan.revision !== run.head_sha && (!SHA.test(plan.revision) || deps.commitTree(plan.revision) !== headTree)) return fail('tree_mismatch', `${at} tested ${short(plan.revision)}, whose tree is not its head ${short(run.head_sha)}'s tree ${short(headTree)}`);
if (shardJobs.size !== plan.shards.length || plan.shards.some(s => !shardJobs.has(s.shard))) return fail('shard_mismatch', `${at} has ${layout.shardJob} job(s) for shard(s) ${[...shardJobs.keys()].sort((a, b) => a - b).join(', ') || 'none'}, but its plan has ${plan.shards.length} shard(s)`);
const failures: string[] = [];
let tests = 0;
for (const s of plan.shards) {
const res = jsonArtifact<FreeCiResult>(art, id, `${layout.result}${s.shard}`);
if (isError(res)) return fail('shard_incomplete', `shard ${s.shard} has no readable ${layout.result}${s.shard} (${res.error})`);
if (res.planId !== plan.id || res.revision !== plan.revision || res.outcome?.shard !== s.shard || JSON.stringify(res.outcome.files) !== JSON.stringify(s.files)) return fail('result_mismatch', `shard ${s.shard}'s result is not shard ${s.shard} of plan ${plan.id}`);
const named = shardFailures(res, s.shard);
if ('reason' in named) return fail(named.reason, named.detail);
const job = shardJobs.get(s.shard)!;
if ((job.conclusion === 'failure') !== (named.final.length > 0)) return fail('shard_mismatch', `shard ${s.shard}'s job concluded ${job.conclusion}, but its result names ${named.final.length} final failure(s)`);
if (job.conclusion === 'failure') {
const problem = logProblem(art, id, `${layout.logs}${s.shard}`, s.shard, s.files, named.all);
if (problem) return fail(problem.reason, problem.detail);
}
failures.push(...named.final);
tests += res.outcome.summary?.testsRan ?? 0;
}
const again = deps.run(id);
if (again.run_attempt !== run.run_attempt || again.status !== 'completed' || again.conclusion !== run.conclusion) return fail('run_changed', `run ${id} moved to attempt ${again.run_attempt} (${again.status === 'completed' ? again.conclusion : again.status}) while it was being verified`);
return { ok: true, evidence: { run_id: id, run_attempt: run.run_attempt, head_sha: run.head_sha, tree: headTree, profile: o.profileName, event: run.event, finished_at: finishedAt!, files: plan.shards.flatMap(s => s.files), tests }, failures: [...new Set(failures)] };
} catch (e) {
return fail('api_error', `reading run ${id} failed: ${errText(e)}`);
}
}
/** Shard number → job, once every job of the attempt is accounted for: only shard jobs and the aggregate may fail. */
function reconcileJobs(jobs: ApiJob[], layout: ShardLayout, p: RunProfile, at: string): Map<number, ApiJob> | { reason: string; detail: string } {
const shardRe = new RegExp(`^${escapeRe(layout.shardJob)} \\((\\d+)\\)$`);
const shards = new Map<number, ApiJob>();
for (const j of jobs) {
if (j.conclusion === null) return { reason: 'shard_incomplete', detail: `${at}'s ${j.name} job has not finished` };
const m = shardRe.exec(j.name);
if (m) {
if (shards.has(Number(m[1]))) return { reason: 'shard_mismatch', detail: `${at} has two jobs named ${j.name}` };
if (j.conclusion !== 'success' && j.conclusion !== 'failure') return { reason: 'shard_incomplete', detail: `${at}'s ${j.name} job concluded ${j.conclusion}` };
shards.set(Number(m[1]), j);
continue;
}
if (j.name === layout.aggregate) continue;
const allowed = p.jobs.includes(j.name) ? ['success'] : ['success', 'skipped', 'neutral'];
if (!allowed.includes(j.conclusion)) return { reason: 'unnamed_failure', detail: `${at}'s ${j.name} job concluded ${j.conclusion}; only test-shard failures can be named` };
}
const missing = p.jobs.find(n => !jobs.some(j => j.name === n));
if (missing) return { reason: 'job_missing', detail: `${at} has no job named ${missing}` };
const aggregate = jobs.filter(j => j.name === layout.aggregate);
if (aggregate.length !== 1) return { reason: 'job_missing', detail: `${at} has ${aggregate.length} jobs named ${layout.aggregate}` };
if (![...shards.values()].some(j => j.conclusion === 'failure')) return { reason: 'unnamed_failure', detail: `${at} failed, but no ${layout.shardJob} job did, so the failure is not a test case` };
if (aggregate[0]!.conclusion !== 'failure') return { reason: 'shard_mismatch', detail: `${at}'s ${layout.aggregate} job concluded ${aggregate[0]!.conclusion} although a shard failed` };
return shards;
}
function completeSummary(o: FreeShardOutcome): boolean {
const s = o.summary;
return !!s && Number.isInteger(s.testsRan) && s.testsRan! >= 0 && s.filesRan === o.files.length && (o.files.length === 0 || s.sawTerminalSummary === true);
}
/**
* A shard's final failures (`<file>::<test>`) and every failure it recorded. A retry that passed recovered its files; a
* retry that failed replaces the first run's failures for the files it ran. Anything unattributed or incomplete refuses.
*/
function shardFailures(r: FreeCiResult, n: number): { final: string[]; all: Set<string> } | { reason: string; detail: string } {
const o = r.outcome;
const key = (f: { file: string | null; testName: string }) => `${f.file}::${f.testName}`;
if (o.status === 'timed-out') return { reason: 'shard_incomplete', detail: `shard ${n} timed out, so the tests after the hang never ran` };
if (!completeSummary(o)) return { reason: 'shard_incomplete', detail: `shard ${n}'s result has no complete run summary` };
if (o.status === 'passed') {
if (o.exitCode !== 0 || o.failingFiles.length || o.unattributedFailures || r.retry) return { reason: 'result_mismatch', detail: `shard ${n} passed with failures recorded` };
return { final: [], all: new Set() };
}
if (o.status !== 'failed') return { reason: 'result_mismatch', detail: `shard ${n} has status ${String(o.status)}` };
if (o.unattributedFailures) return { reason: 'unnamed_failure', detail: `shard ${n}: ${o.unattributedFailures} failure(s) the runner could not attribute to a test file` };
const first = o.failures ?? [];
const unnamed = first.filter(f => !f.file || !o.files.includes(f.file) || !f.testName);
if (!first.length || unnamed.length) return { reason: 'unnamed_failure', detail: `shard ${n} failed ${first.length ? `with ${unnamed.length} failure(s) not attributed to one of its files` : 'without naming a failure'}` };
if (JSON.stringify([...new Set(first.map(f => f.file))].sort()) !== JSON.stringify([...o.failingFiles].sort())) return { reason: 'result_mismatch', detail: `shard ${n}'s named failures and failing files disagree` };
const all = new Set(first.map(key));
const t = r.retry;
if (!t) return { final: [...all], all };
if (t.status === 'timed-out' || !completeSummary(t)) return { reason: 'shard_incomplete', detail: `shard ${n}'s retry did not complete` };
if (t.files.some(f => !o.failingFiles.includes(f))) return { reason: 'result_mismatch', detail: `shard ${n}'s retry ran files that had not failed` };
const again = t.failures ?? [];
if (t.unattributedFailures || (t.status === 'failed' && (!again.length || again.some(f => !f.file || !t.files.includes(f.file))))) return { reason: 'unnamed_failure', detail: `shard ${n}'s retry failed without naming each failure` };
if (t.status === 'passed' && (again.length || t.exitCode !== 0)) return { reason: 'result_mismatch', detail: `shard ${n}'s retry passed with failures recorded` };
for (const f of again) all.add(key(f));
const final = [...first.filter(f => !t.files.includes(f.file!)), ...again].map(key);
return { final: [...new Set(final)], all };
}
/** Why a failed shard's logs do not reconcile with its result: missing, an unhandled error between tests, or a failure the result omits. */
function logProblem(art: FailureDeps, id: number, name: string, n: number, planned: string[], recorded: Set<string>): { reason: string; detail: string } | null {
let files: Record<string, string>;
try { files = art.artifactFiles(id, name); } catch (e) { return { reason: 'logs_missing', detail: `shard ${n} failed and has no readable ${name} (${errText(e)})` }; }
const logs = Object.entries(files).filter(([f]) => f.endsWith('.log'));
if (!logs.length) return { reason: 'logs_missing', detail: `shard ${n} failed and its ${name} holds no .log file` };
const canonical = (printed: string) => {
const stripped = printed.replace(/\\/g, '/').replace(/^(?:\.{1,2}\/)+/, '');
return planned.includes(stripped) ? stripped : planned.find(p => stripped.endsWith(`/${p}`) || p.endsWith(`/${stripped}`)) ?? stripped;
};
const { classifyBunTestOutputLine, parseBunFailureResult, stripAnsiLine } = require('../../scripts/lib/shard-engine') as typeof import('../../scripts/lib/shard-engine');
for (const [, text] of logs) {
let file: string | null = null;
let recap = false;
let unhandled = 0;
for (const raw of text.split('\n')) {
const line = stripAnsiLine(raw).replace(/^::group::/, '').replace(/\r$/, '');
if (/^\d+ tests? failed:$/.test(line)) { recap = true; file = null; continue; }
if (classifyBunTestOutputLine(line) === 'unhandled-between-tests') { unhandled++; continue; }
const header = LOG_FILE_HEADER.exec(line);
if (header) { if (!recap) file = canonical(header[1]!); continue; }
const failed = recap ? null : parseBunFailureResult(line);
if (failed !== null && !recorded.has(`${file}::${failed}`)) return { reason: 'unnamed_failure', detail: `shard ${n}'s log names ${file}::${failed}, which its result does not` };
}
if (unhandled) return { reason: 'unnamed_failure', detail: `shard ${n}'s log shows ${unhandled} unhandled error(s) between tests` };
}
return null;
}
/** The PR's changed paths against the merge base with origin/<base>, and each test the diff reaches through the import graph. */
function prScope(repoRoot: string, file: PregateFile): { diff: Set<string>; closure: Map<string, string[]> } | { error: string } {
const git = (args: string[]) => { const r = spawnSync('git', args, { cwd: repoRoot, encoding: 'utf8', timeout: 60_000, maxBuffer: 64 * 1024 * 1024 }); return r.status === 0 ? r.stdout : null; };
const base = resolveBaseBranch(repoRoot);
const mb = git(['merge-base', `refs/remotes/origin/${base}`, '--end-of-options', file.head!])?.trim();
if (!mb) return { error: `git cannot find the merge base of origin/${base} and ${short(file.head)}` };
const listed = git(['diff', '--name-status', '-z', '--no-renames', '--end-of-options', mb, file.head!]);
if (listed === null) return { error: `git diff ${short(mb)} ${short(file.head)} failed` };
const parts = listed.split('\0').filter(Boolean);
const diff = new Set<string>();
const deleted: string[] = [];
for (let i = 0; i + 1 < parts.length; i += 2) { diff.add(parts[i + 1]!); if (parts[i] === 'D') deleted.push(parts[i + 1]!); }
const loaded = loadConfigFromBase(repoRoot, base);
if (isConfigUnavailable(loaded) || loaded.errors.length) return { error: `the base branch's .gstack/pregate.json cannot be read, so its dependency declarations are unknown` };
const at = () => { const fp = wtreeFingerprint({ cwd: repoRoot }); return 'tree' in fp ? fp.tree : null; };
if (at() !== file.tree) return { error: `the working tree is not pregate.json's tree ${short(file.tree)}; the import closure must be read from that tree` };
const declarations = loaded.config.dependencies;
const graph = buildGraph(repoRoot, { declarations, extraFiles: deleted });
const closure = new Map<string, string[]>();
for (const changed of diff) for (const t of testsFor(graph, changed, declarations).tests) closure.set(t, [...(closure.get(t) ?? []), changed]);
if (at() !== file.tree) return { error: 'the working tree changed while the import closure was read' };
return { diff, closure };
}
/**
* After the runs verified and covered the obligation: the named cases must be exactly the failures, in no paid or
* security test, outside the PR's diff and import closure, the PR's head must be pregate.json's, and the grant row must
* carry this exception's binding in the owner's words. Returns the exception to record.
*/
export function flakyDecision(file: PregateFile, lane: string, check: { repo: string; failures?: FailureDeps }, runs: FlakyRuns, input: FlakyInput & { cases: string[] }, repoRoot: string): { exception: PregateException } | FlakyRefusal {
const label = runs.red.map(r => `run ${r.evidence.run_id} attempt ${r.evidence.run_attempt}`).join(', ');
const failures = [...new Set(runs.red.flatMap(r => r.failures))];
const extra = failures.filter(f => !input.cases.includes(f));
if (extra.length) return invalid(lane, 'unnamed_failure', `${label} failed ${extra.slice(0, 5).join(', ')}${extra.length > 5 ? ` and ${extra.length - 5} more` : ''}, which no --flaky-exception names`);
const notFailed = input.cases.find(c => !failures.includes(c));
if (notFailed) return invalid(lane, 'case_not_failed', `${notFailed} did not fail in ${label}; its failures are ${failures.join(', ')}`);
const files = [...new Set(input.cases.map(c => c.slice(0, c.indexOf('::'))))];
const { isPaidTestFile } = require('../../test/helpers/paid-test-set') as typeof import('../../test/helpers/paid-test-set');
const paid = files.find(f => isPaidTestFile(f));
if (paid) return invalid(lane, 'case_paid', `${paid} is a paid test file; the paid gate covers it, never an exception`);
const security = files.find(f => SECURITY_TEST.test(path.posix.basename(f)));
if (security) return invalid(lane, 'case_security', `${security} tests a security scan, which an exception never covers`);
let pr: { head_sha: string; state: string; head_repo: string | null };
try { pr = check.failures!.pull(input.pr!); }
catch (e) { return invalid(lane, 'api_error', `reading PR #${input.pr} failed: ${errText(e)}`); }
if (pr.state !== 'open') return invalid(lane, 'pr_mismatch', `PR #${input.pr} is ${pr.state}`);
if ((pr.head_repo ?? '').toLowerCase() !== check.repo.toLowerCase()) return invalid(lane, 'pr_mismatch', `PR #${input.pr}'s head is on ${pr.head_repo ?? 'an unknown repository'}, not ${check.repo}`);
if (pr.head_sha !== file.head) return invalid(lane, 'pr_mismatch', `PR #${input.pr}'s head is ${short(pr.head_sha)}, not pregate.json's head ${short(file.head)}`);
const scope = prScope(repoRoot, file);
if ('error' in scope) return invalid(lane, 'closure_failed', scope.error);
const touched = files.find(f => scope.diff.has(f));
if (touched) return invalid(lane, 'case_in_diff', `${touched} is in the PR's diff`);
const reached = files.find(f => scope.closure.has(f));
if (reached) return invalid(lane, 'case_in_closure', `${reached} depends on a file the PR changes (${scope.closure.get(reached)!.slice(0, 5).join(', ')})`);
const subject: ExceptionSubject = { lane, repo: check.repo, pr: input.pr!, head: file.head!, tree: file.tree, runs: runs.evidence.map(e => `${e.run_id}/${e.run_attempt}`), cases: [...input.cases].sort() };
const binding = exceptionBinding(subject);
if (!input.grant) {
const ask = `Accept flaky ${subject.cases.join(', ')} in run ${subject.runs.join(',')} for PR #${subject.pr} at ${short(subject.head)}? Pregate only; required CI still needs a green run.`.slice(0, 300);
return invalid(lane, 'grant_needed', `every failure in ${label} is named (${subject.cases.join(', ')}) and outside the PR's diff and its import closure; the owner must grant the exception`,
`ask the owner, record their words with gstack-approvals add --ask ${shellQuote(ask)} --words "<the owner's exact words>" --by "<owner>" --scope "${binding}" --source pregate-flaky-exception, then rerun this clear with --grant <the row id it prints>`);
}
const row = input.grantRow?.(input.grant) ?? null;
if (!row) return invalid(lane, 'grant_missing', `no gstack-approvals row ${input.grant} in this branch's record`);
if (row.scope !== binding) return invalid(lane, 'grant_mismatch', `row ${row.id}'s scope ${JSON.stringify(row.scope.slice(0, 80))} is not this exception's binding ${binding}; a grant covers one repository, PR, head, tree, lane, run attempt and case list, so a new head needs a new grant`);
if (row.outcome !== 'approved') return invalid(lane, 'grant_not_approved', `row ${row.id} records outcome ${row.outcome}, not approved`);
if (/^agent:/i.test(row.by)) return invalid(lane, 'grant_not_owner', `row ${row.id} records an agent's words (${row.by}); only the owner grants an exception`);
return { exception: { ...subject, grant: row.id, by: row.by, words: row.words, binding } };
}
+35 -11
View File
@@ -14,7 +14,7 @@ import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import * as fs from 'node:fs';
import * as path from 'node:path';
import { ARTIFACT_SCHEMAS, checkSchema, type PregateFile, type PregateReceiptSubstitution, type PregateRemote, type ValidationError } from '../headless-artifacts';
import { ARTIFACT_SCHEMAS, checkSchema, type PregateException, type PregateFile, type PregateReceiptSubstitution, type PregateRemote, type ValidationError } from '../headless-artifacts';
import { wtreeFingerprint, type WtreeResult } from '../script-invocation';
import { resolveStateRoot } from '../state-root';
import { guardsCheck } from './checks/guards';
@@ -28,6 +28,7 @@ import { timingCheck } from './checks/timing';
import { NON_DOWNGRADABLE, PREGATE_CONFIG_PATH, userPolicyAbsent } from './config';
import { sha256, withFingerprint } from './context';
import { baseBranchOf, baseMismatchFix, describeSubstitution, substituteStampOnlyTree } from './remote-receipt';
import { EXCEPTION_RECEIPT, exceptionProblem, exceptionSummary, flakyDecision, flakyRuns, parseCases, redRunChanged, type FailureDeps, type FlakyInput } from './flaky-exception';
import { buildRunCheck } from './run-check';
import { resolveBaseBranch } from '../ship-policy';
import { parseRunReceipt, parseRunRef, runChanged, runReceiptFields, uncoveredFiles, verifyRun, type ApiJob, type ApiRun, type RemoteGateRuns, type RunDeps, type RunEvidence, type RunProfile } from '../run-evidence';
@@ -134,6 +135,7 @@ export function verdictOf(file: PregateFile): string {
if (statuses.has('incomplete') || statuses.has('not_installed')) return 'incomplete';
const uncleared = (file.requires_remote ?? []).filter(r => !r.receipt);
if (uncleared.length) return `requires-remote (${uncleared.length} uncleared)`;
if ((file.requires_remote ?? []).some(r => EXCEPTION_RECEIPT.test(r.receipt ?? ''))) return 'pass-with-exception';
if (statuses.has('requires-remote')) return 'requires-remote cleared';
if (statuses.has('warn')) return 'warn';
return 'pass';
@@ -234,8 +236,12 @@ export function verifyPregate(repoRoot: string, file: PregateFile, treeNow: Wtre
// A run receipt was verified online at clear for its tree; offline it must still name this tree (or carry its substitution).
const foreignRuns = (file.requires_remote ?? []).filter(r => { const run = parseRunReceipt(r.receipt ?? ''); return run && !r.substitution && run.tree !== file.tree.slice(0, 12); });
if (foreignRuns.length) return { ok: false, code: 'PREGATE_REMOTE_UNCLEARED', message: `${foreignRuns.length} run receipt(s) verified for another tree: ${foreignRuns.map(r => `${r.lane} (${r.receipt})`).join(', ')}; clear again with runs on tree ${file.tree.slice(0, 12)}`, current, uncleared: foreignRuns };
// A flaky exception was granted for one head, tree, run attempt and case list; recorded for another, or edited, it clears nothing.
const exception = exceptionProblem(file);
if (exception) return { ok: false, code: 'PREGATE_REMOTE_UNCLEARED', message: exception, current, uncleared: [] };
const substituted = (file.requires_remote ?? []).filter(r => r.substitution).map(r => `${r.lane}: ${describeSubstitution(r.substitution!)}`);
return { ok: true, message: `pregate ${file.verdict} is current for tree ${file.tree.slice(0, 12)}${substituted.length ? `; ${substituted.join('; ')}` : ''}`, current, uncleared };
const excepted = exceptionSummary(file);
return { ok: true, message: `pregate ${file.verdict} is current for tree ${file.tree.slice(0, 12)}${substituted.length ? `; ${substituted.join('; ')}` : ''}${excepted ? `; ${excepted}` : ''}`, current, uncleared };
}
/**
@@ -259,10 +265,10 @@ function userPolicyChange(file: PregateFile): string | null {
return `${absent} now holds a user-owned policy, and pregate.json was recorded under the defaults; rerun gstack-pregate`;
}
export interface ClearInput { runUrl?: string; bundleLane?: string; receiptPath?: string; runs?: string[]; evidence?: RunCheck }
export interface ClearInput { runUrl?: string; bundleLane?: string; receiptPath?: string; runs?: string[]; evidence?: RunCheck; flaky?: FlakyInput }
/** What a run clear needs: the base branch's run profiles, the verifier's dependencies, the clock, and the remote gate's inventory. */
export interface RunCheck { repo: string; deps: RunDeps; profiles: Record<string, RunProfile>; gateRuns: RemoteGateRuns | null; now: Date; unchanged?: (p: RunProfile) => string | null; inventory: (command: string, tree: string, selected?: string[]) => string[] | { error: string } }
export type ClearDecision = { receipt: string; attested: boolean; substitution?: PregateReceiptSubstitution } | { refused: 'usage' | 'PREGATE_RECEIPT_INVALID'; message: string; fix?: string };
export interface RunCheck { repo: string; deps: RunDeps; profiles: Record<string, RunProfile>; gateRuns: RemoteGateRuns | null; now: Date; unchanged?: (p: RunProfile) => string | null; inventory: (command: string, tree: string, selected?: string[]) => string[] | { error: string }; failures?: FailureDeps }
export type ClearDecision = { receipt: string; attested: boolean; substitution?: PregateReceiptSubstitution; exception?: PregateException } | { refused: 'usage' | 'PREGATE_RECEIPT_INVALID'; message: string; fix?: string };
/**
* What `clear` may record for one obligation. A `pregate.json/remote_gate`
@@ -284,12 +290,21 @@ export type ClearDecision = { receipt: string; attested: boolean; substitution?:
* `--run` (and `--run-url` on a lane the base branch profiles) goes to
* clearByRuns, which accepts only verified Actions runs; a profiled lane
* refuses `--bundle-lane`, and the remote gate clears by runs only when the
* base declares remote_gate_runs.
* base declares remote_gate_runs. `flaky` (`--flaky-exception`) takes runs with failures the same way under an owner's
* grant (lib/pregate/flaky-exception.ts).
*/
export function clearDecision(file: PregateFile, lane: string, input: ClearInput, repoRoot: string): ClearDecision {
const list = file.requires_remote ?? [];
const target = list.find(r => r.lane === lane);
if (!target) return { refused: 'usage', message: `no requires-remote obligation named ${lane}; obligations: ${list.map(r => r.lane).join(', ') || '(none)'}` };
if (input.flaky) {
const cases = parseCases(input.flaky.cases);
if (!Array.isArray(cases)) return cases;
const refs = [...(input.runs ?? []), ...(input.runUrl ? [input.runUrl] : [])];
if (!refs.length) return { refused: 'usage', message: '--flaky-exception needs --run <id|url>: an exception reads GitHub Actions runs' };
if (!input.flaky.pr) return { refused: 'usage', message: '--flaky-exception needs --pr <n>, the pull request the grant binds' };
return clearByRuns(file, lane, refs, input.evidence, repoRoot, { ...input.flaky, cases });
}
const profiled = input.evidence && (lane === REMOTE_GATE_LANE ? input.evidence.gateRuns : input.evidence.profiles[lane]);
if (input.runs?.length || (input.runUrl && profiled)) return clearByRuns(file, lane, [...(input.runs ?? []), ...(input.runUrl ? [input.runUrl] : [])], input.evidence, repoRoot);
if (input.bundleLane && profiled && lane !== REMOTE_GATE_LANE) return { refused: 'usage', message: `${lane} has a run profile on the base branch; clear it with --run <id|url>, which verifies the run` };
@@ -372,7 +387,7 @@ function treeSubstitution(file: PregateFile, gatedTree: string, lane: string, re
* does not run (never an inventory file); any other lane needs one verified run of the profile named after it. The run
* tree must be pregate.json's tree or a stamp-only predecessor of it, exactly as a gate report's tree must.
*/
function clearByRuns(file: PregateFile, lane: string, refs: string[], check: RunCheck | undefined, repoRoot: string): ClearDecision {
function clearByRuns(file: PregateFile, lane: string, refs: string[], check: RunCheck | undefined, repoRoot: string, flaky?: FlakyInput & { cases: string[] }): ClearDecision {
if (!check) return { refused: 'usage', message: `--run needs the base branch's run_profiles; none could be read` };
const isGate = lane === REMOTE_GATE_LANE;
const names = isGate ? check.gateRuns?.profiles ?? [] : check.profiles[lane] ? [lane] : [];
@@ -404,13 +419,17 @@ function clearByRuns(file: PregateFile, lane: string, refs: string[], check: Run
}
return null;
};
const evidence = assign(0, new Set());
const red = flaky ? flakyRuns(lane, check, names, refs, file.head) : null;
if (red && 'refused' in red) return red;
const evidence = red ? red.evidence : assign(0, new Set());
if (!evidence) {
const failed = names.map(name => `${name}: ${refs.map(ref => { const v = verdict(name, ref); return v.ok ? `${ref} ok` : `${ref} reason=${v.reason} ${v.detail}`; }).join('; ')}`);
return { refused: 'PREGATE_RECEIPT_INVALID', message: `REUSE: refused reason=no_verified_run — no run per profile verifies (${failed.join(' | ')}); ${lane} stays uncleared` };
}
const trees = [...new Set(evidence.map(e => e.tree))];
if (trees.length > 1) return { refused: 'PREGATE_RECEIPT_INVALID', message: `REUSE: refused reason=tree_mismatch — the runs tested different trees (${trees.map(t => t.slice(0, 12)).join(', ')}); ${lane} stays uncleared` };
const off = red && evidence.find(e => e.head_sha !== file.head || e.tree !== file.tree);
if (off) return { refused: 'PREGATE_RECEIPT_INVALID', message: `FLAKY_EXCEPTION: refused reason=head_mismatch — run ${off.run_id} attempt ${off.run_attempt} tested head ${off.head_sha.slice(0, 12)} tree ${off.tree.slice(0, 12)}, not pregate.json's head ${(file.head ?? '').slice(0, 12)} tree ${file.tree.slice(0, 12)}; an exception binds the exact head and tree, never a stamp-only predecessor; ${lane} stays uncleared` };
const sub = treeSubstitution(file, trees[0]!, lane, repoRoot);
if ('refused' in sub) return { ...sub, message: `REUSE: refused reason=tree_not_stamp_only — ${sub.message}` };
const idle = evidence.filter(e => (e.tests ?? e.files.length) === 0);
@@ -433,24 +452,29 @@ function clearByRuns(file: PregateFile, lane: string, refs: string[], check: Run
}
const missing = uncoveredFiles([...required], evidence);
if (missing.length) return { refused: 'PREGATE_RECEIPT_INVALID', message: `REUSE: refused reason=${isGate ? 'inventory_uncovered' : 'tests_uncovered'} — ${missing.length} of the ${required.size} test file(s) ${lane} must cover appear in no run's tree.json (${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ', …' : ''}); ${lane} stays uncleared` };
const granted = red ? flakyDecision(file, lane, check, red, flaky!, repoRoot) : null;
if (granted && 'refused' in granted) return granted;
for (const e of evidence) {
let changed: string | null;
try { changed = runChanged(check.deps, e.run_id, e.run_attempt); }
try { changed = red?.red.some(r => r.evidence === e) ? redRunChanged(check.deps, e.run_id, e.run_attempt) : runChanged(check.deps, e.run_id, e.run_attempt); }
catch (err: any) { changed = `reading run ${e.run_id} again failed: ${String(err?.message ?? err).slice(0, 200)}`; }
if (changed) return { refused: 'PREGATE_RECEIPT_INVALID', message: `REUSE: refused reason=run_changed — ${changed}; ${lane} stays uncleared` };
}
const tests = evidence.reduce((n, e) => n + (e.tests ?? e.files.length), 0);
const accepted = sub.substitution ? ` accepted-for=${file.tree.slice(0, 12)} stamp-only=${sub.substitution.files.length}` : '';
return { receipt: `${isGate ? 'remote-gate' : 'run'} tree=${trees[0]!.slice(0, 12)} tests=${tests}${skippedCount ? ` skipped=${skippedCount}` : ''}${accepted} ${runReceiptFields(evidence, check.now)}`, attested: false, substitution: sub.substitution };
const exception = granted?.exception;
return { receipt: `${isGate ? 'remote-gate' : 'run'} tree=${trees[0]!.slice(0, 12)} tests=${tests}${skippedCount ? ` skipped=${skippedCount}` : ''}${exception ? ` exception=${exception.grant} cases=${exception.cases.length}` : ''}${accepted} ${runReceiptFields(evidence, check.now)}`, attested: false, substitution: sub.substitution, ...(exception ? { exception } : {}) };
}
/** Record the receipt that clears one obligation (a run URL, an evidence-bundle lane label, or a remote gate report, with the stamp-only substitution when one was accepted). */
export function clearObligation(file: PregateFile, lane: string, receipt: string, by: string, substitution?: PregateReceiptSubstitution): PregateFile {
export function clearObligation(file: PregateFile, lane: string, receipt: string, by: string, substitution?: PregateReceiptSubstitution, exception?: PregateException): PregateFile {
const list = file.requires_remote ?? [];
const target = list.find(r => r.lane === lane);
if (!target) throw new Error(`no requires-remote obligation named ${lane}; obligations: ${list.map(r => r.lane).join(', ') || '(none)'}`);
target.receipt = receipt; target.cleared_by = by;
if (substitution) target.substitution = substitution; else delete target.substitution;
const exceptions = [...(file.exceptions ?? []).filter(e => e.lane !== lane), ...(exception ? [exception] : [])];
if (exceptions.length) file.exceptions = exceptions; else delete file.exceptions;
file.verdict = verdictOf(file);
return file;
}
+2 -2
View File
@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import { ghRunDeps, runInventory, type RunProfile } from '../run-evidence';
import { ghArtifactDeps, ghRunDeps, runInventory, type RunProfile } from '../run-evidence';
import { wtreeFingerprint } from '../script-invocation';
import { resolveBaseBranch } from '../ship-policy';
import { normalizeRemoteUrl } from '../ship-queue-train-record';
@@ -69,7 +69,7 @@ export function buildRunCheck(root: string, lane: string | null, allowRepoComman
const repo = /^https:\/\/github\.com\/(.+)$/.exec(normalizeRemoteUrl(origin.status === 0 ? origin.stdout.trim() : ''))?.[1];
if (!repo) return { error: 'origin is not a github.com repository; run evidence is read from GitHub Actions', profiled: lane === null ? false : lane === REMOTE_GATE_LANE ? !!loaded.config.remote_gate_runs : !!loaded.config.run_profiles[lane] };
return {
repo, deps: ghRunDeps(repo, root), profiles: loaded.config.run_profiles, gateRuns: loaded.config.remote_gate_runs, now: new Date(),
repo, deps: ghRunDeps(repo, root), failures: ghArtifactDeps(repo), profiles: loaded.config.run_profiles, gateRuns: loaded.config.remote_gate_runs, now: new Date(),
unchanged: p => gateInputsChanged(root, base, p),
inventory: (command, tree, selected) => {
if (!allowRepoCommands) return { error: 'the inventory command is a pin-file command; pass --allow-repo-commands' };
+1 -1
View File
@@ -313,7 +313,7 @@ export function branchAddedLines(cwd: string, since: string, files: string[], to
return out;
}
const escapeRegExp = (t: string) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
export const escapeRegExp = (t: string) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
const VERSION_RE = '(?<v>\\d+(?:\\.\\d+){1,3})(?![0-9.])';
/**
* The built-in stamp forms as scanners, the version in the `v` group: `(was X)`, `since: X` and `vX`.
+12 -5
View File
@@ -10,6 +10,7 @@
import { spawnSync } from 'node:child_process';
import * as fs from 'node:fs';
import * as path from 'node:path';
import { resolveBase, type ResolvedBase } from './gate-diff/git';
import { GENERATED_PATH, parseRegistry } from './regen';
import { RESULT_CODES } from './result-codes';
import { classifyPath, dataCandidate, svgCandidate, svgDrawing, type ClassInput, type DepthError, type PathLines, type RegistryInfo } from './review-depth';
@@ -31,6 +32,8 @@ export interface Collected extends ClassInput {
untracked: string[];
consumed: string[] | 'all';
drawings: string[];
/** collectLive only: the ref resolveBase read for the base name (GST-1036), null when nothing resolved. */
base?: ResolvedBase | null;
}
function git(root: string, args: string[]): { ok: boolean; status: number | null; out: string; err: string } {
@@ -255,16 +258,20 @@ export function collectCommit(root: string, baseSha: string, headSha: string): C
return result(diff, { root: skillDirs, registry, errors, mergeBase, untracked: [], consumed, drawings });
}
/** The working tree against the merge base with origin/<base> (or <base>; a remote-qualified base reads refs/remotes/<base> only), untracked files counted per path; the registry is the base ref's commit. */
/**
* The working tree against the merge base with the base resolveBase reads (lib/gate-diff/git.ts: a bare name is
* origin/<base> when it shares history with HEAD, else the local branch; a remote-qualified base reads
* refs/remotes/<base> only), untracked files counted per path; the registry is the base ref's commit.
*/
export function collectLive(root: string, base: string): Collected {
const errors: DepthError[] = [];
const qualified = base.startsWith('origin/') || git(root, ['remote']).out.split('\n').some(r => r && base.startsWith(`${r}/`));
const ref = (qualified ? [`refs/remotes/${base}`] : [`refs/remotes/origin/${base}`, `refs/heads/${base}`]).find(r => git(root, ['rev-parse', '--verify', '-q', `${r}^{commit}`]).ok) ?? base;
const resolved = resolveBase(base, root, 'HEAD');
const ref = resolved?.sha ?? base;
const registry = loadRegistryAt(root, ref);
const mb = git(root, ['merge-base', ref, 'HEAD']);
if (!mb.ok) {
errors.push({ code: 'numstat_failed', detail: oneLine(mb.err || `no merge base with ${ref}`), input: `git merge-base ${ref} HEAD`, repair: `fetch the base first (git fetch origin ${base})` });
return result({ perPath: [], deleted: [], stampOnly: [], created: [], added: {}, removed: {} }, { root, registry, errors, mergeBase: null, untracked: [], consumed: 'all' });
return { ...result({ perPath: [], deleted: [], stampOnly: [], created: [], added: {}, removed: {} }, { root, registry, errors, mergeBase: null, untracked: [], consumed: 'all' }), base: resolved };
}
const mergeBase = mb.out.trim();
const diff = readDiff(root, [mergeBase], errors);
@@ -284,5 +291,5 @@ export function collectLive(root: string, base: string): Collected {
const drawings = drawingsAmong(diff.perPath, root, p => {
try { return fs.statSync(path.join(root, p)).size <= DRAWING_READ_CAP ? fs.readFileSync(path.join(root, p)) : null; } catch { return null; }
});
return result(diff, { root, registry, errors, mergeBase, untracked, consumed, drawings });
return { ...result(diff, { root, registry, errors, mergeBase, untracked, consumed, drawings }), base: resolved };
}
+32 -21
View File
@@ -93,7 +93,16 @@ const SVG_MARKUP = /^<(?:!--|!\[CDATA\[|\?xml\s|!DOCTYPE\s+svg(?:\s+PUBLIC\s+(["
export const SVG_REFUSED = [/&(?!(?:amp|lt|gt|quot|apos);)/, /\\/, /@import/i, /url\((?!\s*#|['"]\s*#)/i, /expression\s*\(/i, /-moz-binding|\bbehavior\s*:/i];
/** A drawing's CSS, a style element's text or a style attribute's value, holds declarations only: no @ rule and no function but url(#id). */
const SVG_STYLE_OPEN = /<(?:[A-Za-z_][\w.-]*:)?style\b/gi;
const SVG_STYLE_CLOSE = /^<\/(?:[A-Za-z_][\w.-]*:)?style\s*>/i;
const SVG_STYLE_CLOSE = /^<\/(?:[A-Za-z_][\w.-]*:)?style[ \t\n\r]*>/i;
/**
* A style element's opening tag, read as quoted name="value" pairs separated by the ASCII whitespace XML and HTML share: any
* other shape (a value holding < or >, an unquoted or valueless attribute, />, another space) refuses, so it cannot hide a closing tag.
*/
const SVG_STYLE_TAG = /^<(?:[A-Za-z_][\w.-]*:)?style(?:[ \t\n\r]+[\w.:-]+[ \t\n\r]*=[ \t\n\r]*(?:"[^"<>]*"|'[^'<>]*'))*[ \t\n\r]*>/i;
/** An element name, ended by ASCII whitespace, / or >: a non-ASCII character in the name (a prefix such as gé:) refuses rather than reading as its ASCII start. */
const SVG_TAG_NAME = /^<\/?(?:[A-Za-z_][\w.-]*:)?([A-Za-z_][\w.-]*)(?=[ \t\n\r/>]|$)/;
/** Every name= in the text, non-ASCII letters included so a prefix such as xé:href is read whole and refused. */
const SVG_ATTR = /(?<![\w.:\-\u0080-\uffff])([A-Za-z_\u0080-\uffff][\w.:\-\u0080-\uffff]*)\s*=\s*(?=(?:"([^"]*)"|'([^']*)'|([^\s"'<>=]+)))/g;
const SVG_CSS_REF = /url\(\s*(['"]?)#[\w.:-]*\1\s*\)/gi;
const SVG_CSS_REFUSED = /[@(]/;
/** An href or src value a drawing may hold: a same-document reference, or a raster image inline. */
@@ -102,10 +111,12 @@ const SVG_HREF = /^\s*(?:#|data:image\/(?:png|jpe?g|gif|webp);base64,[A-Za-z0-9+
/**
* Whether an SVG's whole text is a drawing (GST-911): every element in SVG_ELEMENTS, no event handler, every href or src a
* same-document reference or an inline raster image, CSS of declarations only, and nothing SVG_REFUSED names, read after character references are
* decoded. Every name= in the text is read, so a stray quote cannot hide a later attribute inside its value; an unquoted value
* stops at the next =, which keeps the scan linear. A style element's CSS is walked with indexOf to its closing tag, dropping
* comments and reading CDATA as CSS, so neither can hide a closing tag; any other markup inside it, or a style element that never
* closes, refuses. Anything else, an SVG that can run code included, stays code.
* decoded. Every name= in the text is read (SVG_ATTR), so a stray quote cannot hide a later attribute inside its value, and a name
* holding a non-ASCII character refuses, like an element name (SVG_TAG_NAME); an unquoted value
* stops at the next =, which keeps the scan linear. A style element's opening tag is read quote by quote (SVG_STYLE_TAG), and its CSS is walked with indexOf to its closing tag over the raw
* text, so a character reference cannot fake a closing tag or a comment, and any & in it refuses (GST-940). Comments and CDATA are
* read as CSS, so neither can hide a closing tag and an HTML-only comment end (<!--> or --!>) exposes nothing unread; any other
* markup inside it, or a style element that never closes, refuses. Anything else, an SVG that can run code included, stays code.
*/
export function svgDrawing(text: string): boolean {
const t = decodeCharRefs(text);
@@ -113,36 +124,36 @@ export function svgDrawing(text: string): boolean {
const cssDrawing = (css: string) => !SVG_CSS_REFUSED.test(css.replace(SVG_CSS_REF, ''));
for (let at = 0; ;) {
SVG_STYLE_OPEN.lastIndex = at;
const open = SVG_STYLE_OPEN.exec(t);
const open = SVG_STYLE_OPEN.exec(text);
if (!open) break;
let i = t.indexOf('>', open.index) + 1;
if (!i) return false;
const tag = SVG_STYLE_TAG.exec(text.slice(open.index, open.index + 4096));
if (!tag) return false;
let i = open.index + tag[0].length;
let css = '';
for (;;) {
const lt = t.indexOf('<', i);
const lt = text.indexOf('<', i);
if (lt === -1) return false;
css += t.slice(i, lt);
if (t.startsWith('<!--', lt)) {
i = t.indexOf('-->', lt + 4) + 3;
if (i === 2) return false;
} else if (t.startsWith('<![CDATA[', lt)) {
const end = t.indexOf(']]>', lt + 9);
css += text.slice(i, lt);
const [start, close] = text.startsWith('<!--', lt) ? [lt + 4, '-->'] : text.startsWith('<![CDATA[', lt) ? [lt + 9, ']]>'] : [-1, ''];
if (start !== -1) {
const end = text.indexOf(close, start);
if (end === -1) return false;
css += t.slice(lt + 9, end);
css += ' ' + text.slice(start, end) + ' ';
i = end + 3;
} else if (SVG_STYLE_CLOSE.test(t.slice(lt, lt + 256))) {
} else if (SVG_STYLE_CLOSE.test(text.slice(lt, lt + 256))) {
at = lt + 1;
break;
} else return false;
}
if (!cssDrawing(css)) return false;
if (css.includes('&') || !cssDrawing(css)) return false;
}
for (let at = t.indexOf('<'); at !== -1; at = t.indexOf('<', at + 1)) {
if (SVG_MARKUP.test(t.slice(at, at + 512))) continue;
const tag = /^<\/?(?:[A-Za-z_][\w.-]*:)?([A-Za-z_][\w.-]*)/.exec(t.slice(at, at + 256));
const tag = SVG_TAG_NAME.exec(t.slice(at, at + 256));
if (!tag || !SVG_ELEMENTS.has(tag[1]!.toLowerCase())) return false;
}
for (const m of t.matchAll(/(?<![\w.:-])([A-Za-z_][\w.:-]*)\s*=\s*(?=(?:"([^"]*)"|'([^']*)'|([^\s"'<>=]+)))/g)) {
for (const m of t.matchAll(SVG_ATTR)) {
if (/[^\x00-\x7f]/.test(m[1]!)) return false;
const local = m[1]!.slice(m[1]!.lastIndexOf(':') + 1).toLowerCase();
const value = m[2] ?? m[3] ?? m[4] ?? '';
if (local.startsWith('on') || ((local === 'href' || local === 'src') && !SVG_HREF.test(value)) || (local === 'style' && !cssDrawing(value))) return false;
@@ -153,7 +164,7 @@ export function svgDrawing(text: string): boolean {
/** A hash of the constants and patterns that decide a depth, not of this file's bytes: a comment edit keeps it, a threshold edit changes it. */
export const DEPTH_RULES = createHash('sha256').update(JSON.stringify({
RISK_RULES, SMALL_DIFF_LINES, RED_TEAM_LINES, LARGE_DIFF_LINES, FULL_PASS_CAP, LIGHT_FIXED, BATCH_SCOPED, SCOPED_RANGE_LINES, ROLE_EFFORT, SVG_ELEMENTS: [...SVG_ELEMENTS],
patterns: Object.entries({ GATE_PATH, AGENT_PROSE, TEST_PATH, RELEASE_METADATA, DOC_PATH: [DOC_PATH], DATA_PATH: [DATA_PATH], DATA_CONFIG, SVG_MARKUP: [SVG_MARKUP], SVG_REFUSED, SVG_HREF: [SVG_HREF], SVG_STYLE_OPEN: [SVG_STYLE_OPEN], SVG_STYLE_CLOSE: [SVG_STYLE_CLOSE], SVG_CSS_REF: [SVG_CSS_REF], SVG_CSS_REFUSED: [SVG_CSS_REFUSED] }).map(([k, v]) => [k, v.map(r => `/${r.source}/${r.flags}`)]),
patterns: Object.entries({ GATE_PATH, AGENT_PROSE, TEST_PATH, RELEASE_METADATA, DOC_PATH: [DOC_PATH], DATA_PATH: [DATA_PATH], DATA_CONFIG, SVG_MARKUP: [SVG_MARKUP], SVG_REFUSED, SVG_HREF: [SVG_HREF], SVG_STYLE_OPEN: [SVG_STYLE_OPEN], SVG_STYLE_CLOSE: [SVG_STYLE_CLOSE], SVG_STYLE_TAG: [SVG_STYLE_TAG], SVG_TAG_NAME: [SVG_TAG_NAME], SVG_ATTR: [SVG_ATTR], SVG_CSS_REF: [SVG_CSS_REF], SVG_CSS_REFUSED: [SVG_CSS_REFUSED] }).map(([k, v]) => [k, v.map(r => `/${r.source}/${r.flags}`)]),
})).digest('hex').slice(0, 16);
/**
+3
View File
@@ -272,6 +272,9 @@ export function bindReview(rec: Record<string, any>, token: string, env = proces
if (env.GSTACK_STAMP_TREE) rec.tree = env.GSTACK_STAMP_TREE;
if (env.GSTACK_STAMP_DIRTY) rec.dirty = env.GSTACK_STAMP_DIRTY === 'true';
stampGateFindings(rec.findings, env.GSTACK_STAMP_SESSION_KIND);
if (rec.skill === 'review-fix-check' && (typeof rec.completed !== 'boolean' || typeof rec.converged !== 'boolean')) {
throw new Error('review-log: a review-fix-check row must carry completed and converged as true or false (review-army item 6 fields; without them gstack-review-read marks the row UNVERIFIED and finish cannot count it)');
}
// A /ship pass whose findings were all fixed, or deferred or noted below the floor, left no open defect (review-army
// item 6), so a claimed issues_found is recorded clean with zero counts and Step 11.5 can bind it (GST-430). Only the
// logger-stamped action counts (never a caller's status), and the findings must account for every claimed issue.
+67 -14
View File
@@ -122,20 +122,38 @@ function select(i: ExcludeInput, patterns: readonly string[]): { byPattern: Map<
return { byPattern, files };
}
/** Executable image magic: ELF, Mach-O (thin, universal and 64-bit universal; 0xcafebabe is also a Java class), PE, WebAssembly and a script's #!. */
const NATIVE_MAGIC = [[0x7f, 0x45, 0x4c, 0x46], [0xfe, 0xed, 0xfa, 0xce], [0xfe, 0xed, 0xfa, 0xcf], [0xce, 0xfa, 0xed, 0xfe], [0xcf, 0xfa, 0xed, 0xfe], [0xca, 0xfe, 0xba, 0xbe], [0xca, 0xfe, 0xba, 0xbf], [0x4d, 0x5a], [0x00, 0x61, 0x73, 0x6d], [0x23, 0x21]];
/**
* The matched paths git calls binary whose bytes hold a NUL in their first 8,000 (git's own test), read from the head blob,
* the file on a live tree, or the old blob for a deletion. A branch's .gitattributes can make git call a text file binary;
* only real bytes make it binary content here.
* The matched paths git calls binary by their bytes alone: `git diff --numstat` with attributes read from the empty tree, so
* a branch's .gitattributes (`diff`, `-binary`, `text`) cannot make an executable image read as text and skip the
* magic check. null when git cannot run it (a git without --attr-source); the caller then reads every matched file's bytes.
*/
function binaryContent(i: ExcludeInput, files: ReadonlyMap<string, Matched>, claimed: ReadonlySet<string>, unread: Set<string>): Set<string> {
function bytesBinary(i: ExcludeInput, patterns: readonly string[]): string[] | null {
const empty = git(i.root, ['hash-object', '-t', 'tree', '--stdin'], '');
if (!empty.ok) return null;
const range = i.head ? [i.mergeBase, i.head] : [i.mergeBase];
const r = git(i.root, [`--attr-source=${empty.out.trim()}`, 'diff', '--numstat', '-z', '--no-renames', ...range, '--', ...patterns.map(p => `:(top,glob)${p}`)]);
return r.ok ? r.out.split('\0').filter(l => l.startsWith('-\t-\t')).map(l => l.slice(4)) : null;
}
const nativeImage = (b: Buffer) => NATIVE_MAGIC.some(m => m.every((x, k) => b[k] === x));
/**
* The claimed paths (git calls them binary under the branch's attributes or under none: bytesBinary) whose bytes hold a NUL
* in their first 8,000 (git's own test), read from the head blob, the file on a live tree, or the old blob for a deletion.
* A branch's .gitattributes can make git call a text file binary; only real bytes make it binary content here. A binary file that starts with executable image magic also goes in `native`.
*/
function binaryContent(i: ExcludeInput, files: ReadonlyMap<string, Matched>, claimed: ReadonlySet<string>, unread: Set<string>, native: Set<string>): Set<string> {
const out = new Set<string>();
const sniff = (p: string, b: Buffer) => { if (!b.includes(0)) return; out.add(p); if (nativeImage(b)) native.add(p); };
const real = (sha: string) => /^[0-9a-f]{40,64}$/.test(sha) && !/^0+$/.test(sha);
const bySha = new Map<string, string[]>();
for (const p of claimed) {
const m = files.get(p);
if (!m) continue;
if (!i.head && m.newMode !== '000000') {
try { const fd = fs.openSync(path.join(i.root, p), 'r'); const buf = Buffer.alloc(8000); const n = fs.readSync(fd, buf, 0, 8000, 0); fs.closeSync(fd); if (buf.subarray(0, n).includes(0)) out.add(p); } catch { unread.add(p); }
try { const fd = fs.openSync(path.join(i.root, p), 'r'); const buf = Buffer.alloc(8000); const n = fs.readSync(fd, buf, 0, 8000, 0); fs.closeSync(fd); sniff(p, buf.subarray(0, n)); } catch { unread.add(p); }
continue;
}
const sha = real(m.newSha) ? m.newSha : real(m.oldSha) ? m.oldSha : '';
@@ -144,8 +162,36 @@ function binaryContent(i: ExcludeInput, files: ReadonlyMap<string, Matched>, cla
for (const [sha, paths] of bySha) {
const r = spawnSync('git', ['cat-file', 'blob', sha], { cwd: i.root, timeout: 30_000, maxBuffer: 8000 });
const read = r.status === 0 || (r.error as NodeJS.ErrnoException | undefined)?.code === 'ENOBUFS';
const binary = read && (r.stdout ?? Buffer.alloc(0)).subarray(0, 8000).includes(0);
for (const p of paths) if (!read) unread.add(p); else if (binary) out.add(p);
const head = (r.stdout ?? Buffer.alloc(0)).subarray(0, 8000);
for (const p of paths) if (!read) unread.add(p); else sniff(p, head);
}
return out;
}
/**
* The added lines of matched files git calls binary only because of their attributes (the bytes hold no NUL): the
* collector's added lines are empty for them, so the secret-line rule reads `git diff --text` instead, which no
* .gitattributes, textconv or external diff driver changes. One git diff per KEEP_ARG_MAX_BYTES of literal pathspecs;
* git prints one section per path in byte order, so a chunk whose sections do not line up with its sorted paths, or a
* git failure, puts every path of that chunk in `unread`.
*/
function attributeBinaryLines(i: ExcludeInput, paths: readonly string[], unread: Set<string>): Record<string, string[]> {
const out: Record<string, string[]> = {};
const range = i.head ? [i.mergeBase, i.head] : [i.mergeBase];
const chunks: string[][] = [];
let bytes = Infinity;
for (const p of [...paths].sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)))) {
const n = argBytes([p]);
if (bytes + n > KEEP_ARG_MAX_BYTES) { chunks.push([]); bytes = 0; }
chunks[chunks.length - 1]!.push(p);
bytes += n;
}
for (const chunk of chunks) {
const r = git(i.root, ['diff', '--text', '--no-textconv', '--no-ext-diff', '--no-renames', '--src-prefix=a/', '--dst-prefix=b/', '-U0', ...range, '--', ...chunk.map(literal)]);
const sections = r.ok ? r.out.split(/^(?=diff --git )/m).filter(s => s.startsWith('diff --git ')) : [];
const aligned = sections.length === chunk.length && chunk.every((p, k) => /["\\\x00-\x1f\x7f]/.test(p) || sections[k]!.startsWith(`diff --git a/${p} b/${p}\n`));
if (!aligned) { for (const p of chunk) unread.add(p); continue; }
chunk.forEach((p, k) => { let hunk = false; out[p] = sections[k]!.split('\n').filter(l => (hunk ||= l.startsWith('@@')) && l.startsWith('+')).map(l => l.slice(1)); });
}
return out;
}
@@ -159,17 +205,21 @@ function contentKind(i: ExcludeInput, p: string, binary: ReadonlySet<string>): C
return classifyPath(p, i.classRoot) === 'docs' ? 'docs' : null;
}
/** Source and script extensions: a NUL in one does not make it excludable binary content. */
const CODE_EXT = /\.(?:[cm]?[jt]sx?|py|rb|go|rs|java|kts?|scala|swift|exs?|php|cs|c|h|cc|cpp|hpp|mm?|dart|pl|pm|lua|sh|bash|zsh|fish|ps1|bat|cmd|vue|svelte|html?|wasm)$/i;
/**
* The only extensions a binary file may be excludable content under: images, fonts, media, documents, compressed archives
* and data blobs. Any other binary (source with a NUL, a native library or executable, a key store, a pickle, no
* extension) is code; so is one that starts with executable image magic whatever its extension.
*/
const BINARY_CONTENT_EXT = /\.(?:png|jpe?g|gif|webp|bmp|ico|avif|tiff?|heic|heif|woff2?|ttf|otf|eot|mp3|mp4|m4a|wav|ogg|oga|ogv|webm|mov|avi|mkv|flac|aac|opus|pdf|docx|xlsx|pptx|odt|ods|odp|gz|tgz|zip|tar|bz2|xz|zst|7z|bin|dat|parquet|arrow|feather|avro|orc|npy|npz|h5|hdf5|sqlite3?|db|safetensors)$/i;
/** Why a matched file is kept by its path, mode and lines alone; null for content the policy may exclude. A binary file readers would only see as "Binary files differ" is content unless its directory, mode or gate tags keep it. */
function pathReason(i: ExcludeInput, p: string, m: Matched, binary: ReadonlySet<string>): KeptReason | null {
/** Why a matched file is kept by its path, mode and lines alone; null for content the policy may exclude. A binary file readers would only see as "Binary files differ" is content unless its directory, mode, gate tags, extension or magic keep it. */
function pathReason(i: ExcludeInput, p: string, m: Matched, binary: ReadonlySet<string>, native: ReadonlySet<string>): KeptReason | null {
if (/^\.(gstack|github)\//.test(p)) return 'policy-dir';
if (isGatePath(p)) return 'gate-path';
if (m.oldMode === '100755' || m.newMode === '100755') return 'executable';
if ([m.oldMode, m.newMode].some(x => x === '120000' || x === '160000')) return 'link';
if (i.gateTagged?.has(p)) return 'gate-tagged';
if (binary.has(p)) return CODE_EXT.test(p) ? 'code' : null;
if (binary.has(p)) return BINARY_CONTENT_EXT.test(p) && !native.has(p) ? null : 'code';
if (isAgentProse(p)) return 'agent-prose';
if (isDataConfig(p)) return 'config';
if (contentKind(i, p, binary) === null) return 'code';
@@ -227,9 +277,12 @@ export function reviewExclude(i: ExcludeInput): Exclusion {
const sel = select(i, patterns);
if ('error' in sel) return { state: 'refused', code: 'REVIEW_DIFF_UNREADABLE', lines: [`${i.context}: git could not list the files review_exclude_paths matches (${sel.error}); fix: git fetch origin ${base}, then rerun once; nothing was planned (REVIEW_DIFF_UNREADABLE)`] };
const unread = new Set<string>();
const binary = binaryContent(i, sel.files, new Set(i.perPath.filter(e => e.binary && sel.files.has(e.path)).map(e => e.path)), unread);
const native = new Set<string>();
const claimed = i.perPath.filter(e => e.binary && sel.files.has(e.path)).map(e => e.path);
const binary = binaryContent(i, sel.files, new Set([...claimed, ...(bytesBinary(i, patterns) ?? sel.files.keys())]), unread, native);
const text = { ...i, added: { ...i.added, ...attributeBinaryLines(i, claimed.filter(p => !binary.has(p) && !unread.has(p)), unread) } };
const reasons = new Map<string, KeptReason | null>();
for (const [p, m] of sel.files) reasons.set(p, unread.has(p) ? 'consumer-scan-unavailable' : pathReason(i, p, m, binary));
for (const [p, m] of sel.files) reasons.set(p, unread.has(p) ? 'consumer-scan-unavailable' : pathReason(text, p, m, binary, native));
const candidates = new Set([...reasons].filter(([, r]) => r === null).map(([p]) => p));
const named = grepFixed(i, [...candidates].filter(p => !p.includes('\n')), candidates, [i.mergeBase]);
for (const p of candidates) {
+43
View File
@@ -56,6 +56,13 @@ export interface ApiRun {
export interface ApiJob { name: string; conclusion: string | null; completed_at?: string | null }
export interface TreeRecord { run_id?: unknown; run_attempt?: unknown; event?: unknown; sha?: unknown; head_sha?: unknown; tree?: unknown; reused?: unknown; reuse?: unknown; os?: unknown; files?: unknown; tests?: unknown; skipped_files?: unknown }
/** What a red run's reader needs beyond RunDeps (lib/pregate/flaky-exception.ts): every file of one artifact, and a pull request's head. */
export interface RunArtifactDeps {
/** Every file of the run's one unexpired artifact `name`, path → text; throws when it is missing, ambiguous or too large. */
artifactFiles(id: number, name: string): Record<string, string>;
pull(n: number): { head_sha: string; state: string; head_repo: string | null };
}
/** Everything verifyRun reads, injectable so every refusal has a fixture. */
export interface RunDeps {
run(id: number): ApiRun;
@@ -80,6 +87,8 @@ const WORKFLOW_FILE = /^[A-Za-z0-9_.-]+\.ya?ml$/;
const NAME = /^[A-Za-z0-9_.\/-]{1,128}$/;
export const DEFAULT_MAX_AGE_HOURS = 24;
const MAX_ARTIFACT_BYTES = 8 * 1024 * 1024;
/** Shard logs are the whole test stream, so a red run's reader allows more than a tree.json. */
const MAX_LOG_ARTIFACT_BYTES = 64 * 1024 * 1024;
/** A numeric run id, or a run URL on this repository (`…/actions/runs/<id>[/attempts/<n>][/job/<j>]`). */
export function parseRunRef(ref: string, repo: string): number | null {
@@ -334,3 +343,37 @@ export function ghRunDeps(repo: string, repoRoot: string): RunDeps {
},
};
}
/** The gh-backed artifact and pull request reads for `repo` (lib/pregate/flaky-exception.ts): one unexpired artifact by name, every regular file in it under a byte cap. */
export function ghArtifactDeps(repo: string): RunArtifactDeps {
const all = <T>(p: string, key: string): T[] => gh(['api', '--paginate', p, '--jq', `.${key}[]`]).split('\n').filter(Boolean).map(l => JSON.parse(l) as T);
return {
artifactFiles: (id, name) => {
const listed = all<{ name: string; size_in_bytes: number; expired: boolean }>(`repos/${repo}/actions/runs/${id}/artifacts?name=${encodeURIComponent(name)}&per_page=100`, 'artifacts').filter(a => a.name === name && !a.expired);
if (listed.length !== 1) throw new Error(`run ${id} has ${listed.length} unexpired artifacts named ${name}`);
if (!(listed[0]!.size_in_bytes <= MAX_LOG_ARTIFACT_BYTES)) throw new Error(`artifact ${name} is ${listed[0]!.size_in_bytes} bytes, over ${MAX_LOG_ARTIFACT_BYTES}`);
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-run-evidence-'));
try {
gh(['run', 'download', String(id), '--repo', repo, '--name', name, '--dir', dir], 300_000);
const out: Record<string, string> = {};
let bytes = 0;
const walk = (rel: string) => {
for (const entry of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
const child = rel ? `${rel}/${entry.name}` : entry.name;
if (entry.isDirectory()) { walk(child); continue; }
if (!entry.isFile()) continue;
bytes += fs.statSync(path.join(dir, child)).size;
if (bytes > MAX_LOG_ARTIFACT_BYTES) throw new Error(`artifact ${name} unpacks to more than ${MAX_LOG_ARTIFACT_BYTES} bytes`);
out[child] = fs.readFileSync(path.join(dir, child), 'utf8');
}
};
walk('');
return out;
} finally { fs.rmSync(dir, { recursive: true, force: true }); }
},
pull: n => {
const p = JSON.parse(gh(['api', `repos/${repo}/pulls/${n}`])) as { state: string; head: { sha: string; repo: { full_name: string } | null } };
return { head_sha: p.head.sha, state: p.state, head_repo: p.head.repo?.full_name ?? null };
},
};
}
+6 -3
View File
@@ -114,7 +114,8 @@ export function releasePaths(policy: Record<string, any> | null, cwd: string, re
* added since the merge base with origin/<base>, and not added by the base since): after a lost slot and a merge of the
* base its stale stamp is older than `ref`'s VERSION, so it must be at or newer than the fork point's version instead,
* the bound gstack-restamp's stamp_paths stage uses (GST-895; the fork version itself since GST-963). A branch line is
* named by its position, and with a kept VERSION only such a line may move (GST-979, GST-980).
* named by its position, and with a kept VERSION only such a line may move (GST-979, GST-980); on it a declared
* `stamp_placeholders` value may also become the new version inside a `stamp_patterns` template (GST-1026).
*/
export function stampedFiles(policy: Record<string, any> | null, cwd: string, ref: string, base: string): string[] {
const globs = Array.isArray(policy?.stamp_files) ? policy.stamp_files.filter((s: unknown): s is string => typeof s === 'string') : [];
@@ -124,11 +125,13 @@ export function stampedFiles(policy: Record<string, any> | null, cwd: string, re
let after = '';
try { after = extractVersion(fs.readFileSync(path.join(cwd, before.rel), 'utf8'), before.rel); } catch { return []; }
if (!after) return [];
const templates = Array.isArray(policy?.stamp_patterns) ? policy.stamp_patterns.filter((s: unknown): s is string => typeof s === 'string') : [];
const strings = (v: unknown): string[] => (Array.isArray(v) ? v.filter((s): s is string => typeof s === 'string') : []);
const templates = strings(policy?.stamp_patterns);
const placeholders = strings(policy?.stamp_placeholders);
const diff = git(cwd, ['diff', '--unified=0', '--no-color', '--no-ext-diff', '--no-textconv', '--no-renames', ref]);
if (diff.status !== 0) return [];
const side = branchSides(cwd, `origin/${base}`, 'HEAD', before.version, ref);
const stamp = (rel: string, removed: string, added: string, at: number): boolean => stampOnlyLine(removed, added, before.version, after, templates, side(rel), at);
const stamp = (rel: string, removed: string, added: string, at: number): boolean => stampOnlyLine(removed, added, before.version, after, templates, side(rel), at, placeholders);
return parseUnifiedDiff(diff.stdout).filter(f => f.status === 'M' && !f.binary && !f.modeChanged && matchesAny(globs, f.path) && f.hunks.length > 0 &&
f.hunks.every(h => h.removed.length === h.added.length && h.removed.every((line, i) => stamp(f.path, line, h.added[i]!, h.removedAt[i]!)))).map(f => f.path);
}
+35
View File
@@ -0,0 +1,35 @@
/**
* Validation of the stamp policy keys (stamp_patterns templates and stamp_placeholders), split out of ship-policy.ts
* to keep that module under the module-size ratchet.
*/
import type { PolicyError } from './ship-policy';
import { parseVersion } from './version-source';
const MAX_TEMPLATES = 16;
const MAX_TEMPLATE = 128;
const MAX_PLACEHOLDERS = 16;
const MAX_PLACEHOLDER = 32;
export const VERSION_SLOT = '{version}';
export function templateErrors(value: unknown, out: PolicyError[]): void {
if (!Array.isArray(value)) { out.push({ code: 'POLICY_INVALID', path: 'stamp_patterns', message: 'must be an array of literal templates' }); return; }
if (value.length > MAX_TEMPLATES) out.push({ code: 'POLICY_CONTAINMENT', path: 'stamp_patterns', message: `more than ${MAX_TEMPLATES} templates` });
value.forEach((t, i) => {
const at = `stamp_patterns[${i}]`;
if (typeof t !== 'string') { out.push({ code: 'POLICY_INVALID', path: at, message: 'must be a string' }); return; }
if (t.split(VERSION_SLOT).length !== 2) out.push({ code: 'POLICY_INVALID', path: at, message: `${JSON.stringify(t)} must contain exactly one ${VERSION_SLOT}` });
else if (t.length > MAX_TEMPLATE || /[\0\r\n]/.test(t)) out.push({ code: 'POLICY_CONTAINMENT', path: at, message: `must be one line of at most ${MAX_TEMPLATE} characters` });
});
}
export function placeholderErrors(value: unknown, out: PolicyError[]): void {
if (!Array.isArray(value)) { out.push({ code: 'POLICY_INVALID', path: 'stamp_placeholders', message: 'must be an array of literal placeholders' }); return; }
if (value.length > MAX_PLACEHOLDERS) out.push({ code: 'POLICY_CONTAINMENT', path: 'stamp_placeholders', message: `more than ${MAX_PLACEHOLDERS} placeholders` });
value.forEach((p, i) => {
const at = `stamp_placeholders[${i}]`;
if (typeof p !== 'string') { out.push({ code: 'POLICY_INVALID', path: at, message: 'must be a string' }); return; }
if (!p.trim() || p.length > MAX_PLACEHOLDER || /[\0\r\n]/.test(p)) out.push({ code: 'POLICY_CONTAINMENT', path: at, message: `must be one non-empty line of at most ${MAX_PLACEHOLDER} characters` });
else if (p.includes(VERSION_SLOT)) out.push({ code: 'POLICY_INVALID', path: at, message: `${JSON.stringify(p)} must not contain ${VERSION_SLOT}` });
else if (parseVersion(p)) out.push({ code: 'POLICY_INVALID', path: at, message: `${JSON.stringify(p)} is a version, not a placeholder` });
});
}
+9 -14
View File
@@ -18,6 +18,8 @@ import * as path from 'node:path';
import { defaultBaseBranch, noDefaultBaseLine } from './default-base';
import { RESULT_CODES, type ResultCodeName } from './result-codes';
import { cmpVersion, parseVersion } from './version-source';
import { placeholderErrors, templateErrors } from './ship-policy-stamps';
export { VERSION_SLOT } from './ship-policy-stamps';
export const SHIP_POLICY_PATH = '.gstack/ship-policy.json';
export const SHIP_POLICY_SCHEMA = 'https://github.com/garrytan/gstack/docs/ship-policy.md#schema-v1';
@@ -64,6 +66,8 @@ export interface ShipPolicy {
stamp_files: string[];
/** Literal stamp templates with one `{version}` slot, beside the built-in `(was X)`, `since: X`, `vX`; writer and classifier share them. */
stamp_patterns: string[];
/** Placeholders (`TBD`) a restamp may replace with the new version inside a `stamp_patterns` template, on the branch's own lines only. */
stamp_placeholders: string[];
/** The repo's own restamp, run first in the staging worktree with the target version; gstack's version writer is skipped. */
restamp_command: string | null;
/** Migration numbering: `{ dir, id }` where `id` is a regex with one capture group over the file name. */
@@ -161,6 +165,7 @@ export const DEFAULT_POLICY: ShipPolicy = {
maintainers: [],
stamp_files: [],
stamp_patterns: [],
stamp_placeholders: [],
restamp_command: null,
migrations: null,
gate_command: null,
@@ -193,6 +198,7 @@ export const POLICY_EXPLANATIONS: Record<PolicyKey, string> = {
maintainers: 'GitHub logins treated as maintainers by /review contributor mode; empty uses repository push permission.',
stamp_files: 'The repo’s stamp rule: globs of the only files that may differ by a stamp (version file, manifests, plugin trees, the PR’s own since: rows). Empty keeps gstack’s per-file rules; set, it applies before every rule.',
stamp_patterns: 'Literal templates with exactly one {version} slot (at most 16, 128 characters each), for example `"version": "{version}"` or `since: \'{version}\'`; the restamp writer and the tree receipt use them beside (was X), since: X and vX.',
stamp_placeholders: 'Literal placeholders (at most 16, one line, 32 characters each, never `{version}` or a version), for example `["TBD"]`: a line the branch added that reads a placeholder in a stamp_patterns template (`since: \'TBD\'`) may become that template at the new version, and finish, the receipt carry and the tree receipt read it as a stamp. Empty (default) accepts no placeholder.',
restamp_command: 'The repo’s own restamp, run first in gstack-restamp’s staging worktree (a clean checkout of HEAD) with the target version as its argument and in GSTACK_RESTAMP_VERSION; gstack’s version writer is skipped, output confinement still applies. Needs a clean caller tree and --allow-repo-commands.',
migrations: '{ dir, id }: the migration directory and a regex with one capture group for the number in a file name; `gstack-pregate regate` reports MIGRATION_COLLISION against the base branch and every open PR.',
gate_command: 'The repo’s full pre-merge gate command. gstack-ship-queue gate-ahead and ready print it for the caller to run (in the background or in CI); gstack never executes it. null when the repo has none.',
@@ -236,6 +242,7 @@ export const BUMP_NEVER_KEY_VERSION = '1.91.353.0';
export const BASE_RED_KEY_VERSION = '1.91.374.0';
/** `train.gates` and `train.land` are values of the older train key, so compatErrors checks them by value, as for bump: never. */
export const TRAIN_GATES_KEY_VERSION = '1.92.0.0';
export const STAMP_PLACEHOLDERS_KEY_VERSION = '1.94.16.0';
export const REVIEW_EXCLUDE_KEY_VERSION = '1.93.33.0';
export const POLICY_KEY_INTRODUCED: Record<PolicyKey, string> = {
bump: '1.91.73.0', queue_mode: '1.91.73.0', release_tool: '1.91.73.0', release_outputs: '1.91.73.0', stamp_paths: '1.91.73.0',
@@ -245,6 +252,7 @@ export const POLICY_KEY_INTRODUCED: Record<PolicyKey, string> = {
train: TRAIN_KEYS_VERSION, review_scope: REVIEW_SCOPE_KEY_VERSION, docs: DOCS_CAPS_KEY_VERSION,
changelog_fragments: CHANGELOG_FRAGMENTS_KEY_VERSION,
base_red: BASE_RED_KEY_VERSION, review_exclude_paths: REVIEW_EXCLUDE_KEY_VERSION,
stamp_placeholders: STAMP_PLACEHOLDERS_KEY_VERSION,
};
const newer = (a: string, b: string): boolean => cmpVersion(parseVersion(a)!, parseVersion(b)!) > 0;
@@ -274,9 +282,6 @@ const MAX_PATTERN = 256;
const MAX_REGEX = 512;
const MAX_COMMAND = 512;
const SHA_RE = /^[0-9a-f]{7,64}$/;
const MAX_TEMPLATES = 16;
const MAX_TEMPLATE = 128;
export const VERSION_SLOT = '{version}';
function hasDotDot(p: string): boolean {
return p.split(/[\\/]+/).some(seg => seg === '..');
@@ -343,17 +348,6 @@ function excludeErrors(value: unknown, out: PolicyError[]): void {
});
}
function templateErrors(value: unknown, out: PolicyError[]): void {
if (!Array.isArray(value)) { out.push({ code: 'POLICY_INVALID', path: 'stamp_patterns', message: 'must be an array of literal templates' }); return; }
if (value.length > MAX_TEMPLATES) out.push({ code: 'POLICY_CONTAINMENT', path: 'stamp_patterns', message: `more than ${MAX_TEMPLATES} templates` });
value.forEach((t, i) => {
const at = `stamp_patterns[${i}]`;
if (typeof t !== 'string') { out.push({ code: 'POLICY_INVALID', path: at, message: 'must be a string' }); return; }
if (t.split(VERSION_SLOT).length !== 2) out.push({ code: 'POLICY_INVALID', path: at, message: `${JSON.stringify(t)} must contain exactly one ${VERSION_SLOT}` });
else if (t.length > MAX_TEMPLATE || /[\0\r\n]/.test(t)) out.push({ code: 'POLICY_CONTAINMENT', path: at, message: `must be one line of at most ${MAX_TEMPLATE} characters` });
});
}
function migrationErrors(value: unknown, out: PolicyError[]): void {
const m = value as Record<string, unknown> | null;
if (!m || typeof m !== 'object' || Array.isArray(m)) { out.push({ code: 'POLICY_INVALID', path: 'migrations', message: 'must be { dir, id } or null' }); return; }
@@ -497,6 +491,7 @@ export function validatePolicy(raw: unknown, opts: { gstackVersion?: string } =
if ('release_outputs' in obj) listErrors('release_outputs', obj.release_outputs, errors, globError);
if ('stamp_files' in obj) listErrors('stamp_files', obj.stamp_files, errors, globError);
if ('stamp_patterns' in obj) templateErrors(obj.stamp_patterns, errors);
if ('stamp_placeholders' in obj) placeholderErrors(obj.stamp_placeholders, errors);
if ('restamp_command' in obj && obj.restamp_command !== null) {
const t = obj.restamp_command;
if (typeof t !== 'string' || !t.trim()) errors.push({ code: 'POLICY_INVALID', path: 'restamp_command', message: 'must be a non-empty string or null' });
+7
View File
@@ -29,6 +29,7 @@ import * as fs from 'node:fs';
import * as path from 'node:path';
import type { PregateFile } from './headless-artifacts';
import { CHECKS, pregateMirrorPath, readPregateFile, verifyPregate, PREGATE_OUT_REL } from './pregate/index';
import { exceptionConsumerProblem, flakyExceptionLines } from './pregate/flaky-exception';
import { ensureTmpExcluded, restamp, versionAtRef } from './restamp';
import type { ResultCodeName } from './result-codes';
import { extractReceipt } from './ship-receipt';
@@ -232,6 +233,7 @@ export function ready(ctx: QueueContext, o: { pr: string; pregate?: string; gate
const pregateFile = path.resolve(ctx.repoRoot, o.pregate ?? PREGATE_OUT_REL);
let pregateLine = `PREGATE: missing (${path.relative(ctx.repoRoot, pregateFile)}; run gstack-pregate run --allow-repo-commands)`;
let pregateOk = false;
let accepted: PregateFile | null = null;
const treeNow = wtreeFingerprint({ cwd: ctx.repoRoot });
// The mirror stands in for a record that is missing, unreadable, recorded for another tree, or current but
// waiting on a remote receipt another checkout holds; a record whose own checks failed or stayed incomplete (the diff's doing
@@ -242,6 +244,7 @@ export function ready(ctx: QueueContext, o: { pr: string; pregate?: string; gate
if (read.file) {
const v = verifyPregate(ctx.repoRoot, read.file, treeNow);
pregateOk = v.ok;
if (v.ok) accepted = read.file;
useMirror = !v.ok && v.code !== 'PREGATE_LANE_FAILED' && v.code !== 'PREGATE_INCOMPLETE' && v.code !== 'PREGATE_ENVIRONMENT';
pregateLine = `PREGATE: ${read.file.verdict} tree=${read.file.tree.slice(0, 12)} head=${(read.file.head ?? '').slice(0, 12)} checks=${read.file.checks.length}${v.ok ? '' : ` — ${v.message} (${v.code})`}`;
} else pregateLine = `PREGATE: unreadable (${read.errors[0]?.message ?? 'invalid'})`;
@@ -253,9 +256,12 @@ export function ready(ctx: QueueContext, o: { pr: string; pregate?: string; gate
const v = read?.file && !gap ? verifyPregate(ctx.repoRoot, read.file, treeNow) : null;
if (read?.file && v?.ok) {
pregateOk = true;
accepted = read.file;
pregateLine = `PREGATE: ${read.file.verdict} tree=${read.file.tree.slice(0, 12)} head=${(read.file.head ?? '').slice(0, 12)} checks=${read.file.checks.length} (from the state root's pregate/by-tree/${treeNow.tree.slice(0, 12)}.json, recorded by another checkout)`;
} else if (gap) pregateLine += `; the state root's mirror for this tree cannot stand in: ${gap}`;
}
const foreign = accepted && exceptionConsumerProblem(accepted, head, o.pr);
if (foreign) { pregateOk = false; accepted = null; pregateLine += ` — ${foreign} (PREGATE_REMOTE_UNCLEARED)`; }
const receipt = bindShippedReceipt(ctx.repoRoot, `origin/${ctx.base}`, info.body ?? '', o.pr, acceptedReceiptHeads(ctx, policy, head, info.body ?? ''));
const attempt = currentAttempt(ctx.repoRoot, o.pr);
const hint = conflictHint(info.mergeable, ci, info.headRefName, info.isCrossRepository === true, head);
@@ -268,6 +274,7 @@ export function ready(ctx: QueueContext, o: { pr: string; pregate?: string; gate
`ci: ${ci.line}`,
...(hint ? [hint] : []),
pregateLine,
...(accepted ? flakyExceptionLines(accepted) : []),
gateLine(policy, attempt),
receipt.line,
...(receipt.depthLine ? [receipt.depthLine] : []),
+3 -2
View File
@@ -224,7 +224,8 @@ function headInputs(root: string, baseRef: string, head: string, r?: ShipReceipt
/**
* 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, which receipt write alone cannot stand in for.
* 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';
@@ -232,7 +233,7 @@ export function excludeMismatch(x: Exclusion, r: ShipReceipt, head: string, base
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 reviewers read 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 <n> --review-exclude <d> --body <body> with the digest gstack-review-dispatch verify --ledger <ledger> prints on REVIEW_EXCLUDE_RECORD:; a receipt write alone does not clear this`;
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 <n> --review-exclude <d> --body <body> with the digest gstack-review-dispatch verify --ledger <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 => {
+32 -5
View File
@@ -6,6 +6,7 @@
* computes the P7 adoption census over merged PRs (deduplicated by run and
* thread id against an owner-maintained thread cohort).
*/
import { spawnSync } from 'node:child_process';
import { ARTIFACT_SCHEMAS, checkSchema, type ShipReceipt, type ValidationError } from './headless-artifacts';
import { approvalSummary } from './approval-citations';
import { FRAGMENT_README } from './changelog-fragments';
@@ -19,7 +20,7 @@ const KEY_ORDER: Array<keyof ShipReceipt | 'docs'> = [
'schema_version', 'pr', 'head', 'version', 'base', 'gated_tree', 'predecessor', 'tree', 'gate_reuse', 'gate', 'ci', 'ci_carried', 'spend_usd',
'session_kind', 'artifacts_consumed', 'run', 'thread', 'policy', 'queue_mode', 'preregistration', 'history',
'head_tree', 'product_patch_id', 'gstack_version', 'review_depth', 'pregate', 'requires_remote', 'issues', 'approval', 'docs', 'review_loop',
'review_loop_exception', 'review_targeted', 'review_exclude', 'carry', 'base_red',
'review_loop_exception', 'review_targeted', 'review_exclude', 'carry', 'base_red', 'flaky_exception',
];
/** Keys in the fixed order so identifiers lead; undefined values are dropped. */
@@ -177,6 +178,8 @@ export interface CarryPlanInput {
rangeDiff: string;
/** The base the receipt was reviewed against when it differs from the carry's (a stack parent that landed, #3570): productPatchId.from is then the recorded diff against it. */
retargetedFrom?: string;
/** A commit inside the reviewed range whose product change the base already holds (a stack parent that squash-merged under a receipt written against the base, GST-1199): productPatchId.from is then the range from it. */
stackParent?: string;
/** A clean scoped review of product paths whose only difference is base context next to unchanged hunks (lib/ship-patch.ts, GST-384): the carry reason it adds. */
scopedReview?: string;
/** Stamp files the branch changed as product whose only change since the reviewed head is a stamp on the branch's own rows, the base untouched, and without which the two product patches match (GST-980). */
@@ -189,9 +192,9 @@ const CARRY_RERUNS = ['CI at head (gstack-ship-queue ready requires it); test an
/**
* The file's text at the reviewed head and at HEAD, with the release version each head carries (from `VERSION`, else
* `package.json`) and the base policy's `stamp_patterns` templates.
* `package.json`) and the base policy's `stamp_patterns` templates and `stamp_placeholders`.
*/
export interface CarryChange { before: string | null; after: string | null; oldVersion?: string | null; newVersion?: string | null; templates?: readonly string[]; side?: BranchSide }
export interface CarryChange { before: string | null; after: string | null; oldVersion?: string | null; newVersion?: string | null; templates?: readonly string[]; side?: BranchSide; placeholders?: readonly string[] }
/**
* A policy-named stamp path's change is a stamp when the new text reads as the
@@ -214,7 +217,7 @@ export function stampOnlyText(change: CarryChange): boolean {
const now = after.split('\n');
if (was.length !== now.length) return false;
const changed = was.map((line, i) => i).filter(i => was[i] !== now[i]);
return changed.length > 0 && changed.every(i => stampOnlyLine(was[i]!, now[i]!, oldVersion, newVersion, change.templates ?? [], change.side, i + 1));
return changed.length > 0 && changed.every(i => stampOnlyLine(was[i]!, now[i]!, oldVersion, newVersion, change.templates ?? [], change.side, i + 1, change.placeholders ?? []));
}
/**
@@ -253,7 +256,8 @@ export function planCarry(input: CarryPlanInput): CarryPlan {
const named = input.changedProduct.slice(0, CARRY_NAMED_PATHS);
return { ok: false, code: 'RECEIPT_CARRY_PRODUCT_CHANGED', message: `product diff changed between ${input.from.slice(0, 12)} and ${input.head.slice(0, 12)}: ${named.join(', ') || 'patch-id differs'}${input.changedProduct.length > named.length ? ` (+${input.changedProduct.length - named.length} more)` : ''}` };
}
const reasons: string[] = input.retargetedFrom ? [`stack parent ${input.retargetedFrom} landed`] : [];
const parent = input.retargetedFrom ?? input.stackParent?.slice(0, 12);
const reasons: string[] = parent ? [`stack parent ${parent} landed`] : [];
if (input.mergeCommits > 0) reasons.push(input.mergeCommits === 1 ? 'base merge' : `${input.mergeCommits} base merges`);
if (input.scopedReview && input.productPatchId.from !== input.productPatchId.head) reasons.push(input.scopedReview);
if (input.stampedRows?.length && input.productPatchId.from !== input.productPatchId.head) reasons.push(`a stamp on the branch's own rows (${input.stampedRows.join(', ')})`);
@@ -271,6 +275,29 @@ export function planCarry(input: CarryPlanInput): CarryPlan {
};
}
/** How many commits of the reviewed range landedStackParent tries, newest first. */
export const STACK_PARENT_WALK = 100;
/**
* The newest commit inside the reviewed range (rangeBase..reviewed, the reviewed head itself excluded) whose product
* change the current base already holds: merging it into currentBase changes no product path. That is a stack parent
* that squash-merged (or merged) into the base after the receipt was written against the base (GST-1199). A commit with no
* product change of its own (a test-first commit) is no parent, since any base trivially holds it. Null when no
* commit within STACK_PARENT_WALK qualifies or git cannot tell; a conflicted product path is never held.
*/
export function landedStackParent(repoRoot: string, s: { rangeBase: string; reviewed: string; currentBase: string }, product: readonly string[]): string | null {
const run = (args: string[]) => spawnSync('git', args, { cwd: repoRoot, encoding: 'utf8', timeout: 120_000, maxBuffer: 64 * 1024 * 1024 });
const commits = run(['rev-list', '--topo-order', `--max-count=${STACK_PARENT_WALK + 1}`, `${s.rangeBase}..${s.reviewed}`]);
if (commits.status !== 0) return null;
for (const commit of commits.stdout.split('\n').filter(c => c && c !== s.reviewed)) {
if (run(['diff', '--quiet', s.rangeBase, commit, '--', ...product]).status !== 1) continue;
const merged = run(['merge-tree', '--write-tree', '--no-messages', s.currentBase, commit]);
const tree = merged.status === 0 || merged.status === 1 ? merged.stdout.split('\n')[0]?.trim() : undefined;
if (tree && run(['diff', '--quiet', s.currentBase, tree, '--', ...product]).status === 0) return commit;
}
return null;
}
export interface TreeCarryInput {
from: string; head: string;
/** HEAD^{tree}, and every tree the receipt already covers (its head_tree plus earlier carries' trees). */
+36 -4
View File
@@ -15,6 +15,8 @@ import { mergeChangelogs, normalizeChangelog } from './changelog-check';
import { versionAtRef } from './restamp';
import { classifyPath } from './review-depth';
import { comparePath, contextPacket, gateEditedPaths, isTestCode, PACKET_SECTION_CAP, readScopedReview, touchedPaths, type PatchSides } from './ship-patch';
import { locate, readRecord } from './approval-record';
import { reviewFreshness } from './review-evidence';
import { parseReviewLoopException, type ReviewLoopException } from './ship-receipt-depth';
import { parseReceiptDocs, type ReceiptDocs } from './ship-receipt-docs';
import { resolveStateRoot } from './state-root';
@@ -183,8 +185,14 @@ function harnessRepin(cwd: string, from: string, to: string, p: string): boolean
|| (e?.since === b.version && typeof e?.nonBehavioral === 'string' && e.nonBehavioral.trim().length >= 10));
}
/** Step 16 stage 2's route. With --reviewed-base, a path whose branch patch is the reviewed one counts as base (lib/ship-patch.ts). */
type Routed = Record<'behavior' | 'docs' | 'metadata' | 'tests' | 'base' | 'context' | 'accepted', string[]>;
/**
* Step 16 stage 2's route. With --reviewed-base, a path whose branch patch is the reviewed one counts as base (lib/ship-patch.ts).
* A code or test path the newest completed clean review-fix-check row read (inside its range_base..commit range, where
* range_base holds the reviewed tree, and unchanged since) counts as fix_checked when an approved review_loop_grant names a stop
* head inside range_base..commit: the owner's granted fix-check after Step 11 is a review (GST-1130). Authored docs keep the
* stage 2.2 recheck.
*/
type Routed = Record<'behavior' | 'docs' | 'metadata' | 'tests' | 'base' | 'context' | 'accepted' | 'fix_checked', string[]>;
function route(cwd: string, base: string, reviewed: string, reviewedBase: string | undefined, release: string[], opts: { docsRechecked: boolean; contextReviewed?: string; loop?: ReviewLoopException }, r: Report): Routed | null {
const now = bin(cwd, 'gstack-wtree', [], 60_000).stdout.trim();
if (!/^[0-9a-f]{40,64}$/.test(now)) { r.stop('gstack-wtree printed no tree; the stage 2 comparison is blocked'); return null; }
@@ -204,7 +212,7 @@ function route(cwd: string, base: string, reviewed: string, reviewedBase: string
sides = { reviewedBase: rb, reviewed, currentBase: cb, current: now };
touched = new Set([...a, ...b]);
}
const by: Routed = { behavior: [], docs: [], metadata: [], tests: [], base: [], context: [], accepted: [] };
const by: Routed = { behavior: [], docs: [], metadata: [], tests: [], base: [], context: [], accepted: [], fix_checked: [] };
for (const p of [...changedSet].sort()) {
const verdict = sides ? (touched.has(p) ? comparePath(cwd, sides, p) : 'same') : 'changed';
by[verdict === 'same' ? 'base' : release.includes(p) || harnessRepin(cwd, reviewed, now, p) ? 'metadata' : sides && isTestCode(p) ? 'tests' : classifyPath(p, cwd) === 'docs' ? 'docs' : verdict === 'context' ? 'context' : 'behavior'].push(p);
@@ -219,6 +227,30 @@ function route(cwd: string, base: string, reviewed: string, reviewedBase: string
by.context = by.context.filter(p => !packetBody.over.includes(p));
by.tests = by.tests.filter(p => !packetBody.over.includes(p));
}
const fixRow = bin(cwd, 'gstack-review-read', [], 60_000).stdout.split('\n---CONFIG---')[0].split('\n')
.flatMap(l => { try { const v = JSON.parse(l); return v?.skill === 'review-fix-check' ? [v] : []; } catch { return []; } }).at(-1);
const commitOf = (c: unknown) => typeof c === 'string' && /^[0-9a-f]{7,64}$/.test(c) ? git(cwd, ['rev-parse', '--verify', '--quiet', `${c}^{commit}`]).stdout.trim() : '';
const onBranch = (c: string) => !!c && git(cwd, ['merge-base', '--is-ancestor', c, 'HEAD']).status === 0;
const fixCommit = commitOf(fixRow?.commit_full), fixFrom = commitOf(fixRow?.range_base);
const fresh = fixRow && reviewFreshness(fixRow, fixRow.wtree);
const ancestor = (a: string, d: string) => git(cwd, ['merge-base', '--is-ancestor', a, d]).status === 0;
const grants = fixRow ? (loc => 'file' in loc ? readRecord(loc).rows : [])(locate({ cwd, env: process.env })) : [];
const grant = grants.find(g => g.outcome === 'approved' && `${g.ask} ${g.scope}`.includes('review_loop_grant')
&& (`${g.ask} ${g.scope}`.match(/\b[0-9a-f]{7,40}\b/g) ?? []).some(s => { const c = commitOf(s); return !!c && !!fixFrom && !!fixCommit && ancestor(fixFrom, c) && ancestor(c, fixCommit); }));
const notCounted = !fixRow ? '' : fresh?.status !== 'CURRENT' ? fresh?.reason ?? 'not a review row'
: fixRow.tree !== fixRow.wtree || !onBranch(fixCommit) ? 'the row was logged on content no branch commit holds'
: !onBranch(fixFrom) ? 'the row names no range_base commit on this branch'
: git(cwd, ['rev-parse', `${fixFrom}^{tree}`]).stdout.trim() !== reviewed ? `range_base ${fixFrom.slice(0, 12)} does not hold the reviewed tree`
: !grant ? 'no approved review_loop_grant names a stop head inside its range_base..commit' : '';
if (notCounted) r.add(`FIX_CHECK: not counted (${notCounted})`);
const counted = !!fixRow && !notCounted;
if (counted) {
const range = touchedPaths(cwd, fixFrom, fixCommit), after = touchedPaths(cwd, fixCommit, now);
if (!range || !after) { r.stop(`git could not diff the fix-check range ${fixFrom.slice(0, 12)}..${fixCommit.slice(0, 12)} against the reviewed and current trees: stage 2 is blocked`); return null; }
by.fix_checked = [...by.behavior, ...by.tests, ...by.context].filter(p => range.has(p) && !after.has(p)).sort();
for (const k of ['behavior', 'tests', 'context'] as const) by[k] = by[k].filter(p => !by.fix_checked.includes(p));
r.add(`FIX_CHECK: reviewed ${by.fix_checked.length ? short(by.fix_checked) : 'none'} (fix-check at ${fixCommit.slice(0, 12)}, range from ${fixFrom.slice(0, 12)}, grant ${grant!.id})`);
}
const loop = opts.loop;
if (loop) {
const head = loop.fix_check.head;
@@ -233,7 +265,7 @@ function route(cwd: string, base: string, reviewed: string, reviewedBase: string
by.behavior = by.behavior.filter(p => !by.accepted.includes(p));
by.docs = by.docs.filter(p => !by.accepted.includes(p));
}
r.add(`ROUTE: reviewed=${reviewed.slice(0, 12)} current=${now.slice(0, 12)} behavior=${by.behavior.length} docs=${by.docs.length} metadata=${by.metadata.length} tests=${by.tests.length} base=${sides ? by.base.length : 'unknown'} context=${by.context.length}${loop ? ` accepted=${by.accepted.length}` : ''}`);
r.add(`ROUTE: reviewed=${reviewed.slice(0, 12)} current=${now.slice(0, 12)} behavior=${by.behavior.length} docs=${by.docs.length} metadata=${by.metadata.length} tests=${by.tests.length} base=${sides ? by.base.length : 'unknown'} context=${by.context.length}${counted ? ` fix_checked=${by.fix_checked.length}` : ''}${loop ? ` accepted=${by.accepted.length}` : ''}`);
if (loop) r.add(`REVIEW_LOOP_EXCEPTION: accepted ${by.accepted.length ? short(by.accepted) : 'none'} (changed since fix-check ${loop.fix_check.head.slice(0, 12)}; accepted by ${loop.accepted_by} ${loop.date} via ${loop.via})`);
if (by.behavior.length) { r.stop(`behavior, tests or build inputs changed since review (${short(by.behavior.sort())}): insert 5–11.5 → 12–14 → 16 before Step 17 (stage 2.1)`); return null; }
const scoped = [...by.context, ...by.tests].sort();
+596
View File
@@ -0,0 +1,596 @@
/**
* skill-contract — the skill contract checker (GST-1088, lane A).
*
* A targeted skill declares the outputs that must exist before it is done, in
* its SKILL.md frontmatter (schema frozen in plan-v2):
*
* contract: { version: 1, items: [ { id, kind, ... } ] }
*
* checkContract() is a pure function of a Claude Code transcript (the JSONL a
* hook payload's transcript_path names): the model never self-records. Waivers
* are read the same way, from the `gstack-skill-contract waive` Bash calls in
* that transcript, and count as misses for follow. The Stop hook
* (hosts/claude/hooks/skill-contract-stop-hook.ts) and `gstack-skill-contract`
* (check, report, waive) are its two callers; evals can reuse `check`.
* Records live under $GSTACK_STATE_ROOT/skill-contracts/<session id>.json,
* written atomically. Docs: docs/skill-routing-and-contracts.md.
*/
import * as fs from 'fs';
import * as path from 'path';
import { atomicWriteSync } from './fs-atomic';
import { readFrontmatter, scanInstalledSkills } from './skill-route';
import { resolveStateRoot } from './state-root';
export const TRANSCRIPT_MAX_BYTES = 32 * 1024 * 1024;
export const ITEM_KINDS = ['report_labels', 'check_after_last_edit', 'selected_specialists_dispatched', 'agent_dispatch'] as const;
export type ItemKind = typeof ITEM_KINDS[number];
const ITEM_ID = /^[a-z0-9][a-z0-9_.-]{0,63}$/;
const MAX_ITEMS = 20;
/** Stable exit codes of gstack-skill-contract; each has an anchor in docs/skill-routing-and-contracts.md. */
export const EXIT = { MET: 0, UNMET: 1, USAGE: 2, STATE_ERROR: 3, UNKNOWN_SHAPE: 4, NO_CONTRACT: 5, NOT_LOADED: 6 } as const;
export const STATE_ERROR_DOC = 'docs/skill-routing-and-contracts.md#state-error';
export interface ContractItem {
id: string;
kind: ItemKind;
heading?: string;
labels?: string[];
match?: string;
marker?: string;
empty_marker?: string;
fix?: string;
summary?: string;
}
export interface Contract { version: 1; items: ContractItem[] }
export class StateError extends Error {
constructor(readonly file: string, readonly why: string) { super(`${file}: ${why}`); }
}
export class UnknownShape extends Error {}
export function stateErrorLine(file: string, why: string): string {
return `gstack-skill-contract: SKILL_CONTRACT_STATE_ERROR ${file}: ${why}; stop allowed, miss not recorded (see ${STATE_ERROR_DOC})`;
}
const isObject = (v: unknown): v is Record<string, any> => typeof v === 'object' && v !== null && !Array.isArray(v);
const errText = (e: unknown) => (e as NodeJS.ErrnoException)?.code ?? (e instanceof Error ? e.message : String(e));
const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
/** The `contract:` key and its indented lines, or null when the frontmatter has none. */
export function contractBlock(frontmatter: string): string | null {
const lines = frontmatter.split('\n');
const start = lines.findIndex(l => /^contract:/.test(l));
if (start < 0) return null;
let end = start + 1;
while (end < lines.length && (!lines[end].trim() || /^\s/.test(lines[end]))) end++;
return lines.slice(start, end).join('\n');
}
export function parseContract(frontmatter: string): { contract: Contract } | { error: string } | null {
const block = contractBlock(frontmatter);
if (block === null) return null;
let doc: unknown;
try {
doc = Bun.YAML.parse(block);
} catch (e) {
return { error: `contract block is not valid YAML (${errText(e)})` };
}
return validateContract(isObject(doc) ? doc.contract : undefined);
}
const STRING_FIELDS = ['heading', 'match', 'marker', 'empty_marker', 'fix', 'summary'] as const;
const REGEX_FIELDS = ['match'] as const;
/**
* Every default matcher string the checker uses, in one table: edit it here. A contract item's own marker or
* empty_marker replaces its row for that item. Markers are literal text in which a whole-word N is a number.
*/
export const DEFAULT_MATCHERS = {
/** selected_specialists_dispatched: the selection line. The names are the rest of the line; N = 0 selects none. */
specialistSelection: 'Dispatching N specialists:',
/** selected_specialists_dispatched: a line that means no specialist was selected. */
specialistsSkipped: 'specialists skipped',
/** Any contract: a line of the turn's final message, starting with this, means the skill ended the run early (met). A final STATUS: BLOCKED does too. */
earlyExit: 'Nothing to review',
} as const;
/**
* A marker as a pattern: literal text, case-insensitive, any run of spaces matching any whitespace, and a whole-word
* N matching a number (the first one captured as count). The names are the rest of that line.
*/
export function markerPattern(marker: string): RegExp {
const literal = (s: string) => s.split(/\s+/).map(escapeRe).join('\\s+');
const body = marker.split(/\bN\b/).map(literal).map((s, i) => (i === 0 ? s : `${i === 1 ? '(?<count>\\d+)' : '\\d+'}${s}`)).join('');
return new RegExp(`${body}\\s*(?<names>[^\\n]*)`, 'i');
}
export function validateContract(raw: unknown): { contract: Contract } | { error: string } {
if (!isObject(raw)) return { error: 'contract must be a mapping' };
if (raw.version !== 1) return { error: `contract version ${JSON.stringify(raw.version)} is not supported (expected 1)` };
if (!Array.isArray(raw.items) || !raw.items.length || raw.items.length > MAX_ITEMS) {
return { error: `contract items must be a list of 1 to ${MAX_ITEMS} items` };
}
const items: ContractItem[] = [];
for (const [n, item] of raw.items.entries()) {
if (!isObject(item)) return { error: `items[${n}] must be a mapping` };
const id = item.id;
if (typeof id !== 'string' || !ITEM_ID.test(id)) return { error: `items[${n}].id must match ${ITEM_ID}` };
if (items.some(i => i.id === id)) return { error: `duplicate item id ${id}` };
if (!(ITEM_KINDS as readonly string[]).includes(item.kind)) {
return { error: `${id}: unknown kind ${JSON.stringify(item.kind)} (expected one of ${ITEM_KINDS.join(', ')})` };
}
const out: ContractItem = { id, kind: item.kind };
for (const field of STRING_FIELDS) {
if (item[field] === undefined) continue;
if (typeof item[field] !== 'string' || !item[field].trim()) return { error: `${id}: ${field} must be a non-empty string` };
out[field] = item[field].trim();
}
for (const field of REGEX_FIELDS) {
if (out[field] === undefined) continue;
try { new RegExp(out[field] as string, 'i'); } catch { return { error: `${id}: ${field} is not a valid regular expression` }; }
}
if (out.kind === 'report_labels') {
if (!out.heading) return { error: `${id}: report_labels needs a heading` };
if (!Array.isArray(item.labels) || !item.labels.length || item.labels.some((l: unknown) => typeof l !== 'string' || !l.trim())) {
return { error: `${id}: report_labels needs labels, a list of non-empty strings` };
}
out.labels = item.labels.map((l: string) => l.trim());
}
if (out.kind === 'agent_dispatch' && !out.match) return { error: `${id}: agent_dispatch needs match` };
items.push(out);
}
return { contract: { version: 1, items } };
}
/** One plain phrase per item, for the routing hint's "Done means" variant. */
export function itemSummary(item: ContractItem): string {
if (item.summary) return item.summary;
switch (item.kind) {
case 'report_labels': return `a ${item.heading} with ${(item.labels ?? []).join(', ')}`;
case 'check_after_last_edit': return 'a test or repro run after your last edit';
case 'selected_specialists_dispatched': return 'one Agent dispatch per selected specialist';
case 'agent_dispatch': return `an Agent dispatch matching /${item.match}/`;
}
}
export type TranscriptEvent =
| { kind: 'prompt' | 'meta' | 'text'; line: number; text: string }
| { kind: 'tool_use'; line: number; id: string; name: string; input: Record<string, any> }
| { kind: 'tool_result'; line: number; id: string; text: string; isError: boolean };
export interface Transcript { events: TranscriptEvent[]; sessionId: string | null }
const META_PREFIX = /^\s*<(?:local-command-stdout|local-command-stderr|system-reminder|task-notification|user-prompt-submit-hook|bash-input|bash-stdout|bash-stderr)\b/;
function blockText(content: unknown): string {
if (typeof content === 'string') return content;
if (!Array.isArray(content)) return '';
return content.filter(b => isObject(b) && typeof b.text === 'string').map(b => b.text).join('\n');
}
/**
* Main-thread events of a Claude Code transcript JSONL. Sidechain (subagent) records are skipped; unparseable
* lines (a partial last line) are skipped. Throws UnknownShape when the file is not a transcript this parser knows.
*/
export function parseTranscript(text: string): Transcript {
const events: TranscriptEvent[] = [];
let sessionId: string | null = null;
let lines = 0;
let objects = 0;
let messages = 0;
for (const [idx, raw] of text.split('\n').entries()) {
if (!raw.trim()) continue;
lines++;
let rec: unknown;
try { rec = JSON.parse(raw); } catch { continue; }
if (!isObject(rec)) continue;
objects++;
if (rec.type !== 'user' && rec.type !== 'assistant') continue;
const line = idx + 1;
if (!isObject(rec.message)) throw new UnknownShape(`line ${line}: ${rec.type} record without a message object`);
const content = rec.message.content;
if (typeof content !== 'string' && !Array.isArray(content)) throw new UnknownShape(`line ${line}: message content is neither text nor a block list`);
messages++;
if (rec.isSidechain === true) continue;
if (typeof rec.sessionId === 'string') sessionId = rec.sessionId;
const blocks = typeof content === 'string' ? [{ type: 'text', text: content }] : content;
for (const block of blocks) {
if (!isObject(block)) continue;
if (rec.type === 'assistant') {
if (block.type === 'text' && typeof block.text === 'string') events.push({ kind: 'text', line, text: block.text });
if (block.type === 'tool_use' && typeof block.name === 'string') {
events.push({ kind: 'tool_use', line, id: String(block.id ?? ''), name: block.name, input: isObject(block.input) ? block.input : {} });
}
} else if (block.type === 'tool_result') {
events.push({ kind: 'tool_result', line, id: String(block.tool_use_id ?? ''), text: blockText(block.content), isError: block.is_error === true });
} else if (block.type === 'text' && typeof block.text === 'string') {
events.push({ kind: rec.isMeta === true || META_PREFIX.test(block.text) ? 'meta' : 'prompt', line, text: block.text });
}
}
}
if (lines > 0 && objects === 0) throw new UnknownShape('no line is a JSON object');
if (objects > 0 && messages === 0) throw new UnknownShape('no user or assistant message records');
return { events, sessionId };
}
/**
* The transcript with the Stop payload's last_assistant_message as its final text, when the file does not end on it
* yet: Claude Code can fire Stop before it writes the turn's last message.
*/
export function withFinalMessage(t: Transcript, message: unknown): Transcript {
if (typeof message !== 'string' || !message.trim()) return t;
const lastPrompt = t.events.map(e => e.kind).lastIndexOf('prompt');
const lastText = t.events.slice(lastPrompt + 1).filter(e => e.kind === 'text').pop() as { text: string } | undefined;
if (lastText?.text.trim() === message.trim()) return t;
const line = (t.events[t.events.length - 1]?.line ?? 0) + 1;
return { ...t, events: [...t.events, { kind: 'text', line, text: message }] };
}
export function readTranscriptFile(file: string): string {
try {
const size = fs.statSync(file).size;
if (size > TRANSCRIPT_MAX_BYTES) throw new StateError(file, `transcript is ${size} bytes, over the ${TRANSCRIPT_MAX_BYTES} byte read limit`);
return fs.readFileSync(file, 'utf8');
} catch (e) {
if (e instanceof StateError) throw e;
throw new StateError(file, `cannot read transcript (${errText(e)})`);
}
}
export const canonicalSkill = (name: string) => name.trim().toLowerCase().replace(/^\//, '').replace(/^gstack:/, '');
export function sameSkill(a: string, b: string): boolean {
const x = canonicalSkill(a);
const y = canonicalSkill(b);
return x === y || x === `gstack-${y}` || `gstack-${x}` === y;
}
export interface SkillLoad { skill: string; at: number; line: number; via: 'skill-tool' | 'slash-command' | 'read' }
/** Every skill load in order: a Skill tool call, a typed /command, or a Read of a SKILL.md under a skills/ directory (an installed skill, not a checkout's source). */
export function skillLoads(t: Transcript): SkillLoad[] {
const loads: SkillLoad[] = [];
t.events.forEach((e, at) => {
if (e.kind === 'tool_use' && e.name === 'Skill') {
const name = e.input.skill ?? e.input.command;
if (typeof name === 'string' && name.trim()) loads.push({ skill: canonicalSkill(name.split(/\s/)[0]), at, line: e.line, via: 'skill-tool' });
} else if (e.kind === 'tool_use' && e.name === 'Read' && typeof e.input.file_path === 'string') {
const m = /(?:^|[\\/])skills[\\/](?:.*[\\/])?([^\\/]+)[\\/]SKILL\.md$/.exec(e.input.file_path);
if (m) loads.push({ skill: canonicalSkill(m[1]), at, line: e.line, via: 'read' });
} else if (e.kind === 'prompt') {
const m = /<command-name>\s*\/?([^<\s]+)\s*<\/command-name>/.exec(e.text);
if (m) loads.push({ skill: canonicalSkill(m[1]), at, line: e.line, via: 'slash-command' });
}
});
return loads;
}
export const STATUS_RE = /^[ \t>*_-]*(?:\*\*|__)?(?:STATUS|Status)(?:\*\*|__)?[ \t]*(?:\*\*|__)?:[ \t]*(?:\*\*|__)?[ \t]*(DONE_WITH_CONCERNS|DONE|BLOCKED|NEEDS_CONTEXT)\b/m;
const EDIT_TOOLS = /^(?:Edit|Write|MultiEdit|NotebookEdit)$/;
const AGENT_TOOLS = /^(?:Agent|Task)$/;
const CHECK_RUNNER = /^(?:pytest|jest|vitest|mocha|rspec|phpunit|ctest|tox|nox|tsc|make|cargo|go|bun|bunx|npm|npx|pnpm|yarn|node|deno|python3?|ruby|rake|mvn|gradlew?|dotnet|swift|xcodebuild|curl|mix|bazel|just|dart|flutter|rails)$/i;
const CHECK_SCRIPT = /(?:^|[-_.])(?:tests?|spec|repro|check|verify|lint)(?:[-_.]|$)/i;
const COMMAND_WRAPPER = /^(?:bundle|uv|poetry|pipenv|docker|podman|xvfb-run|bash|sh|zsh)$/;
const COMMAND_PREFIX = /^(?:env|sudo|time|nice|timeout|command|exec|\w+=\S*|-\S*|\d+[smh]?)$/;
const isCheckProgram = (word: string) => { const name = word.split(/[\\/]/).pop() ?? ''; return CHECK_RUNNER.test(name) || (name !== 'test' && CHECK_SCRIPT.test(name)); };
const SAFE_SPECIALIST = /^[A-Za-z0-9][A-Za-z0-9 _.-]{0,39}$/;
/**
* A test or repro run: some segment of the command (split on && || ; | and newlines) starts with a test runner or a
* test, check or repro script, directly or behind a wrapper (bundle exec, uv run, docker compose run, xvfb-run, bash).
*/
export function isCheckCommand(cmd: string): boolean {
return cmd.split(/&&|\|\||[;|\n]/).some(segment => {
const words = segment.trim().replace(/^[({]\s*/, '').split(/\s+/);
while (words.length > 1 && COMMAND_PREFIX.test(words[0])) words.shift();
if (isCheckProgram(words[0])) return true;
return COMMAND_WRAPPER.test(words[0].split(/[\\/]/).pop() ?? '') && words.slice(1, 6).some(isCheckProgram);
});
}
const WAIVE_RE = /gstack-skill-contract["']?\s+waive\s+["']?([A-Za-z0-9][A-Za-z0-9_.-]*)["']?/;
type ToolUse = Extract<TranscriptEvent, { kind: 'tool_use' }>;
type ToolResult = Extract<TranscriptEvent, { kind: 'tool_result' }>;
const isToolUse = (e: TranscriptEvent): e is ToolUse => e.kind === 'tool_use';
const bashCommand = (e: TranscriptEvent) => (isToolUse(e) && e.name === 'Bash' ? String(e.input.command ?? '') : null);
const agentText = (e: ToolUse) => [e.input.description, e.input.prompt, e.input.subagent_type, e.input.name].filter(v => typeof v === 'string').join('\n');
const cut = (s: string, n = 80) => (s.length > n ? `${s.slice(0, n - 3)}...` : s).replace(/\s+/g, ' ');
function labelValue(text: string, label: string): string | null {
const re = new RegExp(`^[ \\t>*_|-]*(?:\\*\\*|__)?${escapeRe(label)}[ \\t]*(?:\\*\\*|__)?[ \\t]*:[ \\t]*(?:\\*\\*|__)?(.*)$`, 'im');
const m = re.exec(text);
return m ? m[1].replace(/(?:\*\*|__)\s*$/, '').replace(/^`+|`+$/g, '').trim() : null;
}
export function isPlaceholder(value: string): boolean {
const v = value.trim();
return !v || /^\[[^\]]*\]$/.test(v) || /^<[^>]*>$/.test(v) || /^[A-Z_]+(?:\s*\|\s*[A-Z_]+)+$/.test(v) ||
/^(?:tbd|tba|todo|xxx|fixme|placeholder|\.{2,}|…|-+|—|\?+)$/i.test(v);
}
function parseNames(raw: string): string[] {
const end = raw.search(/\.\s|\.$|\s(?:Skipped|Gated)\s*:/i);
return (end < 0 ? raw : raw.slice(0, end)).replace(/\([^)]*\)/g, ' ').split(/,|;|\band\b/)
.map(n => n.replace(/[[\]()"'`*]/g, '').trim()).filter(n => n && !/^none$/i.test(n));
}
interface ItemCheck { met: boolean; detail: string; fix: string }
function checkItem(item: ContractItem, run: TranscriptEvent[]): ItemCheck {
const texts = run.filter(e => e.kind === 'text').map(e => (e as { text: string }).text);
const agents = run.filter((e): e is ToolUse => isToolUse(e) && AGENT_TOOLS.test(e.name));
switch (item.kind) {
case 'report_labels': {
const heading = item.heading as string;
const labels = item.labels ?? [];
const headingRe = new RegExp(escapeRe(heading), 'i');
const source = [...texts].reverse().find(t => headingRe.test(t));
if (!source) return { met: false, detail: `no ${heading} found`, fix: item.fix ?? `print the ${heading} with real values for ${labels.join(', ')}` };
const after = source.slice(source.search(headingRe));
const bad = labels.filter(label => { const v = labelValue(after, label); return v === null || isPlaceholder(v); });
return bad.length
? { met: false, detail: `${heading} lacks a real value for ${bad.join(', ')}`, fix: item.fix ?? `fill ${bad.join(', ')} in the ${heading} with real values` }
: { met: true, detail: `${heading} has all ${labels.length} labels`, fix: '' };
}
case 'check_after_last_edit': {
let lastEdit = -1;
run.forEach((e, i) => { if (isToolUse(e) && EDIT_TOOLS.test(e.name)) lastEdit = i; });
if (lastEdit < 0) return { met: true, detail: 'no edits since the skill loaded', fix: '' };
const re = item.match ? new RegExp(item.match, 'i') : null;
const check = run.slice(lastEdit + 1).map(bashCommand).find(cmd => {
if (cmd === null || /gstack-skill-contract/.test(cmd)) return false;
const bare = cmd.replace(/"(?:[^"\\]|\\.)*"|'[^']*'/g, '""');
return re ? re.test(bare) : isCheckCommand(bare);
});
return check
? { met: true, detail: `ran "${cut(check)}" after the last edit`, fix: '' }
: { met: false, detail: `no test or repro command after the last ${(run[lastEdit] as ToolUse).name}`, fix: item.fix ?? 'run the test or repro again after your last edit and show its result' };
}
case 'selected_specialists_dispatched': {
const marker = markerPattern(item.marker ?? DEFAULT_MATCHERS.specialistSelection);
const empty = markerPattern(item.empty_marker ?? DEFAULT_MATCHERS.specialistsSkipped);
const bashIds = new Set(run.filter(e => bashCommand(e) !== null).map(e => (e as ToolUse).id));
const sources = run.filter(e => e.kind === 'text' || (e.kind === 'tool_result' && bashIds.has(e.id))).map(e => (e as { text: string }).text).reverse();
let names: string[] | null = null;
for (const src of sources) {
const m = marker.exec(src);
const parsed = m ? (m.groups?.count === '0' ? [] : parseNames(m.groups?.names ?? '')) : null;
if (parsed && parsed.every(n => SAFE_SPECIALIST.test(n))) { names = parsed; break; }
if (empty.test(src)) { names = []; break; }
}
if (names === null) return { met: false, detail: 'no specialist selection line found', fix: item.fix ?? 'print the specialist selection line, then dispatch one Agent per selected specialist' };
if (!names.length) return { met: true, detail: 'no specialists selected', fix: '' };
const missing = names.filter(n => {
const forms = [n, n.replace(/\s+/g, '-'), n.replace(/\s+/g, '_')].map(f => f.toLowerCase());
return !agents.some(a => forms.some(f => agentText(a).toLowerCase().includes(f)));
});
return missing.length
? { met: false, detail: `selected ${names.join(', ')}; no Agent dispatch for ${missing.join(', ')}`, fix: item.fix ?? `dispatch an Agent for ${missing.join(', ')}` }
: { met: true, detail: `dispatched ${names.join(', ')}`, fix: '' };
}
case 'agent_dispatch': {
if (item.marker) {
const marker = markerPattern(item.marker);
let markedAt = -1;
run.forEach((e, i) => { if (e.kind === 'text' && marker.test(e.text)) markedAt = i; });
if (markedAt >= 0 && run.slice(markedAt + 1).some(e => isToolUse(e) && AGENT_TOOLS.test(e.name))) {
return { met: true, detail: `printed "${item.marker}", then an Agent dispatch`, fix: '' };
}
}
const re = new RegExp(item.match as string, 'i');
return agents.some(a => re.test(agentText(a)))
? { met: true, detail: `an Agent dispatch matches /${item.match}/`, fix: '' }
: { met: false, detail: `no Agent dispatch matches /${item.match}/`, fix: item.fix ?? `dispatch the Agent pass matching /${item.match}/` };
}
}
}
/** Waivers in a run: item id -> reason, from waive Bash calls whose result (if any) is not an error. */
function waivers(run: TranscriptEvent[], skill: string, results: Map<string, ToolResult>): Map<string, string> {
const out = new Map<string, string>();
for (const e of run) {
const cmd = bashCommand(e);
const m = cmd === null ? null : WAIVE_RE.exec(cmd);
if (!m || !cmd) continue;
const reason = /--reason[= ]\s*(?:"([^"]*)"|'([^']*)'|(\S+))/.exec(cmd);
const text = reason ? (reason[1] ?? reason[2] ?? reason[3] ?? '').trim() : '';
const skillFlag = /--skill[= ]\s*["']?([^\s"']+)/.exec(cmd);
if (!text || (skillFlag && !sameSkill(skillFlag[1], skill)) || results.get((e as ToolUse).id)?.isError) continue;
out.set(m[1], text);
}
return out;
}
export interface ItemResult { id: string; kind: ItemKind; status: 'met' | 'missing' | 'waived'; detail: string; fix: string; reason?: string }
export interface CheckResult {
skill: string;
version: 1;
loaded: boolean;
load: SkillLoad | null;
items: ItemResult[];
missing: string[];
waived: string[];
/** every item met or waived: nothing to block on */
met: boolean;
/** every item met with no waiver: what follow-rate metrics count */
follow: boolean;
statusLine: string | null;
pendingQuestion: boolean;
pendingAgents: string[];
}
/**
* The contract against one run of the skill: from its load (the last one, or the one at loadLine) to its next load.
* Pure: same transcript, same result.
*/
export function checkContract(t: Transcript, skill: string, contract: Contract, opts: { loadLine?: number } = {}): CheckResult {
const events = t.events;
const loads = skillLoads(t).filter(l => sameSkill(l.skill, skill));
const load = (opts.loadLine === undefined ? loads[loads.length - 1] : loads.find(l => l.line === opts.loadLine)) ?? null;
const next = load ? loads.find(l => l.at > load.at) : undefined;
const run = load ? events.slice(load.at + 1, next?.at) : [];
const results = new Map<string, ToolResult>();
for (const e of run) if (e.kind === 'tool_result') results.set(e.id, e);
const waived = load ? waivers(run, skill, results) : new Map<string, string>();
const lastPrompt = events.map(e => e.kind).lastIndexOf('prompt');
const turn = events.slice(lastPrompt + 1).filter(e => e.kind === 'text' || e.kind === 'tool_use');
const final = turn[turn.length - 1];
const finalText = [...turn].reverse().find(e => e.kind === 'text') as { text: string } | undefined;
const statusLine = finalText ? STATUS_RE.exec(finalText.text)?.[1] ?? null : null;
const exitMarker = new RegExp(`^[ \\t>*_-]*${markerPattern(DEFAULT_MATCHERS.earlyExit).source}`, 'im');
const endedEarly = !!finalText && run.includes(finalText as TranscriptEvent) && exitMarker.test(finalText.text);
const earlyExit = !load ? null : statusLine === 'BLOCKED' ? 'STATUS: BLOCKED' : endedEarly ? DEFAULT_MATCHERS.earlyExit : null;
const items: ItemResult[] = load ? contract.items.map(item => {
if (earlyExit) return { id: item.id, kind: item.kind, status: 'met', detail: `the skill ended the run early (${earlyExit})`, fix: '' };
const r = checkItem(item, run);
if (r.met) return { id: item.id, kind: item.kind, status: 'met', detail: r.detail, fix: '' };
const reason = waived.get(item.id);
return reason ? { id: item.id, kind: item.kind, status: 'waived', detail: r.detail, fix: r.fix, reason } : { id: item.id, kind: item.kind, status: 'missing', detail: r.detail, fix: r.fix };
}) : [];
const lastParagraph = (finalText?.text ?? '').trim().split(/\n\s*\n/).pop() ?? '';
const pendingQuestion = statusLine === 'NEEDS_CONTEXT' || (final !== undefined && isToolUse(final) && /AskUserQuestion$/.test(final.name)) ||
(final !== undefined && final.kind === 'text' && /\?[\s*_)"']*$/.test(lastParagraph));
const pendingAgents = run.flatMap((e, i) => {
if (!isToolUse(e) || !AGENT_TOOLS.test(e.name)) return [];
const result = results.get(e.id);
if (!result) return [e.id];
const resultAt = run.indexOf(result);
const ids = [e.id, ...[...result.text.matchAll(/\b(?:agent|task)[_ -]?id["']?\s*[:=]\s*["']?([\w-]+)/gi)].map(m => m[1])].filter(Boolean);
const named = ids.map(id => new RegExp(`(?:^|[^\\w-])${escapeRe(id)}(?:[^\\w-]|$)`));
const notified = run.slice(resultAt + 1).some(n => n.kind === 'meta' && named.some(re => re.test(n.text)));
return e.input.run_in_background === true && i < resultAt && !notified ? [e.id] : [];
});
const missing = items.filter(i => i.status === 'missing').map(i => i.id);
const waivedIds = items.filter(i => i.status === 'waived').map(i => i.id);
return {
skill, version: 1, loaded: !!load, load, items, missing, waived: waivedIds,
met: !!load && missing.length === 0, follow: !!load && missing.length === 0 && waivedIds.length === 0,
statusLine, pendingQuestion, pendingAgents,
};
}
/** The one agent-facing block text (gate rev 2, E1). It never names the off switch: that is for humans, in the docs and setup. */
export function blockMessage(result: CheckResult): string {
const fixes = result.items.filter(i => i.status === 'missing').map(i => `${i.id}: ${i.fix}`).join('; ');
return `SKILL_CONTRACT_UNMET ${result.skill} (contract v1): missing ${result.missing.join(', ')}. Fix: ${fixes}. ` +
'If an item truly does not apply, run gstack-skill-contract waive <item> --reason "<why>" (this session only; counted as a miss for follow). This blocks once.';
}
export type ContractLookup =
| { skill: string; file: string; contract: Contract }
| { skill: string; file: string | null; error: string; reason: 'not-found' | 'no-contract' | 'invalid' };
/** The contract of an installed skill (by frontmatter name or directory), or of an explicit SKILL.md. */
export function lookupContract(skill: string, skillsDir: string, skillFile?: string): ContractLookup {
let file: string | null = skillFile ?? null;
let frontmatter: string | null = null;
if (file) {
try { frontmatter = readFrontmatter(file); } catch (e) { return { skill, file, error: `cannot read ${file} (${errText(e)})`, reason: 'not-found' }; }
} else {
const found = scanInstalledSkills(skillsDir).skills.find(s => sameSkill(s.name, skill) || sameSkill(path.basename(path.dirname(s.file)), skill));
if (found) { file = found.file; frontmatter = found.frontmatter; }
}
if (!file) return { skill, file, error: `no installed skill named ${skill} under ${skillsDir}`, reason: 'not-found' };
const parsed = frontmatter === null ? null : parseContract(frontmatter);
if (parsed === null) return { skill, file, error: `${file} declares no contract`, reason: 'no-contract' };
return 'error' in parsed ? { skill, file, error: `${file}: ${parsed.error}`, reason: 'invalid' } : { skill, file, contract: parsed.contract };
}
export type Outcome = 'met' | 'met_waived' | 'blocked' | 'met_after_block' | 'miss';
export interface RunRecord { skill: string; load_line: number; outcome: Outcome; missing: string[]; waived: string[]; blocked_at?: string; updated_at: string }
export interface SessionRecord { version: 1; session_id: string; transcript_path: string; runs: Record<string, RunRecord> }
export function recordsDir(env: NodeJS.ProcessEnv = process.env): string {
return path.join(resolveStateRoot(env), 'skill-contracts');
}
export function recordPath(sessionId: string, env: NodeJS.ProcessEnv = process.env): string {
const safe = sessionId.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 128);
if (!safe) throw new StateError(recordsDir(env), 'hook payload has no session_id');
return path.join(recordsDir(env), `${safe}.json`);
}
export const runKey = (skill: string, load: SkillLoad) => `${canonicalSkill(skill)}@${load.line}`;
export function readRecord(file: string): SessionRecord | null {
let text: string;
try {
text = fs.readFileSync(file, 'utf8');
} catch (e) {
if ((e as NodeJS.ErrnoException)?.code === 'ENOENT' || (e as NodeJS.ErrnoException)?.code === 'ENOTDIR') return null;
throw new StateError(file, `cannot read record (${errText(e)})`);
}
let rec: unknown;
try { rec = JSON.parse(text); } catch { throw new StateError(file, 'corrupt record (not JSON)'); }
if (!isObject(rec) || rec.version !== 1 || typeof rec.session_id !== 'string' || !isObject(rec.runs)) {
throw new StateError(file, 'corrupt record (unexpected shape)');
}
return rec as SessionRecord;
}
export function writeRecord(file: string, rec: SessionRecord): void {
try {
fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
atomicWriteSync(file, `${JSON.stringify(rec, null, 2)}\n`, { mode: 0o600 });
} catch (e) {
throw new StateError(file, `cannot write record (${errText(e)})`);
}
}
/**
* Block at most once per skill run: an unmet contract blocks unless this run was already blocked, which makes it a miss.
* A run recorded met, met_waived or met_after_block is final: later unrelated turns in the session never reopen it.
*/
export function nextOutcome(prev: RunRecord | undefined, result: CheckResult): { outcome: Outcome; block: boolean } {
if (prev && (prev.outcome === 'met' || prev.outcome === 'met_waived' || prev.outcome === 'met_after_block')) return { outcome: prev.outcome, block: false };
if (result.met) return { outcome: prev?.blocked_at ? 'met_after_block' : result.waived.length ? 'met_waived' : 'met', block: false };
return prev?.blocked_at ? { outcome: 'miss', block: false } : { outcome: 'blocked', block: true };
}
/** Count one unknown transcript shape in $GSTACK_STATE_ROOT/hooks/skill-contract.canary.json; returns the new count, 0 when it cannot be written. */
export function bumpCanary(why: string, env: NodeJS.ProcessEnv = process.env): number {
try {
const file = path.join(resolveStateRoot(env), 'hooks', 'skill-contract.canary.json');
let count = 0;
try { count = Number(JSON.parse(fs.readFileSync(file, 'utf8')).count) || 0; } catch { /* first one */ }
fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
atomicWriteSync(file, `${JSON.stringify({ count: count + 1, last_cause: why, updated_at: new Date().toISOString() })}\n`, { mode: 0o600 });
return count + 1;
} catch {
return 0;
}
}
export interface ReportRow { session: string; skill: string; outcome: Outcome | 'fixed_after_block'; missing: string[]; waived: string[]; transcript: string }
/** Every recorded run; a run still marked blocked is re-checked against its transcript when a recheck is given. */
export function reportRows(records: SessionRecord[], recheck?: (rec: SessionRecord, run: RunRecord) => CheckResult | null): ReportRow[] {
return records.flatMap(rec => Object.values(rec.runs).map(run => {
const row: ReportRow = { session: rec.session_id, skill: run.skill, outcome: run.outcome, missing: run.missing, waived: run.waived, transcript: rec.transcript_path };
if (run.outcome !== 'blocked' || !recheck) return row;
const again = recheck(rec, run);
if (!again) return row;
return again.met
? { ...row, outcome: 'fixed_after_block' as const, missing: [], waived: again.waived }
: { ...row, outcome: 'miss' as const, missing: again.missing, waived: again.waived };
}));
}
/** A miss for follow: blocked and never fixed, stopped again unmet, or met only through a waiver. */
export const isMiss = (row: ReportRow) => row.outcome === 'blocked' || row.outcome === 'miss' || row.waived.length > 0;
export function readAllRecords(env: NodeJS.ProcessEnv = process.env): { records: SessionRecord[]; errors: string[] } {
const dir = recordsDir(env);
const records: SessionRecord[] = [];
const errors: string[] = [];
let names: string[] = [];
try { names = fs.readdirSync(dir).filter(n => n.endsWith('.json')).sort(); } catch { return { records, errors }; }
for (const name of names) {
try {
const rec = readRecord(path.join(dir, name));
if (rec) records.push(rec);
} catch (e) {
errors.push(e instanceof StateError ? `${e.file}: ${e.why}` : String(e));
}
}
return { records, errors };
}
+305
View File
@@ -0,0 +1,305 @@
/**
* skill-route — deterministic prompt-to-skill routing (GST-1088, lane A).
*
* The UserPromptSubmit hook (hosts/claude/hooks/skill-route-hook.ts) and
* `gstack-skill-route --explain` score a prompt against the `triggers:` lists
* in the installed skills' SKILL.md frontmatter. No model call, no network:
* the same prompt and the same installed skills always give the same route.
*
* Also home to what both skill hooks share: the on/off switches
* (skill_routing, skill_contracts), the installed-skills directory, the
* bounded stdin reader and the trace log under $GSTACK_STATE_ROOT/hooks/.
* Docs: docs/skill-routing-and-contracts.md.
*/
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import { atomicWriteSync } from './fs-atomic';
import { frontmatterList } from './skill-triggers';
import { readConfigKey, resolveStateRoot } from './state-root';
/** A route needs at least this share of a trigger's content words (2 of 3, 3 of 4; both of 2). */
export const ROUTE_THRESHOLD = 0.66;
/** Longer prompts (pasted logs, files) are never routed: their words match everything. */
export const PROMPT_MAX_CHARS = 8000;
const FRONTMATTER_MAX_BYTES = 16 * 1024;
const MAX_SKILLS = 256;
const MAX_TRIGGER_CHARS = 200;
const TRACE_MAX_BYTES = 1024 * 1024;
const FAILURE_SESSIONS_KEPT = 64;
export type SwitchName = 'skill_routing' | 'skill_contracts';
export const SWITCH_ENV: Record<SwitchName, string> = {
skill_routing: 'GSTACK_SKILL_ROUTING',
skill_contracts: 'GSTACK_SKILL_CONTRACTS',
};
export function normalizeSwitch(raw: string | null | undefined): 'on' | 'off' | null {
const v = String(raw ?? '').trim().toLowerCase();
if (['on', 'yes', 'y', 'true', '1'].includes(v)) return 'on';
if (['off', 'no', 'n', 'false', '0', 'skip'].includes(v)) return 'off';
return null;
}
export interface SwitchReading { on: boolean; source: string; invalid?: string }
/** env GSTACK_SKILL_ROUTING / GSTACK_SKILL_CONTRACTS > config key > default off. An unrecognized value is off. */
export function readSkillSwitch(name: SwitchName, env: NodeJS.ProcessEnv = process.env): SwitchReading {
const envName = SWITCH_ENV[name];
const raw = env[envName];
if (raw !== undefined && raw !== '') {
const v = normalizeSwitch(raw);
return v ? { on: v === 'on', source: `env ${envName}` } : { on: false, source: `env ${envName}`, invalid: raw };
}
const cfg = readConfigKey(name, env);
if (cfg === null) return { on: false, source: 'default' };
const v = normalizeSwitch(cfg);
return v ? { on: v === 'on', source: `config ${name}` } : { on: false, source: `config ${name}`, invalid: cfg };
}
/** Where Claude Code reads skills: GSTACK_INSTALLED_SKILLS_DIR, else ${CLAUDE_CONFIG_DIR:-~/.claude}/skills. */
export function installedSkillsDir(env: NodeJS.ProcessEnv = process.env): string {
if (env.GSTACK_INSTALLED_SKILLS_DIR) return env.GSTACK_INSTALLED_SKILLS_DIR;
return path.join(env.CLAUDE_CONFIG_DIR || path.join(env.HOME || os.homedir(), '.claude'), 'skills');
}
/** The frontmatter between the leading `---` lines, read from at most the first 16 KiB; null without one. */
export function readFrontmatter(file: string): string | null {
const fd = fs.openSync(file, 'r');
try {
const buf = Buffer.alloc(FRONTMATTER_MAX_BYTES);
const text = buf.subarray(0, fs.readSync(fd, buf, 0, FRONTMATTER_MAX_BYTES, 0)).toString('utf8').replace(/\r\n/g, '\n');
if (!text.startsWith('---\n')) return null;
const end = text.indexOf('\n---', 4);
return end < 0 ? null : text.slice(4, end);
} finally {
fs.closeSync(fd);
}
}
export function frontmatterName(frontmatter: string, fallback: string): string {
const m = /^name:\s*(.+)$/m.exec(frontmatter);
return m ? m[1].trim().replace(/^["']|["']$/g, '') : fallback;
}
export interface InstalledSkill { name: string; file: string; frontmatter: string; triggers: string[] }
/** Every installed skill with frontmatter, sorted by directory; `problems` names skills whose triggers the repo's reader cannot use. */
export function scanInstalledSkills(dir: string): { skills: InstalledSkill[]; problems: string[] } {
const skills: InstalledSkill[] = [];
const problems: string[] = [];
let entries: string[];
try {
entries = fs.readdirSync(dir).sort().slice(0, MAX_SKILLS);
} catch {
return { skills, problems: [`skills directory unreadable: ${dir}`] };
}
for (const entry of entries) {
const file = path.join(dir, entry, 'SKILL.md');
let frontmatter: string | null;
try {
frontmatter = readFrontmatter(file);
} catch {
continue;
}
if (frontmatter === null) continue;
const name = frontmatterName(frontmatter, entry);
let triggers: string[] = [];
if (/^triggers:/m.test(frontmatter)) {
triggers = frontmatterList(`---\n${frontmatter}\n---`, 'triggers');
if (!triggers.length || triggers.some(t => !t || t.length > MAX_TRIGGER_CHARS)) {
problems.push(`${name}: malformed triggers`);
triggers = [];
}
}
skills.push({ name, file, frontmatter, triggers });
}
return { skills, problems };
}
const STOPWORDS = new Set(('a an the this that these those it its i me my we our us you your he she they them their ' +
'is are was were be been being am do does did done to of in on at by for from with as into onto about and or but ' +
'so if then than just please can could would should will shall may might must some any all here there now ' +
'up out over get got let lets want need make sure ok okay hey hi').split(' '));
/** Lowercase, light stemming: plural s/es, -ing and -ed, with a doubled final consonant undone. */
export function stem(word: string): string {
let w = word.toLowerCase().replace(/'s$/, '');
if (w.length > 4 && /(?:xes|sses|shes|ches|zes)$/.test(w)) w = w.slice(0, -2);
else if (w.length > 3 && w.endsWith('s') && !w.endsWith('ss') && !w.endsWith('us')) w = w.slice(0, -1);
if (w.length > 5 && w.endsWith('ing')) w = w.slice(0, -3);
else if (w.length > 4 && w.endsWith('ed')) w = w.slice(0, -2);
if (/([b-df-hj-np-tv-z])\1$/.test(w) && !/(?:ll|ss|zz|ff)$/.test(w)) w = w.slice(0, -1);
return w;
}
const words = (text: string) => text.toLowerCase().match(/[a-z0-9]+(?:'[a-z]+)?/g) ?? [];
export function tokens(text: string): string[] {
return words(text).map(stem);
}
export function contentTokens(text: string): string[] {
return [...new Set(words(text).filter(w => !STOPWORDS.has(w)).map(stem))];
}
export interface RouteCandidate { skill: string; score: number; matched: number; trigger: string; file: string }
/** A lone content word specific enough to route on by itself: five or more letters, not a question word. */
const SPECIFIC_WORD = /^(?!(?:what|which|where|whose)$)[a-z0-9]{5,}$/;
/**
* Every skill whose best trigger shares a content word with the prompt, best first (score, matched words,
* name). A trigger's score is 1 when its whole phrase appears in the prompt, else the share of its content
* words (stopwords dropped, lightly stemmed) that the prompt contains. A trigger with one content word scores
* only on its whole phrase unless that word is specific (SPECIFIC_WORD).
*/
export function scorePrompt(prompt: string, skills: InstalledSkill[]): RouteCandidate[] {
const promptSeq = ` ${tokens(prompt).join(' ')} `;
const promptSet = new Set(contentTokens(prompt));
const out: RouteCandidate[] = [];
for (const skill of skills) {
let best: RouteCandidate | null = null;
for (const trigger of skill.triggers) {
const content = contentTokens(trigger);
if (!content.length) continue;
const matched = content.filter(w => promptSet.has(w)).length;
const phrase = promptSeq.includes(` ${tokens(trigger).join(' ')} `);
const weakSingle = content.length === 1 && !SPECIFIC_WORD.test(content[0]);
const score = phrase ? 1 : weakSingle ? 0 : Math.round((matched / content.length) * 100) / 100;
if (score > 0 && (!best || score > best.score || (score === best.score && matched > best.matched))) {
best = { skill: skill.name, score, matched, trigger, file: skill.file };
}
}
if (best) out.push(best);
}
return out.sort((a, b) => b.score - a.score || b.matched - a.matched || a.skill.localeCompare(b.skill));
}
/**
* The skills the hook may route to: plan-v2 decision 4's discovery targets. Run D's prompts showed routing
* every installed skill's triggers false-routes most non-fit prompts (docs/skill-routing-and-contracts.md).
*/
export const ROUTED_SKILLS = ['investigate', 'review', 'qa', 'verify'];
const isRouted = (name: string) => ROUTED_SKILLS.includes(name.toLowerCase().replace(/^gstack[-:]/, ''));
export type RouteDecision =
| { route: RouteCandidate; candidates: RouteCandidate[] }
| { route: null; reason: 'slash-command' | 'prompt-too-long' | 'empty' | 'below-threshold'; candidates: RouteCandidate[] };
export function routePrompt(prompt: string, skills: InstalledSkill[], threshold = ROUTE_THRESHOLD): RouteDecision {
const trimmed = prompt.trim();
if (!trimmed) return { route: null, reason: 'empty', candidates: [] };
if (trimmed.startsWith('/')) return { route: null, reason: 'slash-command', candidates: [] };
if (prompt.length > PROMPT_MAX_CHARS) return { route: null, reason: 'prompt-too-long', candidates: [] };
const candidates = scorePrompt(prompt, skills.filter(s => isRouted(s.name)));
const top = candidates[0];
return top && top.score >= threshold ? { route: top, candidates } : { route: null, reason: 'below-threshold', candidates };
}
export type HintVariant = 'name' | 'step' | 'contract';
export const HINT_VARIANTS: HintVariant[] = ['name', 'step', 'contract'];
/** The default line (d6 pilot); GSTACK_SKILL_ROUTE_HINT selects another variant for the pilot. */
export const DEFAULT_HINT_VARIANT: HintVariant = 'name';
export function hintVariant(env: NodeJS.ProcessEnv = process.env): HintVariant {
const v = (env.GSTACK_SKILL_ROUTE_HINT || '').trim().toLowerCase();
return (HINT_VARIANTS as string[]).includes(v) ? v as HintVariant : DEFAULT_HINT_VARIANT;
}
/** The one additionalContext line: its source, its off switch, the skill, and the ask to say gstack routed it. */
export function hintLine(route: RouteCandidate, extra = ''): string {
const s = `/${route.skill}`;
const trigger = route.trigger.replace(/["\s]+/g, ' ').trim();
return `gstack skill routing (UserPromptSubmit hook; matched the installed ${s} trigger "${trigger}"; off: gstack-config set skill_routing off): ` +
`this request fits ${s}. Run ${s} with the Skill tool before you start, and tell the user in one sentence that gstack routed this to ${s}.` +
(extra.trim() ? ` ${extra.replace(/\s+/g, ' ').trim()}` : '');
}
/** First sentence under a skill body's first "Step 1", "Phase 1" or "How to work" heading, plain text, at most 200 chars; '' without one. */
export function firstStep(skillMd: string): string {
const m = /^#{2,3}\s+(?:Step\s*0*1\b|Phase\s*0*1\b|How to work\b).*$/im.exec(skillMd);
if (!m) return '';
const para = skillMd.slice(m.index + m[0].length).split(/\n\s*\n/).map(p => p.trim())
.find(p => p && !p.startsWith('```') && !p.startsWith('#'));
if (!para) return '';
const plain = para.replace(/[*_`]/g, '').replace(/\s+/g, ' ');
const sentence = (/^.*?[.!?](?=\s|$)/.exec(plain)?.[0] ?? plain).trim();
return sentence.length > 200 ? `${sentence.slice(0, 197).replace(/\s+\S*$/, '')}...` : sentence;
}
export interface BoundedStdin { text: string; overCap: boolean }
/** A hook payload: returns at EOF, at the first complete JSON value, at the deadline, or as soon as it passes capBytes. */
export function readStdinBounded(capBytes: number, ms: number, stream: NodeJS.ReadStream = process.stdin): Promise<BoundedStdin> {
return new Promise((resolve) => {
let buf = '';
let bytes = 0;
let settled = false;
const done = (overCap: boolean) => {
if (settled) return;
settled = true;
clearTimeout(timer);
stream.removeAllListeners('data');
try { stream.destroy(); } catch { /* already closed */ }
resolve({ text: overCap ? '' : buf, overCap });
};
const timer = setTimeout(() => done(false), ms);
stream.on('data', (chunk: Buffer | string) => {
const b = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
bytes += b.length;
if (bytes > capBytes) { done(true); return; }
buf += b.toString('utf8');
try { JSON.parse(buf); done(false); } catch { /* keep reading */ }
});
stream.on('end', () => done(false));
stream.on('error', () => done(false));
});
}
export type TraceHook = 'skill-route' | 'skill-contract';
export function traceLogPath(hook: TraceHook, env: NodeJS.ProcessEnv = process.env): string {
return path.join(resolveStateRoot(env), 'hooks', `${hook}.log`);
}
const traceValue = (v: string | number | boolean) => {
const s = String(v).replace(/[\r\n\t]+/g, ' ');
return /[\s"=]/.test(s) ? JSON.stringify(s) : s;
};
/**
* Append one trace line to $GSTACK_STATE_ROOT/hooks/<hook>.log (rotated to .log.1 past 1 MiB). A failure also
* bumps the session's count in <hook>.failures.json and the line carries `failures=<n>`. Never throws, never
* writes stderr, never logs prompt text.
*/
export function appendHookTrace(hook: TraceHook, sessionId: string, fields: Record<string, string | number | boolean>,
failed = false, env: NodeJS.ProcessEnv = process.env): void {
try {
const log = traceLogPath(hook, env);
const dir = path.dirname(log);
fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
const sid = sessionId.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 64) || 'unknown';
const parts = [`session=${sid}`, ...Object.entries(fields).map(([k, v]) => `${k}=${traceValue(v)}`)];
if (failed) {
const counter = path.join(dir, `${hook}.failures.json`);
let sessions: Record<string, number> = {};
try {
const parsed = JSON.parse(fs.readFileSync(counter, 'utf8'));
if (parsed && typeof parsed.sessions === 'object' && parsed.sessions) sessions = parsed.sessions;
} catch { /* first failure, or a corrupt counter that starts over */ }
const n = (Number(sessions[sid]) || 0) + 1;
delete sessions[sid];
sessions[sid] = n;
const kept = Object.fromEntries(Object.entries(sessions).slice(-FAILURE_SESSIONS_KEPT));
atomicWriteSync(counter, `${JSON.stringify({ sessions: kept })}\n`, { mode: 0o600 });
parts.push(`failures=${n}`);
}
try {
if (fs.statSync(log).size > TRACE_MAX_BYTES) fs.renameSync(log, `${log}.1`);
} catch { /* no log yet */ }
fs.appendFileSync(log, `${new Date().toISOString()} ${parts.join(' ')}\n`, { mode: 0o600 });
} catch {
// tracing is best-effort; a hook never fails because its log did
}
}
+28 -4
View File
@@ -4,7 +4,8 @@
* lines the branch wrote itself. Split from restamp.ts (module-size ratchet).
*/
import { spawnSync } from 'node:child_process';
import { branchAddedLines, forkVersion, rewriteStamps, stampMentions } from './restamp';
import { branchAddedLines, escapeRegExp, forkVersion, rewriteStamps, stampMentions } from './restamp';
import { VERSION_SLOT } from './ship-policy';
import { cmpVersion, parseVersion, versionWidth } from './version-source';
/**
@@ -26,12 +27,20 @@ import { cmpVersion, parseVersion, versionWidth } from './version-source';
* stage's bound for its own lines (GST-895, GST-963): finish's stampedFiles,
* the tree receipt and the receipt carry all pass the same side. When the
* version does not move (a slot that keeps its claimed VERSION), only such a
* branch line may change: the stage moves nothing else then.
* branch line may change: the stage moves nothing else then. On such a branch
* line a declared placeholder (`stamp_placeholders`, GST-1026: gbrain's
* `since: 'TBD'`) may also become the new version, but only inside a
* `stamp_patterns` template with literal text around its slot, never a built-in
* form: with at least one such rewrite, the line must then be the added line,
* or one whose remaining stamp-form moves pass the fork-version bound.
*/
export function stampOnlyLine(removed: string, added: string, oldV: string, newV: string, templates: readonly string[] = [], side?: BranchSide, at?: number): boolean {
export function stampOnlyLine(removed: string, added: string, oldV: string, newV: string, templates: readonly string[] = [], side?: BranchSide, at?: number, placeholders: readonly string[] = []): boolean {
if (removed === added) return false;
if (oldV !== newV && stampOnlyWithin(removed, added, oldV, newV, templates)) return true;
return !!side && at !== undefined && side.at.has(at) && side.added.has(removed) && stampOnlyWithin(removed, added, side.fork, newV, templates);
if (!side || at === undefined || !side.at.has(at) || !side.added.has(removed)) return false;
if (stampOnlyWithin(removed, added, side.fork, newV, templates)) return true;
const filled = fillPlaceholders(removed, newV, templates, placeholders);
return filled.count > 0 && (filled.text === added || stampOnlyWithin(filled.text, added, side.fork, newV, templates));
}
/**
@@ -64,6 +73,21 @@ export function branchSides(repoRoot: string, baseRef: string, head: string, fal
};
}
/** Each declared placeholder rewritten to `newV` inside each template with literal text around its slot (a bare edge at a word boundary). */
function fillPlaceholders(removed: string, newV: string, templates: readonly string[], placeholders: readonly string[]): { text: string; count: number } {
let text = removed;
let count = 0;
for (const t of templates) {
const [pre, post] = t.split(VERSION_SLOT) as [string, string];
if (!pre && !post) continue;
for (const p of placeholders) {
const re = new RegExp(`${escapeRegExp(pre)}${pre ? '' : '(?<![A-Za-z0-9_.])'}${escapeRegExp(p)}${post ? '' : '(?![A-Za-z0-9_.])'}${escapeRegExp(post)}`, 'g');
text = text.replace(re, () => { count++; return pre + newV + post; });
}
}
return { text, count };
}
function stampOnlyWithin(removed: string, added: string, oldV: string, newV: string, templates: readonly string[]): boolean {
const floor = parseVersion(oldV);
const width = versionWidth(oldV);
+5 -4
View File
@@ -78,15 +78,16 @@ export function classifyFiles(repoRoot: string, fileDiffs: FileDiff[], gated: st
/**
* Every removed/added pair differs only by stamp rewrites to the new version:
* the old version, or a tentative one (newer than it) the stamp_paths stage
* moved (#3512), each in a stamp form (`stampOnlyLine`, bounded by the fork version on the branch's own lines).
* moved (#3512), each in a stamp form (`stampOnlyLine`, bounded by the fork version on the branch's own lines, where a
* declared placeholder may also move inside a stamp_patterns template, GST-1026).
*/
function stampOnlyHunks(hunks: FileDiff['hunks'], oldV: string, newV: string, templates: readonly string[], side?: BranchSide): { why: string; line: number } | null {
function stampOnlyHunks(hunks: FileDiff['hunks'], oldV: string, newV: string, templates: readonly string[], side?: BranchSide, placeholders: readonly string[] = []): { why: string; line: number } | null {
for (const h of hunks) {
if (h.removed.length !== h.added.length) return { why: `${h.removed.length} line(s) removed, ${h.added.length} added`, line: h.at };
for (let i = 0; i < h.removed.length; i++) {
const r = h.removed[i]!;
const a = h.added[i]!;
if (!stampOnlyLine(r, a, oldV, newV, templates, side, h.removedAt[i])) return { why: `${JSON.stringify(r.trim().slice(0, 60))} -> ${JSON.stringify(a.trim().slice(0, 60))}`, line: h.at + i };
if (!stampOnlyLine(r, a, oldV, newV, templates, side, h.removedAt[i], placeholders)) return { why: `${JSON.stringify(r.trim().slice(0, 60))} -> ${JSON.stringify(a.trim().slice(0, 60))}`, line: h.at + i };
}
}
return null;
@@ -130,7 +131,7 @@ export function classifyFile(repoRoot: string, f: FileDiff, gated: string, curre
const rule = matchesAny(policy.stamp_paths, f.path) ? 'stamp_paths' : matchesAny(policy.release_outputs, f.path) ? 'release_outputs' : matchesAny(policy.stamp_files, f.path) ? 'stamp_files' : null;
const own = rule ? side?.(f.path) : undefined;
if (oldV && newV && (oldV !== newV || own) && rule) {
const bad = stampOnlyHunks(f.hunks, oldV, newV, policy.stamp_patterns, own);
const bad = stampOnlyHunks(f.hunks, oldV, newV, policy.stamp_patterns, own, policy.stamp_placeholders);
return bad ? changed(rule, bad.why, bad.line) : stamp(rule);
}
return changed('other', `${f.hunks.length} hunk(s) outside every stamp rule`);