mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-17 05:41:50 +01:00
Merge remote-tracking branch 'origin/main' into gsta-155-autoplan-carry
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> # Conflicts: # CHANGELOG.md
This commit is contained in:
commit
ba42ed27a9
111 files changed
+4342
-498
No files matched your search
@@ -71,6 +71,8 @@ export interface PregateCheck {
|
||||
stage?: 'preflight' | 'tests'; inputs?: Record<string, string>; fix?: string; code?: string; lines?: string[];
|
||||
// Lane D (GSTA-112): a non-pass names its cause; an environment cause carries its kind and evidence.
|
||||
cause?: 'diff' | 'environment'; environment?: { kind: string; evidence: string; proof?: 'launch' | 'output' };
|
||||
/** `regen`: the touched outputs the generator recreated byte-identically from a deleted copy (what a receipt carry may set aside as generated). */
|
||||
proven?: string[];
|
||||
}
|
||||
/** 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 }> }
|
||||
@@ -101,7 +103,14 @@ export interface ShipReceipt {
|
||||
issues?: { fixes: number[]; refs: number[]; flakes: Array<{ issue: number; run: string }>; related?: Array<{ pr: number; repo?: string; author: string; closes: number[]; supersedes?: boolean; credit?: boolean }> };
|
||||
/** Harness lane E: the review loop's counters (gstack-review-scope summary) and the carry record when the receipt followed a head whose product diff was unchanged (gstack-ship-receipt carry). */
|
||||
review_loop?: { passes: number; blocking_found: number; deferred: number; noted?: number; fixed?: number; scope?: string; fix_checks?: number; dispatches?: Record<string, number>; est_input_tokens?: number };
|
||||
carry?: { from: string; reason: string; product_patch_id: string; changed_paths: string[]; merge_commits: number; range_diff: string; covers: string[]; reruns: string[] };
|
||||
carry?: { from: string; reason: string; product_patch_id: string; changed_paths: string[]; merge_commits: number; range_diff: string; covers: string[]; reruns: string[]; trees?: string[]; ancestry?: 'linear' | 'rewritten' };
|
||||
/** The reviewed head's tree and its product patch-id against the base (gstack-ship-receipt write; carry rebinds both): what a carry across rewritten history compares. */
|
||||
head_tree?: string; product_patch_id?: string;
|
||||
/** The gstack that wrote the receipt, and the review depth the reviewed head needs, recomputed at write (lib/ship-receipt-depth.ts receiptDepthAtHead). */
|
||||
gstack_version?: string;
|
||||
review_depth?: { depth: 'light' | 'standard' | 'full'; class: 'docs' | 'tests' | 'code' | 'gate'; runtime_lines: number; rules: string; base: string; registry: string | null; gate_scan: { tagged: number | null; head: string }; reasons: string[] };
|
||||
/** The owner's acceptance of a stop after a fix-check edit under frozen scope (#3559); the PR body repeats it word for word. */
|
||||
review_loop_exception?: { accepted_by: string; date: string; via: string; reason: string; fix_check: { head: string; findings: number; files?: string[] } };
|
||||
}
|
||||
|
||||
export const RESULT_STATUSES: readonly ResultStatus[] = ['complete', 'gate_pending', 'amend_pending', 'incomplete', 'interrupted', 'refused'];
|
||||
@@ -206,7 +215,7 @@ export const ARTIFACT_SCHEMAS = {
|
||||
type: 'object', required: ['schema_version', 'tree', 'checks'],
|
||||
properties: {
|
||||
schema_version: { const: 1 }, run: str, tree: str, stage1_ms: num, stage2_ms: num,
|
||||
checks: { type: 'array', items: { type: 'object', required: ['id', 'status'], properties: { id: str, status: { enum: ['pass', 'fail', 'warn', 'incomplete', 'requires-remote', 'not_installed'] }, ms: num, detail: str, stage: { enum: ['preflight', 'tests'] }, inputs: { type: 'object' }, fix: str, code: str, lines: strList, cause: { enum: ['diff', 'environment'] }, environment: { type: 'object', required: ['kind', 'evidence'], properties: { kind: str, evidence: str } } } } },
|
||||
checks: { type: 'array', items: { type: 'object', required: ['id', 'status'], properties: { id: str, status: { enum: ['pass', 'fail', 'warn', 'incomplete', 'requires-remote', 'not_installed'] }, ms: num, detail: str, stage: { enum: ['preflight', 'tests'] }, inputs: { type: 'object' }, fix: str, code: str, lines: strList, cause: { enum: ['diff', 'environment'] }, environment: { type: 'object', required: ['kind', 'evidence'], properties: { kind: str, evidence: str } }, proven: strList } } },
|
||||
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 } } } } } } } },
|
||||
@@ -222,7 +231,10 @@ export const ARTIFACT_SCHEMAS = {
|
||||
pregate: { ...str, description: 'pass|warn|requires-remote cleared … @<tree> from pregate.json, current for this head' }, requires_remote: strList,
|
||||
approval: { type: 'object', description: 'approval classes: { source, status: checked|unavailable, classes: [{ class, scope, effects, citation: verified|unverified, approved_by, date, via, binding, evidence }], report_only }' },
|
||||
review_loop: { type: 'object', required: ['passes', 'blocking_found', 'deferred'], properties: { passes: { type: 'integer', minimum: 0 }, blocking_found: { type: 'integer', minimum: 0 }, deferred: { type: 'integer', minimum: 0 }, noted: { type: 'integer', minimum: 0 }, fixed: { type: 'integer', minimum: 0 }, scope: str, fix_checks: { type: 'integer', minimum: 0 }, dispatches: { type: 'object', description: 'reviewer dispatches by role' }, est_input_tokens: { type: 'integer', minimum: 0 } } },
|
||||
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 } },
|
||||
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,
|
||||
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 } },
|
||||
review_loop_exception: { type: 'object', required: ['accepted_by', 'date', 'via', 'reason', 'fix_check'], properties: { accepted_by: str, date: str, via: str, reason: str, fix_check: { type: 'object', required: ['head', 'findings'], properties: { head: str, findings: { type: 'integer', minimum: 0 }, files: strList } } } },
|
||||
issues: { type: 'object', properties: { fixes: { type: 'array', items: { type: 'integer' } }, refs: { type: 'array', items: { type: 'integer' } }, flakes: { type: 'array', items: { type: 'object', required: ['issue', 'run'], properties: { issue: { type: 'integer' }, run: str } } }, related: { type: 'array', items: { type: 'object', required: ['pr', 'author', 'closes'], properties: { pr: { type: 'integer' }, repo: str, author: str, closes: { type: 'array', items: { type: 'integer' } }, supersedes: { type: 'boolean' }, credit: { type: 'boolean' } } } } } },
|
||||
},
|
||||
},
|
||||
|
||||
@@ -23,7 +23,7 @@ function run(ctx: PregateContext): CheckResult {
|
||||
fix: 'rerun with --allow-repo-commands (what /ship passes)', lines: commands.map(c => `COMMAND: ${c.id}=${JSON.stringify(c.command)} outputs=${c.outputs.join(',')}`),
|
||||
};
|
||||
}
|
||||
const { results } = runRegen({ repoRoot: ctx.repoRoot, registry: ctx.registry, mode: 'check', only: selected.map(e => e.id), env: ctx.env, timeoutMs: ctx.timeoutMs });
|
||||
const { results } = runRegen({ repoRoot: ctx.repoRoot, registry: ctx.registry, mode: 'check', only: selected.map(e => e.id), prove: ctx.touched.map(t => t.path), env: ctx.env, timeoutMs: ctx.timeoutMs });
|
||||
const lines = results.map(renderEntry);
|
||||
const stale = results.filter(r => r.status === 'stale');
|
||||
const failed = results.filter(r => r.status === 'failed');
|
||||
@@ -32,7 +32,8 @@ function run(ctx: PregateContext): CheckResult {
|
||||
if (depsMissing.length) return { id: 'regen', stage: 'preflight', status: 'incomplete', inputs, lines, code: 'REGEN_DEPS_MISSING', detail: `dependencies missing; ${depsMissing[0]!.fix} (${depsMissing.length} entr${depsMissing.length === 1 ? 'y' : 'ies'} unverified: ${depsMissing.map(d => d.id).join(', ')})`, fix: depsMissing[0]!.fix };
|
||||
if (failed.length) return { id: 'regen', stage: 'preflight', status: 'incomplete', inputs, lines, code: 'REGEN_COMMAND_FAILED', detail: `${failed.length} regen command(s) failed: ${failed.map(f => f.id).join(', ')}`, fix: failed.map(f => f.fix).join('; ') };
|
||||
if (stale.length) return { id: 'regen', stage: 'preflight', status: 'fail', inputs, lines, code: 'REGEN_STALE', detail: `${stale.length} stale: ${stale.flatMap(s => s.changed.concat(s.outside)).join(' ')}`, fix: stale.map(s => s.fix).join('; ') };
|
||||
return { id: 'regen', stage: 'preflight', status: 'pass', inputs, lines, detail: `${results.length} entr${results.length === 1 ? 'y' : 'ies'} fresh${results.some(r => r.status === 'listed') ? ' (hand-regenerated outputs listed)' : ''}` };
|
||||
const proven = results.flatMap(r => r.proven ?? []).sort();
|
||||
return { id: 'regen', stage: 'preflight', status: 'pass', inputs, lines, ...(proven.length ? { proven } : {}), detail: `${results.length} entr${results.length === 1 ? 'y' : 'ies'} fresh${results.some(r => r.status === 'listed') ? ' (hand-regenerated outputs listed)' : ''}` };
|
||||
}
|
||||
|
||||
export const regenCheck: CheckDef = { id: 'regen', stage: 'preflight', tier: 1, downgradable: true, needsRepoCommands: true, run };
|
||||
@@ -321,7 +321,7 @@ export function explainConfig(): string {
|
||||
'local: <workflow.yml>/<job> lanes a local run satisfies (platform-agnostic toolchain, or CI off); their tests run here, not requires-remote',
|
||||
'guards: [{ id, when: [globs], command, fix?, timeout_s? }]: each guard whose globs match a touched file runs in its own process (--allow-repo-commands); a failure fails pregate with the guard id and fix; never downgradable',
|
||||
`serial_patterns: test-file globs the lanes check runs one process per file, apart from the unit files (default ${DEFAULT_SERIAL_PATTERNS.join(', ')})`,
|
||||
'sealed: { paths, transcripts, answer_markers, seed_patterns, local_paths, visibility }: sealed or eval output the pre-push hook and `gstack-pregate sealed` refuse to publish to a public destination (docs/pregate.md#sealed)',
|
||||
'sealed: { paths, transcripts, answer_markers, seed_patterns, local_paths, allow_paths, case_insensitive, visibility }: sealed or eval output the pre-push hook and `gstack-pregate sealed` refuse to publish to a public destination; allow_paths (base branch only) exempt publishable files from the path globs (docs/pregate.md#sealed)',
|
||||
'price_file: repo-relative path of the GSTACK_EVAL_CALLS v1 call-plan file `gstack-eval-plan price-gate` prices a paid gate from; never executed (docs/eval-calls.md)',
|
||||
'stall_timeout_s: seconds without test output before the lanes check kills the runner\'s process group and records it incomplete (default 300; 0 disables; --stall-timeout overrides)',
|
||||
'remote_gate: the repo\'s remote test gate command; under 8 cores the test tier becomes a requires-remote obligation naming it, and gstack-pregate --remote runs it (it must print PREGATE_REMOTE: tree=<tree> tests=<n> failed=<n>) (docs/pregate.md#remote-gate)',
|
||||
|
||||
+59
-2
@@ -201,6 +201,35 @@ function looksLikeCompactTimestamp(span: string): boolean {
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Bare integers that programs print as constants: 2^30 through 2^49 and each
|
||||
* one minus one (`4294967296`, `2147483647`), and the 32-bit multipliers,
|
||||
* offsets and primes of common hashes and PRNGs (Knuth's multiplicative hash,
|
||||
* the golden-ratio constant, the glibc and Numerical Recipes LCGs, FNV-1a,
|
||||
* MurmurHash2 and 3, the MT19937 seeder, the largest 32-bit prime). pii.phone.e164
|
||||
* reads each as a bare 10-15 digit number. Only the exact separator-free value
|
||||
* is exempt: the same digits with a `+`, spaces, dashes or dots still report,
|
||||
* so an E.164 number, which carries its `+`, is never exempt.
|
||||
*/
|
||||
const NUMERIC_CONSTANTS: ReadonlySet<string> = new Set([
|
||||
...Array.from({ length: 20 }, (_, i) => 2n ** BigInt(30 + i)).flatMap((p) => [String(p), String(p - 1n)]),
|
||||
"2654435761",
|
||||
"2654435769",
|
||||
"1103515245",
|
||||
"1013904223",
|
||||
"2166136261",
|
||||
"1540483477",
|
||||
"3432918353",
|
||||
"2246822507",
|
||||
"3266489909",
|
||||
"1812433253",
|
||||
"4294967291",
|
||||
]);
|
||||
|
||||
export function isNumericConstant(span: string): boolean {
|
||||
return NUMERIC_CONSTANTS.has(span);
|
||||
}
|
||||
|
||||
/** Context window for pairing a normalized parcel ID with its punctuated form. */
|
||||
const PARCEL_CONTEXT_CHARS = 400;
|
||||
|
||||
@@ -446,6 +475,31 @@ export function isDotenvFilename(match: RegExpExecArray): boolean {
|
||||
return spanStart > 0 && input[spanStart - 1] === ".";
|
||||
}
|
||||
|
||||
/** A trailing run of file extensions that are not top-level domains (checked
|
||||
* against the IANA root zone list, 2026-10-28). Extensions that are also TLDs
|
||||
* (`.md`, `.py`, `.sh`, `.rs`, `.so`, `.zip`, `.mov`, `.map`) are left out on
|
||||
* purpose. */
|
||||
const NON_TLD_EXTENSIONS = /(?:\.(?:json|jsonc|jsonl|ndjson|ya?ml|toml|lock|txt|csv|tsv|log|ini|cfg|conf|xml|html?|[mc]?js|jsx|tsx?|tgz|gz|tar|bz2|xz|zst|whl|jar|gem|nupkg|deb|rpm|wasm|svg|png|jpe?g|pdf|patch|diff))+$/i;
|
||||
|
||||
/**
|
||||
* True when a pii.email span is a filename with an `@` in it rather than an
|
||||
* address: `terminal-bench@2.0.json`, `lodash@4.17.21.tgz`,
|
||||
* `eslint-config@next.yaml`. The package@version convention puts a version or
|
||||
* tag after the `@`, so either sign decides: the "domain" ends in file
|
||||
* extensions no TLD uses and what precedes them cannot be a domain (one dotless
|
||||
* label or a dotted version), or it is a dotted version (two or more all-digit
|
||||
* labels) followed by an extension that doubles as a TLD (`a@1.2.md`). A file
|
||||
* named after an address (`jane@acme.com.json`), `user@163.com`,
|
||||
* `alice@1.2.com` and an address at a TLD that doubles as an extension
|
||||
* (`dev@acme.sh`, `ops@acme.md`) still report.
|
||||
*/
|
||||
export function looksLikeAtFilename(span: string): boolean {
|
||||
const domain = span.slice(span.lastIndexOf("@") + 1);
|
||||
const stem = domain.replace(NON_TLD_EXTENSIONS, "");
|
||||
if (stem !== domain) return !/\.[A-Za-z]{2,}$/.test(stem);
|
||||
return /^\d+(?:\.\d+)+\.(?:md|py|sh|rs|so|zip|mov|map)$/i.test(domain);
|
||||
}
|
||||
|
||||
/** Extensions that mark a `<name>.local.<ext>` span as a file. Closed on
|
||||
* purpose: `.md` is also Moldova's TLD, but no internal suffix sits in front
|
||||
* of a public one, so after `.local` it can only be an extension. */
|
||||
@@ -955,6 +1009,7 @@ export const PATTERNS: RedactPattern[] = [
|
||||
regex: /\b([A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,})\b/,
|
||||
autoRedactable: true,
|
||||
redactToken: "<REDACTED-EMAIL>",
|
||||
validate: (span) => !looksLikeAtFilename(span),
|
||||
// Engine layers the email allowlist (example.com, noreply@, user's own,
|
||||
// repo-public authors) on top of this — see redact-engine.ts.
|
||||
},
|
||||
@@ -969,12 +1024,14 @@ export const PATTERNS: RedactPattern[] = [
|
||||
// A digit-only UUID's hyphen groups read as national phone formatting, and
|
||||
// so do a county tax-map parcel ID (see looksLikeParcelId), vector
|
||||
// coordinates (looksLikeDecimalCoordinates) and seed/nonce/timestamp JSON
|
||||
// values (isNumericMetadataValue), and GitHub Actions run and job ids in
|
||||
// their id positions (isCiRunIdentifier).
|
||||
// values (isNumericMetadataValue), GitHub Actions run and job ids in
|
||||
// their id positions (isCiRunIdentifier), and bare powers of two and
|
||||
// hash/PRNG constants (isNumericConstant).
|
||||
validate: (span, match) =>
|
||||
!insideUuid(match) &&
|
||||
span.replace(/\D/g, "").length >= 10 &&
|
||||
!looksLikeCompactTimestamp(span) &&
|
||||
!isNumericConstant(span) &&
|
||||
!looksLikeParcelId(span, match) &&
|
||||
!looksLikeDecimalCoordinates(span) &&
|
||||
!isNumericMetadataValue(span, match) &&
|
||||
|
||||
+19
-3
@@ -164,6 +164,8 @@ export interface EntryResult {
|
||||
exit?: number | null; stderr?: string; ms: number;
|
||||
/** The exact command an author runs to refresh the entry. */
|
||||
fix: string;
|
||||
/** `check` with `prove`, on a fresh entry: the deleted outputs the proof run recreated byte-identically (an output it never writes, or a proof run that failed, proves nothing). */
|
||||
proven?: string[];
|
||||
}
|
||||
|
||||
/** Working tree vs the seeded index in a scratch worktree: modified tracked files plus new untracked ones. */
|
||||
@@ -214,6 +216,8 @@ export interface RunRegenOptions {
|
||||
only?: string[];
|
||||
/** Restrict to entries whose inputs or outputs intersect these paths. */
|
||||
touched?: string[];
|
||||
/** `check`: outputs to prove on a fresh entry: a second run with each one deleted first, the ones it recreates byte-identically come back as `proven`. The verdict comes from the first run alone. */
|
||||
prove?: readonly string[];
|
||||
env?: NodeJS.ProcessEnv; timeoutMs?: number;
|
||||
}
|
||||
|
||||
@@ -248,10 +252,22 @@ export function runRegen(o: RunRegenOptions): { results: EntryResult[]; wtree: s
|
||||
if (run.exit !== 0) { results.push({ id: e.id, command: e.command, status: 'failed', changed, outside, exit: run.exit, stderr: run.stderr, ms, fix: fixFor(e) }); continue; }
|
||||
if (o.mode === 'check') {
|
||||
const differs = changed.length > 0 || outside.length > 0;
|
||||
if (differs && install) results.push({ id: e.id, command: e.command, status: 'deps-missing', changed, outside, exit: 0, ms, fix: `run ${install}, then rerun the check` });
|
||||
else results.push({ id: e.id, command: e.command, status: differs ? 'stale' : 'fresh', changed, outside, exit: 0, ms, fix: fixFor(e) });
|
||||
// Reset the scratch so the next entry's diff is its own.
|
||||
git(cwd, ['checkout', '-q', '--', '.']); git(cwd, ['clean', '-fdq']);
|
||||
const reset = () => { git(cwd, ['checkout', '-q', '--', '.']); git(cwd, ['clean', '-fdq']); };
|
||||
reset();
|
||||
if (differs && install) { results.push({ id: e.id, command: e.command, status: 'deps-missing', changed, outside, exit: 0, ms, fix: `run ${install}, then rerun the check` }); continue; }
|
||||
// The proof is a second run apart from the verdict: each touched output deleted first, the ones recreated
|
||||
// byte-identically are proven, and a failure (a generator that reads its own output) proves nothing.
|
||||
const probe = differs ? [] : (o.prove ?? []).filter(p => matchesAny(e.outputs, p) && fs.existsSync(path.join(cwd, p)));
|
||||
let proven: string[] | undefined;
|
||||
if (probe.length) {
|
||||
for (const p of probe) fs.rmSync(path.join(cwd, p), { force: true });
|
||||
const proof = runCommand(cwd, e.command, o.env ?? process.env, timeout);
|
||||
const redo = changedPaths(cwd);
|
||||
proven = proof.exit === 0 ? probe.filter(p => !redo.includes(p)) : [];
|
||||
reset();
|
||||
}
|
||||
results.push({ id: e.id, command: e.command, status: differs ? 'stale' : 'fresh', changed, outside, exit: 0, ms, fix: fixFor(e), ...(proven ? { proven } : {}) });
|
||||
} else results.push({ id: e.id, command: e.command, status: changed.length ? 'written' : 'fresh', changed, outside, exit: 0, ms, fix: fixFor(e) });
|
||||
}
|
||||
} finally { scratch?.remove(); }
|
||||
|
||||
+16
-2
@@ -223,6 +223,19 @@ export function versionFiles(root: string, versionRel: string): string[] {
|
||||
const dir = path.dirname(pkgRel) === '.' ? '' : path.dirname(pkgRel) + '/';
|
||||
return [versionRel, pkgRel, ...NPM_LOCKFILES.map(l => dir + l)];
|
||||
}
|
||||
/**
|
||||
* The manifest's path when the repo's convention is a four-part manifest: the policy lists it as a
|
||||
* stamp file and the base's copy holds a four-part version (gbrain). Read at the base, like the
|
||||
* policy, so a branch an older restamp cut to three parts heals. Otherwise null, and the writer
|
||||
* stores the npm-valid three-part form (decision 11; gstack's own manifest).
|
||||
*/
|
||||
function manifestKeepsFourParts(plan: Plan, root: string): string | null {
|
||||
const pkgRel = versionFiles(root, plan.versionRel)[1]!;
|
||||
if (pkgRel === plan.versionRel || !matchesAny([...plan.policy.stamp_paths, ...plan.policy.stamp_files], pkgRel)) return null;
|
||||
const atBase = git(root, ['show', `${plan.baseSha}:${pkgRel}`]);
|
||||
const version = atBase.ok ? extractVersion(atBase.out, pkgRel) : '';
|
||||
return version && versionWidth(version) === 4 ? pkgRel : null;
|
||||
}
|
||||
function allowedOutput(plan: Plan, root: string, rel: string): boolean {
|
||||
const p = plan.policy;
|
||||
if (versionFiles(root, plan.versionRel).includes(rel)) return true;
|
||||
@@ -455,9 +468,10 @@ function runStages(o: RestampOptions, plan: Plan, staging: string, since: string
|
||||
const v = stage('version');
|
||||
if (command) { v.status = 'skipped'; v.detail = 'restamp_command owns the version'; }
|
||||
else {
|
||||
const w = spawnSync(process.execPath, [...bunIsolationArgs(), path.join(BIN_DIR, 'gstack-version-bump'), 'write', '--version', plan.newVersion], { cwd: staging, encoding: 'utf8', timeout: 120_000, env });
|
||||
const full = manifestKeepsFourParts(plan, staging);
|
||||
const w = spawnSync(process.execPath, [...bunIsolationArgs(), path.join(BIN_DIR, 'gstack-version-bump'), 'write', '--version', plan.newVersion, ...(full ? ['--manifest-form', 'full'] : [])], { cwd: staging, encoding: 'utf8', timeout: 120_000, env });
|
||||
if (w.status !== 0) { v.status = 'failed'; v.detail = (w.stderr ?? '').trim().slice(0, 300); throw new Refusal('RESTAMP_VERSION_SOURCE', `gstack-version-bump write failed: ${v.detail}; nothing written`); }
|
||||
v.status = 'done'; v.detail = `wrote ${plan.newVersion}`;
|
||||
v.status = 'done'; v.detail = `wrote ${plan.newVersion}` + (full ? ` (${full} keeps four parts: a policy stamp file the base holds in four)` : '');
|
||||
}
|
||||
injected('version');
|
||||
|
||||
|
||||
@@ -148,6 +148,16 @@ export const RELEASE_RESULT_CODES = {
|
||||
summary: 'the PR body’s /ship receipt is for another head than the one being READY’d or merged (a push after /ship, or a receipt copied from another PR)',
|
||||
fix: 'rerun /ship on the current head so the receipt names it, then gstack-ship-queue ready again; a slot’s stamp commit keeps the receipt written for its pinned head',
|
||||
},
|
||||
QUEUE_RECEIPT_DEPTH_RAISED: {
|
||||
anchor: 'queue-receipt-depth-raised',
|
||||
summary: 'the PR body’s /ship receipt records a review depth below the one its head needs (the queue recomputed it from git), or a current receipt records no review_depth at all',
|
||||
fix: 'run /ship on the head the READY names; the REVIEW_DEPTH line shows the receipt’s depth, the required depth, its reasons and inputs, and the receipt is left unchanged',
|
||||
},
|
||||
QUEUE_RECEIPT_EXCEPTION_INVALID: {
|
||||
anchor: 'queue-receipt-exception-invalid',
|
||||
summary: 'the PR body’s /ship receipt records an owner exception (docs or review loop) that is malformed, lacks the fix-check it follows, or whose line the body no longer carries verbatim',
|
||||
fix: 'restore the exception line in the PR body word for word, or run /ship again and record the owner’s acceptance with --docs or --review-loop-exception',
|
||||
},
|
||||
QUEUE_SCREEN_STALE_REF: {
|
||||
anchor: 'queue-screen-stale-ref',
|
||||
summary: 'GitHub’s refs/pull/<n>/merge is missing or still merges an older head than the PR’s: the PR conflicts with the base (a CHANGELOG-only conflict counts), so a screen dispatched on it would plan no cases and report success',
|
||||
@@ -246,18 +256,28 @@ export const RELEASE_RESULT_CODES = {
|
||||
},
|
||||
RECEIPT_CARRY_REFUSED: {
|
||||
anchor: 'receipt-carry-refused',
|
||||
summary: 'gstack-ship-receipt carry could not carry the /ship receipt to HEAD: the PR body has no receipt, the receipt head is not an ancestor of HEAD (rebase or force-push), or the product diff could not be compared',
|
||||
fix: 'merge the base in instead of rebasing, keep the reviewed head in HEAD\'s history, then rerun carry; otherwise run /ship on the new head',
|
||||
summary: 'gstack-ship-receipt carry could not carry the /ship receipt to HEAD: the PR body has no receipt, the working tree has uncommitted changes, the receipt head is not an ancestor of HEAD and the receipt records no tree to compare, or the product diff could not be compared',
|
||||
fix: 'commit or stash working-tree changes and rerun carry; when history was rewritten and the receipt predates head_tree, run /ship on the new head (merge the base in instead of rebasing next time)',
|
||||
},
|
||||
PROSE_LINT_FOUND: {
|
||||
anchor: 'prose-lint-found',
|
||||
summary: 'the prose /ship is about to publish (a CHANGELOG entry or a PR body) carries an AI tell a regular expression can decide',
|
||||
fix: 'rewrite each PROSE: line in the draft the way its hint says, then rerun gstack-prose-lint on the same file',
|
||||
},
|
||||
REVIEW_LOOP_EXCEPTION_INVALID: {
|
||||
anchor: 'review-loop-exception-invalid',
|
||||
summary: 'write --review-loop-exception got an exception that is malformed, follows no fix-check (review_loop.fix_checks is 0 or missing), names a fix-check head that is not the receipt head or its ancestor, or is missing from the PR body',
|
||||
fix: 'pass { accepted_by, date, via, reason, fix_check: { head, findings } } with the owner’s words, the --review-loop summary that counts the fix-check, and the printed "Review-loop exception: …" line in the body',
|
||||
},
|
||||
RECEIPT_CARRY_TREE_MISMATCH: {
|
||||
anchor: 'receipt-carry-tree-mismatch',
|
||||
summary: 'the branch was rebased or force-pushed since its /ship receipt, and HEAD\'s tree is not a tree the receipt covers, so no review saw this code',
|
||||
fix: 'run /ship on the new head; next time merge the base in instead of rebasing a reviewed branch (a rebase carries only onto a reviewed tree with the reviewed product diff)',
|
||||
},
|
||||
RECEIPT_CARRY_PRODUCT_CHANGED: {
|
||||
anchor: 'receipt-carry-product-changed',
|
||||
summary: 'the product diff against the base changed between the receipt\'s head and HEAD (a product file differs beyond a base merge, a test-only fix or release metadata), so the reviewed verdict does not cover HEAD',
|
||||
fix: 'run /ship on the new head; the receipt carries only when every changed path is a test, release metadata or the base merge and the product patch-id is unchanged',
|
||||
summary: 'the product diff against the base changed between the receipt\'s head and HEAD (a product file differs beyond a base merge, a test-only fix, release metadata or a regenerated output), so the reviewed verdict does not cover HEAD',
|
||||
fix: 'run /ship on the new head; the receipt carries only when every changed path is a test, release metadata, a registered output the pregate regen check proved, or the base merge, and the product patch-id is unchanged',
|
||||
},
|
||||
DOCS_AUDIT_BLOCKED: {
|
||||
anchor: 'docs-audit-blocked',
|
||||
|
||||
+1
-1
@@ -597,7 +597,7 @@ export const RESULT_CODES = {
|
||||
},
|
||||
UPGRADE_BUSY: {
|
||||
anchor: 'upgrade-busy',
|
||||
summary: 'bin/gstack-upgrade changed nothing: another live session holds a workflow lease on this installation (bin/gstack-lease live), so moving the checkout would change gstack under it',
|
||||
summary: 'bin/gstack-upgrade changed nothing: another live session holds a workflow lease on this installation (bin/gstack-lease live), or, at a Capy install, the caller\'s own run does, so moving the checkout would change gstack under it',
|
||||
fix: 'wait for those sessions to finish (bin/gstack-lease list names each pid and age), then re-run bin/gstack-upgrade; GSTACK_UPGRADE_FORCE=1 overrides when you know they are idle',
|
||||
},
|
||||
UPGRADE_FETCH_FAILED: {
|
||||
|
||||
@@ -0,0 +1,137 @@
|
||||
/**
|
||||
* review-collect — the git reads behind a review depth (docs/review-policy.md#review-depth),
|
||||
* kept out of lib/review-depth.ts so the policy stays pure. collectCommit reads git
|
||||
* objects only (a range between two commits, from any checkout, dirty or not);
|
||||
* collectLive reads the working tree as /ship reviews it (committed, tracked
|
||||
* uncommitted edits and untracked files). Both return a ClassInput with per-path
|
||||
* line counts, the base commit's generated-output registry and collector errors;
|
||||
* the caller adds the gate-scan result.
|
||||
*/
|
||||
import { spawnSync } from 'node:child_process';
|
||||
import * as fs from 'node:fs';
|
||||
import * as path from 'node:path';
|
||||
import { GENERATED_PATH, parseRegistry } from './regen';
|
||||
import { RESULT_CODES } from './result-codes';
|
||||
import type { ClassInput, DepthError, PathLines, RegistryInfo } from './review-depth';
|
||||
|
||||
export interface Collected extends ClassInput {
|
||||
perPath: PathLines[];
|
||||
registry: RegistryInfo;
|
||||
errors: DepthError[];
|
||||
deleted: string[];
|
||||
stampOnly: string[];
|
||||
/** Added lines per path, for scanNumbers. */
|
||||
added: Record<string, string[]>;
|
||||
diffLines: number;
|
||||
mergeBase: string | null;
|
||||
untracked: string[];
|
||||
}
|
||||
|
||||
function git(root: string, args: string[]): { ok: boolean; out: string; err: string } {
|
||||
const r = spawnSync('git', ['-c', 'core.quotePath=false', ...args], { cwd: root, encoding: 'utf8', timeout: 60_000, maxBuffer: 256 * 1024 * 1024 });
|
||||
return { ok: r.status === 0, out: r.stdout ?? '', err: (r.stderr ?? '').trim() };
|
||||
}
|
||||
const scratch = (p: string) => p.startsWith('.gstack/tmp/');
|
||||
const oneLine = (s: string) => s.replace(/[\0-\x1f]+/g, ' ').trim().slice(0, 200);
|
||||
const unavailable = (input: string, detail: string): RegistryInfo => ({ sha: null, outputs: [], error: { code: 'registry_unavailable', detail: oneLine(detail), input, repair: 'fetch the base branch (git fetch origin <base>) so its commit and registry resolve' } });
|
||||
|
||||
/** The registry as committed at `sha`: outputs of entries with a command (a `command: null` entry never excludes); a missing file is an empty registry. */
|
||||
export function loadRegistryAt(root: string, sha: string): RegistryInfo {
|
||||
const commit = git(root, ['rev-parse', '--verify', '--quiet', `${sha}^{commit}`]);
|
||||
if (!commit.ok) return unavailable(`${sha}:${GENERATED_PATH}`, `${sha} is not a commit in this repository`);
|
||||
const resolved = commit.out.trim();
|
||||
const input = `${resolved.slice(0, 12)}:${GENERATED_PATH}`;
|
||||
if (!git(root, ['cat-file', '-e', `${resolved}:${GENERATED_PATH}`]).ok) return { sha: resolved, outputs: [] };
|
||||
const show = git(root, ['show', `${resolved}:${GENERATED_PATH}`]);
|
||||
if (!show.ok) return unavailable(input, show.err || 'git show failed');
|
||||
const { registry, errors } = parseRegistry(show.out);
|
||||
const e = errors[0];
|
||||
if (e) return { sha: resolved, outputs: [], error: { code: 'registry_invalid', detail: oneLine(`${e.path || GENERATED_PATH}: ${e.message}`), input, repair: RESULT_CODES[e.code].fix, result: e.code } };
|
||||
return { sha: resolved, outputs: registry.entries.filter(x => x.command !== null).flatMap(x => x.outputs) };
|
||||
}
|
||||
|
||||
/** Numstat, deletions and the -U0 patch for `range` (`[mergeBase, head]` or `[mergeBase]` for the working tree). */
|
||||
function readDiff(root: string, range: string[], errors: DepthError[]): Pick<Collected, 'perPath' | 'deleted' | 'stampOnly' | 'added'> {
|
||||
const numstat = git(root, ['diff', '--numstat', '-z', '--no-renames', ...range]);
|
||||
const status = git(root, ['diff', '--name-status', '-z', '--no-renames', '--diff-filter=D', ...range]);
|
||||
const patch = git(root, ['diff', '-U0', '--no-color', '--no-ext-diff', '--no-renames', ...range]);
|
||||
const empty = { perPath: [], deleted: [], stampOnly: [], added: {} };
|
||||
for (const [r, what] of [[numstat, '--numstat'], [status, '--name-status'], [patch, '-U0']] as const) {
|
||||
if (!r.ok) { errors.push({ code: 'numstat_failed', detail: oneLine(r.err || 'git diff failed'), input: `git diff ${what} ${range.join(' ')}`, repair: 'check that both commits exist locally (git fetch origin <base>) and rerun' }); return empty; }
|
||||
}
|
||||
const perPath: PathLines[] = [];
|
||||
for (const rec of numstat.out.split('\0').filter(Boolean)) {
|
||||
const [a, d, ...rest] = rec.split('\t');
|
||||
const p = rest.join('\t');
|
||||
if (!scratch(p)) perPath.push({ path: p, lines: (Number(a) || 0) + (Number(d) || 0), binary: a === '-' && d === '-' });
|
||||
}
|
||||
const statusParts = status.out.split('\0');
|
||||
const deleted = statusParts.flatMap((s, k) => (s === 'D' && statusParts[k + 1] ? [statusParts[k + 1]!] : [])).filter(p => !scratch(p));
|
||||
const added: Record<string, string[]> = {};
|
||||
const changed: Record<string, string[]> = {};
|
||||
let cur = '';
|
||||
let minus = '';
|
||||
let inHunk = false;
|
||||
for (const line of patch.out.split('\n')) {
|
||||
if (line.startsWith('diff --git ')) { inHunk = false; cur = ''; minus = ''; continue; }
|
||||
if (!inHunk) {
|
||||
if (line.startsWith('--- ')) minus = line === '--- /dev/null' ? '' : line.slice(6).replace(/\t$/, '');
|
||||
else if (line.startsWith('+++ ')) cur = line === '+++ /dev/null' ? minus : line.slice(6).replace(/\t$/, '');
|
||||
else if (line.startsWith('@@')) inHunk = true;
|
||||
continue;
|
||||
}
|
||||
if (!cur || scratch(cur) || line.startsWith('@@')) continue;
|
||||
if (line[0] === '+') (added[cur] ??= []).push(line.slice(1));
|
||||
if (line[0] === '+' || line[0] === '-') (changed[cur] ??= []).push(line);
|
||||
}
|
||||
const stampOnly = perPath.map(e => e.path).filter(p => p.endsWith('package.json') && !!changed[p]?.length && changed[p]!.every(l => /^[+-]\s*"version"\s*:\s*"[^"]*"\s*,?\s*$/.test(l)));
|
||||
return { perPath, deleted, stampOnly, added };
|
||||
}
|
||||
|
||||
function result(diff: ReturnType<typeof readDiff>, extra: Pick<Collected, 'root' | 'registry' | 'errors' | 'mergeBase' | 'untracked'>): Collected {
|
||||
const paths = diff.perPath.map(e => e.path).sort();
|
||||
return { ...diff, ...extra, paths, gateTagged: null, diffLines: diff.perPath.reduce((n, e) => n + e.lines, 0) };
|
||||
}
|
||||
|
||||
/** The range `baseSha`...`headSha` from git objects alone; the registry is the base commit's, never the head's. */
|
||||
export function collectCommit(root: string, baseSha: string, headSha: string): Collected {
|
||||
const errors: DepthError[] = [];
|
||||
const registry = loadRegistryAt(root, baseSha);
|
||||
const mb = git(root, ['merge-base', baseSha, headSha]);
|
||||
if (!mb.ok) {
|
||||
errors.push({ code: 'numstat_failed', detail: oneLine(mb.err || 'no merge base'), input: `git merge-base ${baseSha} ${headSha}`, repair: 'check that both commits exist locally (git fetch origin <base>) and rerun' });
|
||||
return result({ perPath: [], deleted: [], stampOnly: [], added: {} }, { root: [], registry, errors, mergeBase: null, untracked: [] });
|
||||
}
|
||||
const mergeBase = mb.out.trim();
|
||||
const diff = readDiff(root, [mergeBase, headSha], errors);
|
||||
const tree = git(root, ['ls-tree', '-r', '--name-only', '-z', headSha]);
|
||||
const skillDirs = [...new Set(tree.out.split('\0').flatMap(p => /^([^/]+)\/SKILL\.md(\.tmpl)?$/.exec(p)?.[1] ?? []))].sort();
|
||||
return result(diff, { root: skillDirs, registry, errors, mergeBase, untracked: [] });
|
||||
}
|
||||
|
||||
/** The working tree against the merge base with origin/<base> (or <base>), 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 ref = git(root, ['rev-parse', '--verify', '-q', `origin/${base}^{commit}`]).ok ? `origin/${base}` : 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: [], added: {} }, { root, registry, errors, mergeBase: null, untracked: [] });
|
||||
}
|
||||
const mergeBase = mb.out.trim();
|
||||
const diff = readDiff(root, [mergeBase], errors);
|
||||
const others = git(root, ['ls-files', '--others', '--exclude-standard', '-z']);
|
||||
if (!others.ok) errors.push({ code: 'numstat_failed', detail: oneLine(others.err || 'git ls-files failed'), input: 'git ls-files --others --exclude-standard', repair: 'run the command by hand and fix what git reports' });
|
||||
const untracked = others.out.split('\0').filter(p => p && !scratch(p)).sort();
|
||||
for (const p of untracked) {
|
||||
let buf: Buffer;
|
||||
try { buf = fs.readFileSync(path.join(root, p)); } catch { diff.perPath.push({ path: p, lines: 0, binary: true }); continue; }
|
||||
const binary = buf.subarray(0, 8000).includes(0);
|
||||
const text = binary ? '' : buf.toString('utf8');
|
||||
const lines = text ? text.split('\n').length - (text.endsWith('\n') ? 1 : 0) : 0;
|
||||
diff.perPath.push({ path: p, lines, binary });
|
||||
if (!binary) diff.added[p] = text.split('\n');
|
||||
}
|
||||
return result(diff, { root, registry, errors, mergeBase, untracked });
|
||||
}
|
||||
+176
-43
@@ -1,17 +1,22 @@
|
||||
/**
|
||||
* review-depth — the one policy owner for how much review a /ship run dispatches
|
||||
* (docs/review-policy.md#review-depth). A pure function from the changed paths,
|
||||
* gstack-diff-scope flags, the diff size, the gate scan and the pass history to a
|
||||
* diff class, the next step of the loop and the reviewers that step dispatches,
|
||||
* each with its reasoning-effort tier. bin/gstack-review-plan prints it; the
|
||||
* (docs/review-policy.md#review-depth). A pure function from the changed paths and
|
||||
* their line counts, gstack-diff-scope flags, the base registry's generated outputs,
|
||||
* the gate scan and the pass history to a diff class, a review depth (light,
|
||||
* standard, full), the next step of the loop and the reviewers that step
|
||||
* dispatches, each with its effort tier and the pathspecs it leaves out. Git reads
|
||||
* live in lib/review-collect.ts; bin/gstack-review-plan prints the plan; the
|
||||
* review-army resolver and the skills read the same definitions.
|
||||
*/
|
||||
import { createHash } from 'node:crypto';
|
||||
import * as fs from 'node:fs';
|
||||
import * as path from 'node:path';
|
||||
import type { ResultCodeName } from './result-codes';
|
||||
import { matchesAny } from './ship-policy';
|
||||
|
||||
export type DiffClass = 'docs' | 'tests' | 'code' | 'gate';
|
||||
export type PathClass = 'docs' | 'tests' | 'code';
|
||||
export type Depth = 'light' | 'standard' | 'full';
|
||||
export type Effort = 'light' | 'full' | 'host';
|
||||
export type Role = 'specialist' | 'red-team' | 'adversarial-native' | 'outside-voice' | 'fix-check';
|
||||
export type Step = 'full' | 'fix-check' | 'done' | 'stop';
|
||||
@@ -22,7 +27,12 @@ export const FULL_PASS_CAP = 2;
|
||||
export const SMALL_DIFF_LINES = 50;
|
||||
export const RED_TEAM_LINES = 200;
|
||||
export const LARGE_DIFF_LINES = 100;
|
||||
/** The checklists light's batched specialist always reads, whatever the scope. */
|
||||
export const LIGHT_FIXED: readonly Specialist[] = ['testing', 'maintainability', 'security'];
|
||||
/** Why light with runtime above 0 keeps the native adversarial pass as its own dispatch. */
|
||||
export const LIGHT_ADVERSARIAL_REASON = 'backtest inconclusive (GSTA-147 D5)';
|
||||
const CLASS_RANK: Record<DiffClass, number> = { docs: 0, tests: 1, code: 2, gate: 3 };
|
||||
const DEPTH_RANK: Record<Depth, number> = { light: 0, standard: 1, full: 2 };
|
||||
|
||||
const AGENT_PROSE = [/(^|\/)SKILL\.md(\.tmpl)?$/, /(^|\/)sections\//, /^scripts\/resolvers\//, /^docs\/[^/]*-policy\.md$/, /^docs\/(captain|unattended|pregate)\.md$/, /(^|\/)DRIVER\.md(\.tmpl)?$/, /(^|\/)templates\//, /(^|\/)(AGENTS|CLAUDE|ETHOS)\.md$/, /(^|\/)specialists\//, /(^|\/)checklist\.md$/, /^\.gstack\//];
|
||||
/** gstack-diff-scope's TEST_PATH_RE (the test-bootstrap rule), plus fixture directories. */
|
||||
@@ -30,19 +40,41 @@ const TEST_PATH = [/(^|\/)(tests?|spec|__tests__)\/|(^|\/)tests?\.py$|(^|\/)test
|
||||
const DOC_PATH = /\.(md|mdx|markdown|rst|txt|adoc)$/i;
|
||||
/** Release metadata a version stamp writes: never a reason for review depth on its own. */
|
||||
const RELEASE_METADATA = [/^CHANGELOG\.md$/, /^VERSION$/, /^agents-digest\//];
|
||||
const GATE_PATH = [/(^|\/)\.github\/workflows\//, /(^|\/)(secrets?|credentials?|keychain|token[s]?)([._/-]|$)/i, /state-root/, /(^|\/)(pregate|gate|ship-receipt|ship-policy)[^/]*\.(ts|sh|json)$/, /(^|\/)bin\/gstack-(pregate|gate|ship-receipt|verify-gate|ci-gate)$/];
|
||||
/** Gate paths, the review-depth machinery included: an edit to how much review runs gets the most review. */
|
||||
const GATE_PATH = [
|
||||
/(^|\/)\.github\/workflows\//, /(^|\/)(secrets?|credentials?|keychain|token[s]?)([._/-]|$)/i, /state-root/, /(^|\/)(pregate|gate|ship-receipt|ship-policy)[^/]*\.(ts|sh|json)$/, /(^|\/)bin\/gstack-(pregate|gate|ship-receipt|verify-gate|ci-gate)$/,
|
||||
/^lib\/review-(depth|collect|scope)\.ts$/, /^bin\/gstack-review-plan$/, /^lib\/ship-queue[^/]*\.ts$/, /^lib\/regen\.ts$/, /^\.gstack\/generated\.json$/, /^ship\/sections\/(review-army|adversarial)\.md\.tmpl$/, /^scripts\/resolvers\/review-army\.ts$/,
|
||||
];
|
||||
|
||||
/** One changed path's class. Markdown an agent or a gate reads (skills, sections, resolvers, policy and rule docs, templates, any markdown in a skill directory under `root`) is code: it is gstack's product. */
|
||||
export function classifyPath(p: string, root?: string): PathClass {
|
||||
/** 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({
|
||||
SMALL_DIFF_LINES, RED_TEAM_LINES, LARGE_DIFF_LINES, FULL_PASS_CAP, LIGHT_FIXED,
|
||||
patterns: Object.entries({ GATE_PATH, AGENT_PROSE, TEST_PATH, RELEASE_METADATA, DOC_PATH: [DOC_PATH] }).map(([k, v]) => [k, v.map(r => `/${r.source}/${r.flags}`)]),
|
||||
})).digest('hex').slice(0, 16);
|
||||
|
||||
/**
|
||||
* One changed path's class. Markdown an agent or a gate reads (skills, sections, resolvers, policy and rule docs,
|
||||
* templates, any markdown in a skill directory) is code: it is gstack's product. `root` is the repository root
|
||||
* (skill directories probed on disk) or the top-level skill directory names read from a commit.
|
||||
*/
|
||||
export function classifyPath(p: string, root?: string | readonly string[]): PathClass {
|
||||
if (RELEASE_METADATA.some(r => r.test(p))) return 'docs';
|
||||
if (AGENT_PROSE.some(r => r.test(p))) return 'code';
|
||||
if (TEST_PATH.some(r => r.test(p))) return 'tests';
|
||||
if (!DOC_PATH.test(p)) return 'code';
|
||||
const top = p.includes('/') ? p.split('/')[0]! : '';
|
||||
if (root && top && ['SKILL.md', 'SKILL.md.tmpl'].some(f => fs.existsSync(path.join(root, top, f)))) return 'code';
|
||||
return 'docs';
|
||||
if (!top || !root) return 'docs';
|
||||
if (typeof root === 'string') return ['SKILL.md', 'SKILL.md.tmpl'].some(f => fs.existsSync(path.join(root, top, f))) ? 'code' : 'docs';
|
||||
return root.includes(top) ? 'code' : 'docs';
|
||||
}
|
||||
|
||||
export type DepthErrorCode = 'scope_error' | 'gate_scan_unavailable' | 'registry_unavailable' | 'registry_invalid' | 'numstat_failed' | 'binary_code_path';
|
||||
/** Why a depth failed closed to full: the input it could not read, a sanitized cause and the repair; `result` is the result code behind it when one exists. */
|
||||
export interface DepthError { code: DepthErrorCode; detail: string; input: string; repair: string; result?: ResultCodeName }
|
||||
export interface PathLines { path: string; lines: number; binary: boolean }
|
||||
/** The base commit's `.gstack/generated.json`: outputs of entries with a command only; `error` when it could not be read or validated. */
|
||||
export interface RegistryInfo { sha: string | null; outputs: readonly string[]; error?: DepthError }
|
||||
|
||||
export interface ClassInput {
|
||||
paths: readonly string[];
|
||||
/** gstack-diff-scope output (SCOPE_* keys). */
|
||||
@@ -53,23 +85,38 @@ export interface ClassInput {
|
||||
deleted?: readonly string[];
|
||||
/** Paths whose whole change is a version stamp (package.json's version key): classified as docs. */
|
||||
stampOnly?: readonly string[];
|
||||
/** The repository root: markdown inside a skill directory there is code. */
|
||||
root?: string;
|
||||
/** The repository root, or the skill directory names at the reviewed commit: markdown inside a skill directory is code. */
|
||||
root?: string | readonly string[];
|
||||
/** Changed lines per path; without it a code diff counts every line as runtime. */
|
||||
perPath?: readonly PathLines[];
|
||||
registry?: RegistryInfo;
|
||||
/** Collector failures (a diff git could not list): each fails the depth closed. */
|
||||
errors?: readonly DepthError[];
|
||||
}
|
||||
export interface ClassResult { class: DiffClass; reasons: string[] }
|
||||
export interface ClassResult { class: DiffClass; reasons: string[]; errors: DepthError[]; runtimeLines: number | null }
|
||||
|
||||
/** The diff's class: the most restrictive of its paths, raised to gate by any gate signal; errors fail closed. */
|
||||
const sanitize = (s: string) => s.replace(/[\0-\x1f]+/g, ' ').slice(0, 200);
|
||||
const isOutput = (i: ClassInput, p: string) => !!i.registry?.outputs.length && matchesAny(i.registry.outputs, p);
|
||||
const pathClass = (i: ClassInput, p: string): PathClass => ((i.stampOnly ?? []).includes(p) ? 'docs' : classifyPath(p, i.root));
|
||||
|
||||
/** The diff's class, raised to gate by any gate signal; `errors` lists every input that fails the depth closed; `runtimeLines` counts code-class lines outside the base registry's outputs. */
|
||||
export function classifyDiff(i: ClassInput): ClassResult {
|
||||
const reasons: string[] = [];
|
||||
const errors: DepthError[] = [...(i.errors ?? [])];
|
||||
let cls: DiffClass = 'docs';
|
||||
const raise = (c: DiffClass, why: string) => { if (CLASS_RANK[c] > CLASS_RANK[cls]) cls = c; reasons.push(why); };
|
||||
if (!i.paths.length) raise('docs', 'no changed paths');
|
||||
for (const p of i.paths) { const c = (i.stampOnly ?? []).includes(p) ? 'docs' : classifyPath(p, i.root); if (CLASS_RANK[c] > CLASS_RANK[cls]) raise(c, `${c}: ${p}`); }
|
||||
for (const p of i.paths) { const c = pathClass(i, p); if (CLASS_RANK[c] > CLASS_RANK[cls]) raise(c, `${c}: ${p}`); }
|
||||
const s = i.scope ?? {};
|
||||
if (s.SCOPE_ERROR) raise('code', `scope error: ${s.SCOPE_ERROR}`);
|
||||
if (s.SCOPE_ERROR) {
|
||||
raise('code', `scope error: ${s.SCOPE_ERROR}`);
|
||||
errors.push({ code: 'scope_error', detail: sanitize(s.SCOPE_ERROR), input: 'gstack-diff-scope <base>', repair: 'run gstack-diff-scope <base> by hand and fix what it reports' });
|
||||
}
|
||||
if (CLASS_RANK[cls] >= CLASS_RANK.tests) {
|
||||
if (i.gateTagged === null) raise('gate', 'gate scan unavailable');
|
||||
else if (i.gateTagged > 0) raise('gate', `gate scan tagged ${i.gateTagged} hunk(s)`);
|
||||
if (i.gateTagged === null) {
|
||||
raise('gate', 'gate scan unavailable');
|
||||
errors.push({ code: 'gate_scan_unavailable', detail: 'gstack-gate-diff reported no GATE_SUMMARY', input: 'gstack-gate-diff <base>', repair: 'run gstack-gate-diff <base> and read its GATE_ERROR line, or pass the recorded scan as --gate-tagged <n>' });
|
||||
} else if (i.gateTagged > 0) raise('gate', `gate scan tagged ${i.gateTagged} hunk(s)`);
|
||||
const deletedGuarded = (i.deleted ?? []).filter(p => classifyPath(p, i.root) !== 'docs');
|
||||
if (deletedGuarded.length) raise('gate', `deletes ${deletedGuarded.length} code or test path(s)`);
|
||||
}
|
||||
@@ -77,8 +124,38 @@ export function classifyDiff(i: ClassInput): ClassResult {
|
||||
if (s.SCOPE_AUTH === 'true') raise('gate', 'auth paths');
|
||||
if (s.SCOPE_MIGRATIONS === 'true') raise('gate', 'migrations');
|
||||
for (const p of i.paths) if (GATE_PATH.some(r => r.test(p))) { raise('gate', `gate path: ${p}`); break; }
|
||||
if (i.registry?.error) errors.push(i.registry.error);
|
||||
}
|
||||
return { class: cls, reasons };
|
||||
if (!i.perPath) return { class: cls, reasons, errors, runtimeLines: null };
|
||||
let runtimeLines = 0;
|
||||
for (const e of i.perPath) {
|
||||
if (pathClass(i, e.path) !== 'code' || isOutput(i, e.path)) continue;
|
||||
if (e.binary) errors.push({ code: 'binary_code_path', detail: 'git reports a binary change, so its lines cannot be counted', input: e.path, repair: "register it as an output of an entry with a command in the base branch's .gstack/generated.json, or accept the full review" });
|
||||
else runtimeLines += e.lines;
|
||||
}
|
||||
return { class: cls, reasons, errors, runtimeLines };
|
||||
}
|
||||
|
||||
/** Any classifier error or gate class is full; runtime above SMALL_DIFF_LINES is standard; otherwise light. A floor only raises. */
|
||||
export function depthFor(o: { cls: DiffClass; runtimeLines: number; errors: readonly DepthError[]; floor?: Depth }): Depth {
|
||||
const d: Depth = o.errors.length || o.cls === 'gate' ? 'full' : o.runtimeLines > SMALL_DIFF_LINES ? 'standard' : 'light';
|
||||
return o.floor && DEPTH_RANK[o.floor] > DEPTH_RANK[d] ? o.floor : d;
|
||||
}
|
||||
|
||||
export interface DepthResult { depth: Depth; class: DiffClass; runtimeLines: number; reasons: string[]; errors: DepthError[]; codes: ResultCodeName[]; rules: string }
|
||||
|
||||
function decideDepth(c: ClassResult, runtimeLines: number, floor?: Depth): DepthResult {
|
||||
const unfloored = depthFor({ cls: c.class, runtimeLines, errors: c.errors });
|
||||
const reasons = [...c.errors.map(e => `error:${e.code}`), ...(c.class === 'gate' ? ['gate-class'] : []), `runtime=${runtimeLines}${runtimeLines > SMALL_DIFF_LINES ? '>' : '<='}${SMALL_DIFF_LINES}`];
|
||||
if (floor && DEPTH_RANK[floor] > DEPTH_RANK[unfloored]) reasons.push(`floor:${floor}`);
|
||||
const codes = [...new Set(c.errors.flatMap(e => (e.result ? [e.result] : [])))];
|
||||
return { depth: depthFor({ cls: c.class, runtimeLines, errors: c.errors, floor }), class: c.class, runtimeLines, reasons, errors: c.errors, codes, rules: DEPTH_RULES };
|
||||
}
|
||||
|
||||
/** The depth of a collected range (lib/review-collect.ts) plus a recorded gate-scan result: what the queue recomputes at a head. */
|
||||
export function depthOfCommitInput(input: ClassInput & { floor?: Depth }): DepthResult {
|
||||
const c = classifyDiff(input);
|
||||
return decideDepth(c, c.runtimeLines ?? 0, input.floor);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -153,34 +230,48 @@ export interface PlanInput extends ClassInput {
|
||||
force?: readonly string[] | 'all';
|
||||
/** Specialists the hit-rate stats tag GATE_CANDIDATE. */
|
||||
gated?: readonly string[];
|
||||
/** A specialist produced a CRITICAL finding (Red Team activation on code class). */
|
||||
/** A specialist produced a CRITICAL finding (Red Team activation on code class; raises light to standard). */
|
||||
criticalFound?: boolean;
|
||||
/** Step 11's native adversarial pass already ran in this invocation. */
|
||||
adversarialRan?: boolean;
|
||||
/** The numeric-claim fingerprint the outside voice last reviewed; a change reruns it. */
|
||||
reviewedNumbers?: string;
|
||||
/** --depth-floor: raises the depth, never lowers it. */
|
||||
floor?: Depth;
|
||||
}
|
||||
export interface Dispatch { role: Role; name: string; effort: Effort }
|
||||
export interface ReviewPlan { class: DiffClass; reasons: string[]; next: NextStep; numbers: NumbersResult; dispatches: Dispatch[]; skipped: string[] }
|
||||
/** One reviewer. `exclude` holds git pathspec argv items the reviewer's diff leaves out; `checklists` names what light's batched specialist reads. */
|
||||
export interface Dispatch { role: Role; name: string; effort: Effort; exclude: string[]; checklists?: string[]; reason?: string }
|
||||
export interface ReviewPlan extends DepthResult {
|
||||
/** The depth this step runs at: light raised to standard by a fixed blocker, a CRITICAL or an open blocker. */
|
||||
stepDepth: Depth;
|
||||
depthReasons: string[];
|
||||
next: NextStep; numbers: NumbersResult; dispatches: Dispatch[]; skipped: string[];
|
||||
}
|
||||
|
||||
const scopeWants: Partial<Record<Specialist, (s: Record<string, string>) => boolean>> = {
|
||||
performance: s => s.SCOPE_BACKEND === 'true' || s.SCOPE_FRONTEND === 'true',
|
||||
'data-migration': s => s.SCOPE_MIGRATIONS === 'true',
|
||||
'api-contract': s => s.SCOPE_API === 'true',
|
||||
design: s => s.SCOPE_FRONTEND === 'true',
|
||||
'state-machines': s => s.SCOPE_STATE_MACHINE === 'true' || s.SCOPE_STATE_MACHINE === 'unknown' || s.SCOPE_STATE_MACHINE === undefined,
|
||||
};
|
||||
const forcedBy = (i: PlanInput) => (n: string) => i.force === 'all' || (Array.isArray(i.force) && i.force.includes(n));
|
||||
|
||||
/** The specialists a full pass selects for a class: class sets the eligible set, hit-rate gating applies inside it, gate class ignores gating. */
|
||||
export function specialistsFor(cls: DiffClass, i: PlanInput, skipped: string[] = []): Specialist[] {
|
||||
const s = i.scope ?? {};
|
||||
const forced = (n: string) => i.force === 'all' || (Array.isArray(i.force) && i.force.includes(n));
|
||||
const forced = forcedBy(i);
|
||||
if (cls === 'docs') { skipped.push('specialists (docs class)'); return SPECIALISTS.filter(forced); }
|
||||
if (cls === 'tests') { skipped.push('specialists except testing (tests class)'); return SPECIALISTS.filter(n => n === 'testing' || forced(n)); }
|
||||
const want = (n: Specialist): boolean => {
|
||||
if (forced(n)) return true;
|
||||
if (n === 'state-machines') return s.SCOPE_STATE_MACHINE === 'true' || s.SCOPE_STATE_MACHINE === 'unknown' || s.SCOPE_STATE_MACHINE === undefined;
|
||||
if (n === 'state-machines') return scopeWants[n]!(s);
|
||||
if (i.diffLines < SMALL_DIFF_LINES) return false;
|
||||
switch (n) {
|
||||
case 'testing': case 'maintainability': return true;
|
||||
case 'security': return s.SCOPE_AUTH === 'true' || (s.SCOPE_BACKEND === 'true' && i.diffLines > LARGE_DIFF_LINES);
|
||||
case 'performance': return s.SCOPE_BACKEND === 'true' || s.SCOPE_FRONTEND === 'true';
|
||||
case 'data-migration': return s.SCOPE_MIGRATIONS === 'true';
|
||||
case 'api-contract': return s.SCOPE_API === 'true';
|
||||
case 'design': return s.SCOPE_FRONTEND === 'true';
|
||||
case 'simplification': return i.diffLines > LARGE_DIFF_LINES;
|
||||
default: return scopeWants[n]!(s);
|
||||
}
|
||||
};
|
||||
return SPECIALISTS.filter(n => {
|
||||
@@ -190,34 +281,76 @@ export function specialistsFor(cls: DiffClass, i: PlanInput, skipped: string[] =
|
||||
});
|
||||
}
|
||||
|
||||
/** The reviewers the next step dispatches, with each role's effort tier. */
|
||||
/** A path as one git exclude pathspec; a glob character or a leading colon makes it literal. */
|
||||
const excludeSpec = (p: string) => `:(exclude${/[*?[\]\\]/.test(p) || p.startsWith(':') ? ',literal' : ''})${p}`;
|
||||
const shellQuote = (s: string) => `'${s.replace(/'/g, "'\\''")}'`;
|
||||
|
||||
/** The diff command a dispatched reviewer runs; `<diff-base>` is the literal sha the parent writes in. */
|
||||
export function diffCommand(d: Dispatch): string {
|
||||
return d.exclude.length ? `git diff <diff-base> -- . ${d.exclude.map(shellQuote).join(' ')}` : 'git diff <diff-base>';
|
||||
}
|
||||
|
||||
/** The reviewers the next step dispatches at its depth, with each role's effort tier and excluded pathspecs. */
|
||||
export function planReview(i: PlanInput): ReviewPlan {
|
||||
const { class: cls, reasons } = classifyDiff(i);
|
||||
const c = classifyDiff(i);
|
||||
const depth = decideDepth(c, c.runtimeLines ?? (CLASS_RANK[c.class] >= CLASS_RANK.code ? i.diffLines : 0), i.floor);
|
||||
const { class: cls, runtimeLines } = depth;
|
||||
const next = nextStep(i.history);
|
||||
const h = i.history;
|
||||
const raise = depth.depth === 'light' && (h.fixedBlocking || h.blockingOpen || i.criticalFound);
|
||||
const stepDepth: Depth = raise ? 'standard' : depth.depth;
|
||||
const depthReasons = [...depth.reasons, ...(raise ? [`history:${h.fixedBlocking ? 'fixed-blocking' : h.blockingOpen ? 'blocking-open' : 'critical-found'}`] : [])];
|
||||
const skipped: string[] = [];
|
||||
const dispatches: Dispatch[] = [];
|
||||
const add = (role: Role, name: string, effort: Effort, exclude: string[] = [], extra: Partial<Dispatch> = {}) => dispatches.push({ role, name, effort, exclude, ...extra });
|
||||
const docsAndOutputs = i.paths.filter(p => pathClass(i, p) === 'docs' || isOutput(i, p)).map(excludeSpec);
|
||||
const tests = i.paths.filter(p => pathClass(i, p) === 'tests' && !isOutput(i, p)).map(excludeSpec);
|
||||
const numbersChanged = i.numbers.publishes && i.reviewedNumbers !== undefined && i.reviewedNumbers !== i.numbers.fingerprint;
|
||||
if (next.step === 'full') {
|
||||
for (const n of specialistsFor(cls, i, skipped)) dispatches.push({ role: 'specialist', name: n, effort: 'full' });
|
||||
const redTeam = cls === 'gate' || (cls === 'code' && (i.diffLines > RED_TEAM_LINES || !!i.criticalFound));
|
||||
if (redTeam) dispatches.push({ role: 'red-team', name: 'red-team', effort: 'full' });
|
||||
else skipped.push(`red-team (${cls} class${cls === 'code' ? `, ${i.diffLines} lines, no critical` : ''})`);
|
||||
if (i.history.fullPasses === 0 || (!i.adversarialRan && (cls === 'code' || cls === 'gate'))) {
|
||||
if (cls === 'docs' || cls === 'tests') skipped.push(`adversarial-native (${cls} class)`);
|
||||
else dispatches.push({ role: 'adversarial-native', name: 'adversarial', effort: 'full' });
|
||||
if (cls === 'code' || cls === 'gate' || i.numbers.publishes) dispatches.push({ role: 'outside-voice', name: 'outside-voice', effort: 'host' });
|
||||
else skipped.push(`outside-voice (${cls} class, no numeric claims)`);
|
||||
const firstVoices = h.fullPasses === 0 || !i.adversarialRan;
|
||||
if (next.step === 'full' && stepDepth === 'light') {
|
||||
const forced = forcedBy(i);
|
||||
if (runtimeLines > 0) {
|
||||
const scoped = SPECIALISTS.filter(n => !LIGHT_FIXED.includes(n) && (forced(n) || (scopeWants[n]?.(i.scope ?? {}) && !(i.gated ?? []).includes(n))));
|
||||
add('specialist', 'batched', 'full', docsAndOutputs, { checklists: [...LIGHT_FIXED, ...scoped, 'red-team'] });
|
||||
skipped.push('red-team (light depth: the batched specialist carries the Red Team prompt)');
|
||||
if (firstVoices) add('adversarial-native', 'adversarial', 'full', [], { reason: LIGHT_ADVERSARIAL_REASON });
|
||||
} else {
|
||||
for (const n of SPECIALISTS.filter(forced)) add('specialist', n, 'full');
|
||||
skipped.push('specialists, red-team and adversarial-native (light depth, runtime 0)');
|
||||
}
|
||||
if (h.fullPasses === 0 && i.numbers.publishes) add('outside-voice', 'outside-voice', 'host');
|
||||
else if (numbersChanged) add('outside-voice', 'outside-voice (numbers changed)', 'host');
|
||||
else skipped.push(`outside-voice (${cls} class, no numeric claims)`);
|
||||
} else if (next.step === 'full') {
|
||||
const full = stepDepth === 'full';
|
||||
const dcls: DiffClass = full ? 'gate' : cls;
|
||||
const raised = !full && runtimeLines <= SMALL_DIFF_LINES;
|
||||
const lines = full ? i.diffLines : Math.max(runtimeLines, raised ? SMALL_DIFF_LINES : 0);
|
||||
for (const n of specialistsFor(dcls, { ...i, diffLines: lines }, skipped)) add('specialist', n, 'full', full ? [] : n === 'testing' ? docsAndOutputs : [...docsAndOutputs, ...tests]);
|
||||
const redTeam = dcls === 'gate' || (dcls === 'code' && (lines > RED_TEAM_LINES || !!i.criticalFound || raised));
|
||||
if (redTeam) add('red-team', 'red-team', 'full');
|
||||
else skipped.push(`red-team (${dcls} class${dcls === 'code' ? `, ${lines} runtime lines, no critical` : ''})`);
|
||||
const codeLike = dcls === 'code' || dcls === 'gate';
|
||||
if (h.fullPasses === 0 || (!i.adversarialRan && codeLike)) {
|
||||
if (codeLike) add('adversarial-native', 'adversarial', 'full');
|
||||
else skipped.push(`adversarial-native (${dcls} class)`);
|
||||
if (codeLike || i.numbers.publishes) add('outside-voice', 'outside-voice', 'host');
|
||||
else skipped.push(`outside-voice (${dcls} class, no numeric claims)`);
|
||||
} else {
|
||||
skipped.push('adversarial-native and outside-voice (run once per invocation)');
|
||||
if (numbersChanged) dispatches.push({ role: 'outside-voice', name: 'outside-voice (numbers changed)', effort: 'host' });
|
||||
if (numbersChanged) add('outside-voice', 'outside-voice (numbers changed)', 'host');
|
||||
}
|
||||
} else if (next.step === 'fix-check') {
|
||||
dispatches.push({ role: 'fix-check', name: 'fix-check', effort: 'full' });
|
||||
if (numbersChanged) dispatches.push({ role: 'outside-voice', name: 'outside-voice (numbers changed)', effort: 'host' });
|
||||
add('fix-check', 'fix-check', 'full');
|
||||
if (numbersChanged) add('outside-voice', 'outside-voice (numbers changed)', 'host');
|
||||
}
|
||||
return { class: cls, reasons, next, numbers: i.numbers, dispatches, skipped };
|
||||
return { ...depth, stepDepth, depthReasons, reasons: c.reasons, next, numbers: i.numbers, dispatches, skipped };
|
||||
}
|
||||
|
||||
export function reviewPlanLine(p: ReviewPlan, pass: number): string {
|
||||
return `REVIEW_PLAN: class=${p.class} pass=${pass} next=${p.next.step} dispatches=${p.dispatches.length} numbers=${p.numbers.publishes ? `yes(${p.numbers.claims})` : 'no'} fingerprint=${p.numbers.fingerprint}`;
|
||||
}
|
||||
|
||||
export function reviewDepthLine(p: ReviewPlan): string {
|
||||
return `REVIEW_DEPTH: ${p.depth} runtime_lines=${p.runtimeLines} rules=${p.rules} reasons=${p.depthReasons.join(',')} codes=${p.codes.join(',') || 'none'}${p.stepDepth !== p.depth ? ` step=${p.stepDepth}` : ''}`;
|
||||
}
|
||||
+44
-18
@@ -9,6 +9,8 @@
|
||||
* answer_markers regexes for a quoted sealed answer in added text
|
||||
* seed_patterns regexes for a sampling seed in added text
|
||||
* local_paths true: a local home path (/home/<u>/, /Users/<u>/) in added text
|
||||
* allow_paths globs exempt from the path rules (read from the base branch only; never folds case)
|
||||
* case_insensitive true: `paths` and `transcripts` match regardless of case
|
||||
* visibility "public" | "private": the destination override (reviewed on the base branch)
|
||||
*
|
||||
* The publication boundary is every commit the push publishes: the local sha
|
||||
@@ -18,8 +20,9 @@
|
||||
* copies, independent of content (binary, empty, add-then-delete); text rules
|
||||
* see each commit's added lines. The effective policy is the union of the
|
||||
* destination base branch's `sealed` and the pushed one (a push can tighten,
|
||||
* never relax); waivers come only from the base branch's
|
||||
* `.gstack/sealed-allow.tsv`. A malformed or unreadable policy refuses (fail
|
||||
* never relax); `allow_paths` exceptions come only from the base branch's
|
||||
* policy and remove path findings before waivers, which come only from the
|
||||
* base branch's `.gstack/sealed-allow.tsv`. A malformed or unreadable policy refuses (fail
|
||||
* closed). Visibility: the base override, else a cache under the state root
|
||||
* (a `public` answer for 24 h, a `private` one for 1 h before it may
|
||||
* downgrade a refusal), else `gh repo view` (5 s); unknown counts as public.
|
||||
@@ -28,19 +31,20 @@
|
||||
import { spawnSync } from 'node:child_process';
|
||||
import * as fs from 'node:fs';
|
||||
import * as path from 'node:path';
|
||||
import { containedRelative, globToRegExp, matchesAny } from './ship-policy';
|
||||
import { containedRelative, globToRegExp } from './ship-policy';
|
||||
import { resolveStateRoot } from './state-root';
|
||||
|
||||
export const SEALED_CONFIG_PATH = '.gstack/pregate.json';
|
||||
export const SEALED_ALLOW_PATH = '.gstack/sealed-allow.tsv';
|
||||
export const VISIBILITY_OVERRIDE_KEY = 'sealed.visibility';
|
||||
export type SealedRule = 'sealed.path' | 'sealed.transcript' | 'sealed.answer' | 'sealed.seed' | 'sealed.local_path';
|
||||
export interface SealedPolicy { paths: string[]; transcripts: string[]; answer_markers: string[]; seed_patterns: string[]; local_paths: boolean; visibility?: 'public' | 'private' }
|
||||
export interface SealedPolicy { paths: string[]; transcripts: string[]; answer_markers: string[]; seed_patterns: string[]; local_paths: boolean; allow_paths: string[]; case_insensitive: boolean; visibility?: 'public' | 'private' }
|
||||
export interface SealedFinding { rule: SealedRule; file: string; line?: number; commit: string }
|
||||
export type ExemptFinding = SealedFinding & { glob: string };
|
||||
export interface AllowEntry { rule: string; path: string; sha: string; reason: string }
|
||||
export type Visibility = 'public' | 'private' | 'unknown';
|
||||
|
||||
const KEYS = ['paths', 'transcripts', 'answer_markers', 'seed_patterns', 'local_paths', 'visibility'];
|
||||
const KEYS = ['paths', 'transcripts', 'answer_markers', 'seed_patterns', 'local_paths', 'allow_paths', 'case_insensitive', 'visibility'];
|
||||
const MAX_ENTRIES = 64;
|
||||
const MAX_REGEX = 256;
|
||||
const LOCAL_PATH_RE = /(?:^|[^A-Za-z0-9_.~-])(?:\/home\/[^/\s'"`]+\/|\/Users\/[^/\s'"`]+\/|[A-Za-z]:\\+Users\\+[^\\\s'"`]+\\)/;
|
||||
@@ -50,9 +54,9 @@ const PRIVATE_TTL_MS = 3600_000;
|
||||
/** `<key>: <message>` errors for a `sealed` value; empty when valid. Shared with lib/pregate/config.ts. */
|
||||
export function sealedErrors(raw: unknown): Array<{ path: string; message: string }> {
|
||||
const errors: Array<{ path: string; message: string }> = [];
|
||||
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return [{ path: 'sealed', message: 'must be an object { paths, transcripts, answer_markers, seed_patterns, local_paths, visibility }' }];
|
||||
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return [{ path: 'sealed', message: `must be an object { ${KEYS.join(', ')} }` }];
|
||||
const o = raw as Record<string, unknown>;
|
||||
for (const k of Object.keys(o)) if (!KEYS.includes(k)) errors.push({ path: `sealed.${k}`, message: `unknown key; valid keys: ${KEYS.join(', ')}` });
|
||||
for (const k of Object.keys(o)) if (!KEYS.includes(k)) errors.push({ path: `sealed.${k}`, message: `unknown key; valid keys: ${KEYS.join(', ')} (if the key comes from a newer gstack, upgrade gstack on this machine)` });
|
||||
const list = (key: string, check: (s: string) => string | null) => {
|
||||
if (!(key in o)) return;
|
||||
const v = o[key];
|
||||
@@ -62,8 +66,9 @@ export function sealedErrors(raw: unknown): Array<{ path: string; message: strin
|
||||
};
|
||||
const glob = (g: string) => { const why = containedRelative(g); if (why) return why; try { globToRegExp(g); return null; } catch (e: any) { return e.message; } };
|
||||
const regex = (r: string) => { if (!r || r.length > MAX_REGEX) return `must be 1-${MAX_REGEX} characters`; try { new RegExp(r); return null; } catch (e: any) { return `is not a valid regex (${e.message})`; } };
|
||||
list('paths', glob); list('transcripts', glob); list('answer_markers', regex); list('seed_patterns', regex);
|
||||
if ('local_paths' in o && typeof o.local_paths !== 'boolean') errors.push({ path: 'sealed.local_paths', message: 'must be true or false' });
|
||||
const exception = (g: string) => { const name = g.split('/').pop()!; return glob(g) ?? (name.includes('**') || /^[*?]+(\.|$)/.test(name) ? 'has a wildcard file name, which would exempt whole directories or file types; name the file (e.g. **/sealed/*/MANIFEST.json)' : null); };
|
||||
list('paths', glob); list('transcripts', glob); list('answer_markers', regex); list('seed_patterns', regex); list('allow_paths', exception);
|
||||
for (const k of ['local_paths', 'case_insensitive']) if (k in o && typeof o[k] !== 'boolean') errors.push({ path: `sealed.${k}`, message: 'must be true or false' });
|
||||
if ('visibility' in o && o.visibility !== 'public' && o.visibility !== 'private') errors.push({ path: 'sealed.visibility', message: 'must be "public" or "private"' });
|
||||
return errors;
|
||||
}
|
||||
@@ -88,15 +93,15 @@ export function sealedPolicyAt(repoRoot: string, treeish: string, label: string)
|
||||
const errors = sealedErrors(raw.sealed);
|
||||
if (errors.length) return { error: errors.map(e => `${e.path}: ${e.message}`).join('; '), label };
|
||||
const s = raw.sealed;
|
||||
return { policy: { paths: s.paths ?? [], transcripts: s.transcripts ?? [], answer_markers: s.answer_markers ?? [], seed_patterns: s.seed_patterns ?? [], local_paths: s.local_paths === true, visibility: s.visibility }, label };
|
||||
return { policy: { paths: s.paths ?? [], transcripts: s.transcripts ?? [], answer_markers: s.answer_markers ?? [], seed_patterns: s.seed_patterns ?? [], local_paths: s.local_paths === true, allow_paths: s.allow_paths ?? [], case_insensitive: s.case_insensitive === true, visibility: s.visibility }, label };
|
||||
}
|
||||
|
||||
/** Base ∪ pushed: lists concatenate, `local_paths` ORs; visibility stays private only when the base says so and the push does not say public. */
|
||||
/** Base ∪ pushed: deny lists concatenate, `local_paths` and `case_insensitive` OR (both only tighten); `allow_paths` relax, so they come from the base alone; visibility stays private only when the base says so and the push does not say public. */
|
||||
export function unionPolicies(base: SealedPolicy | null, pushed: SealedPolicy | null): SealedPolicy | null {
|
||||
if (!base && !pushed) return null;
|
||||
const u = (k: 'paths' | 'transcripts' | 'answer_markers' | 'seed_patterns') => [...new Set([...(base?.[k] ?? []), ...(pushed?.[k] ?? [])])];
|
||||
const visibility = pushed?.visibility === 'public' || base?.visibility === 'public' ? 'public' : base?.visibility === 'private' ? 'private' : undefined;
|
||||
return { paths: u('paths'), transcripts: u('transcripts'), answer_markers: u('answer_markers'), seed_patterns: u('seed_patterns'), local_paths: !!(base?.local_paths || pushed?.local_paths), visibility };
|
||||
return { paths: u('paths'), transcripts: u('transcripts'), answer_markers: u('answer_markers'), seed_patterns: u('seed_patterns'), local_paths: !!(base?.local_paths || pushed?.local_paths), allow_paths: base?.allow_paths ?? [], case_insensitive: !!(base?.case_insensitive || pushed?.case_insensitive), visibility };
|
||||
}
|
||||
|
||||
/** Reviewed waivers: `rule<TAB>path<TAB>sha<TAB>reason` lines in the base branch's allow file. */
|
||||
@@ -126,12 +131,20 @@ export function rangeCommits(repoRoot: string, range: string): { commits: string
|
||||
|
||||
const HEX = /^[0-9a-f]{40,64}$/;
|
||||
|
||||
/** The first glob matching a repo-relative path, compiled once per list (`matchesAny` normalization); null when none does. */
|
||||
function globMatcher(globs: string[], ignoreCase: boolean): (file: string) => string | null {
|
||||
const compiled = globs.map(g => { const re = globToRegExp(g); return { g, re: ignoreCase ? new RegExp(re.source, 'i') : re }; });
|
||||
return file => { const norm = file.replace(/\\/g, '/').replace(/^\.\//, ''); return compiled.find(c => c.re.test(norm))?.g ?? null; };
|
||||
}
|
||||
|
||||
/** Path rules over every added, renamed or copied path, per commit (merges: paths new against every parent). */
|
||||
function pathFindings(repoRoot: string, commits: string[], p: SealedPolicy): SealedFinding[] {
|
||||
if (!p.paths.length && !p.transcripts.length) return [];
|
||||
const r = git(repoRoot, ['-c', 'core.quotePath=false', 'diff-tree', '--stdin', '-r', '--root', '-M', '-C', '--cc', '--name-status', '-z'], commits.join('\n') + '\n');
|
||||
if (!r.ok) throw new Error(`git diff-tree failed: ${r.err.slice(0, 200)}`);
|
||||
const out: SealedFinding[] = [];
|
||||
const transcript = globMatcher(p.transcripts, p.case_insensitive);
|
||||
const sealedPath = globMatcher(p.paths, p.case_insensitive);
|
||||
const tokens = r.out.split('\0');
|
||||
let commit = '';
|
||||
for (let i = 0; i < tokens.length; i++) {
|
||||
@@ -141,8 +154,8 @@ function pathFindings(repoRoot: string, commits: string[], p: SealedPolicy): Sea
|
||||
const renamed = /^[RC]\d*$/.test(t);
|
||||
const file = renamed ? tokens[i += 2]! : tokens[++i]!;
|
||||
if (!renamed && !t.includes('A')) continue;
|
||||
if (matchesAny(p.transcripts, file)) out.push({ rule: 'sealed.transcript', file, commit });
|
||||
else if (matchesAny(p.paths, file)) out.push({ rule: 'sealed.path', file, commit });
|
||||
if (transcript(file)) out.push({ rule: 'sealed.transcript', file, commit });
|
||||
else if (sealedPath(file)) out.push({ rule: 'sealed.path', file, commit });
|
||||
}
|
||||
return out;
|
||||
}
|
||||
@@ -216,7 +229,7 @@ export function resolveVisibility(url: string | null, o: VisibilityOptions = {})
|
||||
|
||||
export interface SealedReport {
|
||||
status: 'no-policy' | 'clear' | 'refused' | 'warned' | 'error';
|
||||
policyLabels: string[]; commits: number; findings: SealedFinding[]; waived: Array<SealedFinding & { reason: string }>;
|
||||
policyLabels: string[]; commits: number; findings: SealedFinding[]; exempt: ExemptFinding[]; waived: Array<SealedFinding & { reason: string }>;
|
||||
visibility: Visibility; visibilitySource: string; target: string; error?: string;
|
||||
}
|
||||
|
||||
@@ -225,9 +238,14 @@ export interface EvaluateOptions {
|
||||
env?: NodeJS.ProcessEnv; gh?: VisibilityOptions['gh'];
|
||||
}
|
||||
|
||||
/** A report for a failure before any policy is read (an unlisted range, an unreadable push); renders as a fail-closed refusal. */
|
||||
export function sealedErrorReport(error: string, target: string): SealedReport {
|
||||
return { status: 'error', error, policyLabels: [], commits: 0, findings: [], exempt: [], waived: [], visibility: 'unknown', visibilitySource: '', target };
|
||||
}
|
||||
|
||||
/** The whole guard for one push (or range): policies, commits, findings, waivers, visibility, verdict. */
|
||||
export function evaluateSealed(o: EvaluateOptions): SealedReport {
|
||||
const blank = { policyLabels: [] as string[], commits: 0, findings: [] as SealedFinding[], waived: [] as Array<SealedFinding & { reason: string }>, visibility: 'unknown' as Visibility, visibilitySource: '', target: o.target };
|
||||
const blank = { ...sealedErrorReport('', o.target), error: undefined };
|
||||
const base = o.baseRef ? sealedPolicyAt(o.repoRoot, o.baseRef, o.baseLabel ?? o.baseRef) : { policy: null, label: '(no destination base branch)' };
|
||||
if ('error' in base) return { ...blank, status: 'error', error: `the sealed policy on ${base.label} is unreadable: ${base.error}` };
|
||||
let policy: SealedPolicy | null = base.policy;
|
||||
@@ -243,6 +261,13 @@ export function evaluateSealed(o: EvaluateOptions): SealedReport {
|
||||
let found: SealedFinding[];
|
||||
try { found = scanCommits(o.repoRoot, commits, policy); }
|
||||
catch (e: any) { return { ...blank, policyLabels: labels, commits: commits.length, status: 'error', error: `could not read the published commits: ${e.message}` }; }
|
||||
const exception = globMatcher(policy.allow_paths, false);
|
||||
const exempt: ExemptFinding[] = [];
|
||||
found = found.filter(f => {
|
||||
const glob = f.rule === 'sealed.path' || f.rule === 'sealed.transcript' ? exception(f.file) : null;
|
||||
if (glob) exempt.push({ ...f, glob });
|
||||
return !glob;
|
||||
});
|
||||
const allow = allowEntriesAt(o.repoRoot, o.baseRef);
|
||||
const waived: SealedReport['waived'] = [];
|
||||
const findings = found.filter(f => {
|
||||
@@ -252,7 +277,7 @@ export function evaluateSealed(o: EvaluateOptions): SealedReport {
|
||||
});
|
||||
const vis = policy.visibility ? { visibility: policy.visibility as Visibility, source: `${VISIBILITY_OVERRIDE_KEY} override` } : resolveVisibility(o.remoteUrl, { env: o.env, gh: o.gh });
|
||||
const status = findings.length === 0 ? 'clear' : vis.visibility === 'private' ? 'warned' : 'refused';
|
||||
return { status, policyLabels: labels, commits: commits.length, findings, waived, visibility: vis.visibility, visibilitySource: vis.source, target: o.target };
|
||||
return { status, policyLabels: labels, commits: commits.length, findings, exempt, waived, visibility: vis.visibility, visibilitySource: vis.source, target: o.target };
|
||||
}
|
||||
|
||||
const where = (f: SealedFinding) => `${f.file || '(unknown file)'}${f.line ? `:${f.line}` : ''}`;
|
||||
@@ -260,6 +285,7 @@ const where = (f: SealedFinding) => `${f.file || '(unknown file)'}${f.line ? `:$
|
||||
/** stderr text for a report: findings one per line (`<rule> <file[:line]> commit <sha12>`), never the matched text. */
|
||||
export function renderSealed(r: SealedReport, context: string): string {
|
||||
const lines: string[] = [];
|
||||
for (const e of r.exempt) lines.push(`${context}: exempt ${e.rule} ${where(e)} commit ${e.commit.slice(0, 12)} (sealed.allow_paths ${e.glob})`);
|
||||
for (const w of r.waived) lines.push(`${context}: waived ${w.rule} ${where(w)} commit ${w.commit.slice(0, 12)} (${SEALED_ALLOW_PATH}: ${w.reason})`);
|
||||
const vis = `visibility: ${r.visibility}${r.visibility === 'unknown' ? ', counted public' : ''}; ${r.visibilitySource}`;
|
||||
const body = r.findings.map(f => ` ${f.rule} ${where(f)} commit ${f.commit.slice(0, 12)}`);
|
||||
@@ -268,7 +294,7 @@ export function renderSealed(r: SealedReport, context: string): string {
|
||||
lines.push(`Fix the sealed policy (gstack-pregate validate), then retry; an unreadable policy never passes (SEALED_OUTPUT_REFUSED)`);
|
||||
} else if (r.status === 'refused') {
|
||||
lines.push(`\n⛔ ${context} BLOCKED the publication of ${r.target} (${vis}) — sealed or eval output in ${r.commits} published commit(s):`, ...body);
|
||||
lines.push(`Remove it from every published commit before this branch reaches a public repository, or waive one reviewed finding with a \`rule<TAB>path<TAB>sha<TAB>reason\` line in the base branch's ${SEALED_ALLOW_PATH}. A private destination: set ${VISIBILITY_OVERRIDE_KEY} "private" in the base branch's ${SEALED_CONFIG_PATH} (SEALED_OUTPUT_REFUSED)`);
|
||||
lines.push(`Remove it from every published commit before this branch reaches a public repository, exempt a publishable path with a sealed.allow_paths glob in the base branch's ${SEALED_CONFIG_PATH}, or waive one reviewed finding with a \`rule<TAB>path<TAB>sha<TAB>reason\` line in the base branch's ${SEALED_ALLOW_PATH}. A private destination: set ${VISIBILITY_OVERRIDE_KEY} "private" in the base branch's ${SEALED_CONFIG_PATH} (SEALED_OUTPUT_REFUSED)`);
|
||||
} else if (r.status === 'warned') {
|
||||
lines.push(`${context}: warning — sealed or eval output in a push to a private destination (${vis}); it would be refused for a public one:`, ...body);
|
||||
}
|
||||
|
||||
@@ -22,7 +22,7 @@ import { baseOverlapLine } from './pr-wait';
|
||||
import { versionAtRef, versionFiles } from './restamp';
|
||||
import type { LoadedPolicy, ShipPolicy, TrainPolicy } from './ship-policy';
|
||||
import { loadBasePolicy, type QueueContext } from './ship-queue';
|
||||
import { bindReceipt } from './ship-receipt';
|
||||
import { bindShippedReceipt } from './ship-receipt-depth';
|
||||
import { git, sha256, withIndex, type QueueFailure } from './ship-queue-gate';
|
||||
import { recordVerdict, screenVerdict, verdictLines } from './ship-queue-screen';
|
||||
import { stackTestLine, stackTests } from './ship-queue-stack-tests';
|
||||
@@ -351,8 +351,8 @@ function admitSlots(env: TrainEnv, pins: Array<{ pr: string; sha: string }>, dry
|
||||
if (!info.headRefOid.startsWith(p.sha) || fetched !== info.headRefOid) {
|
||||
return outRefused({ code: 'QUEUE_TRAIN_MOVED', message: `PR #${p.pr} moved: pinned ${p.sha.slice(0, 12)}, head is now ${info.headRefOid.slice(0, 12)}` }, [], `ask #${p.pr}'s lane for READY on ${info.headRefOid.slice(0, 12)}, then ${Q} train build --prs <pins>`, 'none');
|
||||
}
|
||||
const shipped = bindReceipt(info.body, p.pr, [info.headRefOid]);
|
||||
if (!shipped.ok) return outRefused({ code: shipped.code, message: shipped.message }, [shipped.line], `#${p.pr}'s lane runs /ship, then ${Q} ready --pr ${p.pr} --screen|--no-screen; then ${Q} train build --prs <pins>`, 'none');
|
||||
const shipped = bindShippedReceipt(ctx.repoRoot, `refs/remotes/${env.remote}/${ctx.base}`, info.body, p.pr, [info.headRefOid]);
|
||||
if (!shipped.ok) return outRefused({ code: shipped.code, message: shipped.message }, [shipped.line, ...(shipped.depthLine ? [shipped.depthLine] : [])], `#${p.pr}'s lane runs /ship, then ${Q} ready --pr ${p.pr} --screen|--no-screen; then ${Q} train build --prs <pins>`, 'none');
|
||||
const ready = loadReady(env.repo.keys, p.pr, info.headRefOid);
|
||||
if (!ready) return outRefused({ code: 'QUEUE_NOT_READY', message: `no READY receipt for #${p.pr} at ${info.headRefOid.slice(0, 12)} (local state or ${'refs/notes/gstack-trains'})` }, [], `the lane runs ${Q} ready --pr ${p.pr} --screen|--no-screen`, 'none');
|
||||
let screen = ready.screen;
|
||||
|
||||
+4
-2
@@ -31,7 +31,8 @@ import type { PregateFile } from './headless-artifacts';
|
||||
import { CHECKS, pregateMirrorPath, readPregateFile, verifyPregate, PREGATE_OUT_REL } from './pregate/index';
|
||||
import { ensureTmpExcluded, restamp, versionAtRef } from './restamp';
|
||||
import type { ResultCodeName } from './result-codes';
|
||||
import { bindReceipt, extractReceipt } from './ship-receipt';
|
||||
import { extractReceipt } from './ship-receipt';
|
||||
import { bindShippedReceipt } from './ship-receipt-depth';
|
||||
import { isUnavailable, loadPolicyFromBase, type LoadedPolicy } from './ship-policy';
|
||||
import {
|
||||
QUEUE_DIR_REL, applyStampPatch, commitForTree, currentAttempt, git, listAttempts, recomputeMergeTree, sha256, writeJsonAtomic,
|
||||
@@ -254,7 +255,7 @@ export function ready(ctx: QueueContext, o: { pr: string; pregate?: string; gate
|
||||
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 receipt = bindReceipt(info.body ?? '', o.pr, acceptedReceiptHeads(ctx, policy, head, info.body ?? ''));
|
||||
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);
|
||||
const lines = [
|
||||
@@ -268,6 +269,7 @@ export function ready(ctx: QueueContext, o: { pr: string; pregate?: string; gate
|
||||
pregateLine,
|
||||
gateLine(policy, attempt),
|
||||
receipt.line,
|
||||
...(receipt.depthLine ? [receipt.depthLine] : []),
|
||||
];
|
||||
const gate = policy.policy.full_e2e ? gateEvidence(ctx, o.pr, head, attempt, o.gateExit, o.gateLog) : null;
|
||||
if (gate) lines.push(gate.line);
|
||||
|
||||
@@ -0,0 +1,164 @@
|
||||
/**
|
||||
* ship-receipt-depth — what the /ship receipt says about how deeply the
|
||||
* review read the head, and what the queue checks against it
|
||||
* (docs/review-policy.md#review-depth, docs/ship-policy.md#ship-receipt).
|
||||
*
|
||||
* `review_depth`: the depth the reviewed head needs, recomputed by
|
||||
* `gstack-ship-receipt write` (receiptDepthAtHead: the committed range from
|
||||
* git objects, gstack-diff-scope on that range and the gate scan of the clean
|
||||
* checkout at that head), with the runtime lines, the rules hash, the base and
|
||||
* registry commits and the gate scan bound to the head.
|
||||
* `review_loop_exception`: the owner's acceptance of a stop after a
|
||||
* fix-check edit under frozen scope (#3559), shaped like the docs exception.
|
||||
* The queue recomputes the depth the head needs from git objects
|
||||
* (lib/review-collect.ts) and refuses a receipt below it. Kept beside
|
||||
* lib/ship-receipt.ts so that module stays under the size ratchet.
|
||||
*/
|
||||
import { spawnSync } from 'node:child_process';
|
||||
import * as path from 'node:path';
|
||||
import type { ShipReceipt } from './headless-artifacts';
|
||||
import { collectCommit } from './review-collect';
|
||||
import { classifyPath, depthOfCommitInput, type Depth } from './review-depth';
|
||||
import { runScriptSync } from './script-invocation';
|
||||
import { bindReceipt, type ReceiptBindingCode } from './ship-receipt';
|
||||
import { docsExceptionLine, parseReceiptDocs } from './ship-receipt-docs';
|
||||
|
||||
export type ReceiptDepth = NonNullable<ShipReceipt['review_depth']>;
|
||||
export type ReviewLoopException = NonNullable<ShipReceipt['review_loop_exception']>;
|
||||
const RANK: Record<Depth, number> = { light: 0, standard: 1, full: 2 };
|
||||
const text = (v: unknown): v is string => typeof v === 'string' && v.trim().length > 0 && !/[\x00-\x1f\x7f]/.test(v);
|
||||
const sha = (v: unknown): v is string => typeof v === 'string' && /^[0-9a-f]{40}$/.test(v);
|
||||
const BIN_DIR = path.join(import.meta.dir, '..', 'bin');
|
||||
const short = (s: string | null | undefined) => (s ? s.slice(0, 12) : 'none');
|
||||
|
||||
function git(root: string, args: string[]): { ok: boolean; out: string } {
|
||||
const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: 60_000 });
|
||||
return { ok: r.status === 0, out: (r.stdout ?? '').trim() };
|
||||
}
|
||||
|
||||
/** gstack-diff-scope on the committed range `base`...`head` (`--head`): the same signals at write, carry and the queue. */
|
||||
function scopeOfRange(root: string, binDir: string, base: string, head: string): Record<string, string> {
|
||||
const sr = runScriptSync(path.join(binDir, 'gstack-diff-scope'), [base, '--head', head], { cwd: root, encoding: 'utf8', timeout: 60_000, maxBuffer: 16 * 1024 * 1024 });
|
||||
const scope: Record<string, string> = {};
|
||||
for (const l of (sr.stdout ?? '').split('\n')) { const m = /^(SCOPE_[A-Z_]+)=(.*)$/.exec(l); if (m) scope[m[1]!] = m[2]!; }
|
||||
if (sr.status !== 0 && !scope.SCOPE_ERROR) scope.SCOPE_ERROR = `exit ${sr.status}`;
|
||||
return scope;
|
||||
}
|
||||
|
||||
/**
|
||||
* The depth record for `head`: the range from git objects (collectCommit) and
|
||||
* its diff-scope, as the queue recomputes them, plus, for a tests or code diff,
|
||||
* the gate scan of this checkout. The scan reads the working tree, so it counts
|
||||
* only when the checkout is `head` with no tracked edits; otherwise it is
|
||||
* unavailable and the depth fails closed to full.
|
||||
*/
|
||||
export function receiptDepthAtHead(repoRoot: string, base: string, binDir: string, head: string): ReceiptDepth {
|
||||
const branch = base.replace(/^origin\//, '');
|
||||
const baseSha = git(repoRoot, ['rev-parse', '--verify', '--quiet', `origin/${branch}^{commit}`]);
|
||||
const baseRev = baseSha.ok ? baseSha.out : branch;
|
||||
const c = collectCommit(repoRoot, baseRev, head);
|
||||
const scope = scopeOfRange(repoRoot, binDir, baseRev, head);
|
||||
let tagged: number | null = 0;
|
||||
if (c.paths.some(p => classifyPath(p, c.root) !== 'docs')) {
|
||||
const atHead = git(repoRoot, ['rev-parse', 'HEAD']).out === head && git(repoRoot, ['diff', '--quiet', 'HEAD', '--']).ok;
|
||||
const g = atHead ? runScriptSync(path.join(binDir, 'gstack-gate-diff'), [baseRev], { cwd: repoRoot, encoding: 'utf8', timeout: 120_000, maxBuffer: 16 * 1024 * 1024 }) : null;
|
||||
const m = /GATE_SUMMARY: .*?tagged=\{([^}]*)\}/.exec(g?.stdout ?? '');
|
||||
tagged = g?.status === 0 && m ? m[1]!.split(',').reduce((n, kv) => n + (Number(kv.split(':')[1]) || 0), 0) : null;
|
||||
}
|
||||
const d = depthOfCommitInput({ ...c, scope, gateTagged: tagged });
|
||||
return { depth: d.depth, class: d.class, runtime_lines: d.runtimeLines, rules: d.rules, base: baseRev, registry: c.registry.sha, gate_scan: { tagged, head }, reasons: d.reasons.slice(0, 12) };
|
||||
}
|
||||
|
||||
export const depthBelow = (have: Depth, need: Depth) => RANK[have] < RANK[need];
|
||||
export const deeper = (a: Depth, b: Depth): Depth => (RANK[a] >= RANK[b] ? a : b);
|
||||
|
||||
/** `write --review-loop-exception` input and the queue's check: who accepted the stop, when, where, why, and the fix-check it followed. */
|
||||
export function parseReviewLoopException(value: unknown): { ok: true; exception: ReviewLoopException } | { ok: false; message: string } {
|
||||
const bad = (message: string) => ({ ok: false as const, message });
|
||||
if (!value || typeof value !== 'object' || Array.isArray(value)) return bad('review_loop_exception must be { accepted_by, date, via, reason, fix_check: { head, findings[, files] } }');
|
||||
const v = value as Record<string, unknown>;
|
||||
for (const key of Object.keys(v)) if (!['accepted_by', 'date', 'via', 'reason', 'fix_check'].includes(key)) return bad(`review_loop_exception: unknown key ${JSON.stringify(key)}`);
|
||||
for (const key of ['accepted_by', 'date', 'via', 'reason']) if (!text(v[key])) return bad(`review_loop_exception.${key} must be a non-empty one-line string`);
|
||||
if (!/^\d{4}-\d{2}-\d{2}$/.test(v.date as string)) return bad('review_loop_exception.date must be YYYY-MM-DD');
|
||||
const f = v.fix_check as Record<string, unknown> | null;
|
||||
if (!f || typeof f !== 'object' || Array.isArray(f)) return bad('review_loop_exception.fix_check must be { head, findings[, files] }');
|
||||
for (const key of Object.keys(f)) if (!['head', 'findings', 'files'].includes(key)) return bad(`review_loop_exception.fix_check: unknown key ${JSON.stringify(key)}`);
|
||||
if (!sha(f.head)) return bad('review_loop_exception.fix_check.head must be the full commit the fix-check reviewed');
|
||||
if (typeof f.findings !== 'number' || !Number.isInteger(f.findings) || f.findings < 0) return bad('review_loop_exception.fix_check.findings must be an integer >= 0 (what the fix-check reported)');
|
||||
if (f.files !== undefined && (!Array.isArray(f.files) || !f.files.every(text))) return bad('review_loop_exception.fix_check.files must be a list of paths');
|
||||
const files = (f.files as string[] | undefined)?.slice(0, 50);
|
||||
return { ok: true, exception: { accepted_by: (v.accepted_by as string).trim(), date: v.date as string, via: (v.via as string).trim(), reason: (v.reason as string).trim(), fix_check: { head: f.head, findings: f.findings, ...(files?.length ? { files } : {}) } } };
|
||||
}
|
||||
|
||||
/** The line the PR body must carry, word for word, while the exception stands. */
|
||||
export function reviewLoopExceptionLine(e: ReviewLoopException): string {
|
||||
return `Review-loop exception: accepted by ${e.accepted_by} ${e.date} via ${e.via}: ${e.reason} (fix-check at ${e.fix_check.head.slice(0, 12)}, ${e.fix_check.findings} finding${e.fix_check.findings === 1 ? '' : 's'})`;
|
||||
}
|
||||
|
||||
const carries = (body: string, line: string) => body.split(/\r?\n/).some(l => l.trim() === line);
|
||||
|
||||
/**
|
||||
* The owner exceptions a receipt records, checked the same way: valid shape, and the body carries each line verbatim.
|
||||
* `isAncestor`, when given, also requires the review-loop exception's fix-check head to be the receipt head or its ancestor.
|
||||
*/
|
||||
export function exceptionProblems(body: string, r: ShipReceipt, isAncestor?: (commit: string) => boolean): string[] {
|
||||
const out: string[] = [];
|
||||
const raw = r as ShipReceipt & { docs?: unknown };
|
||||
if (raw.docs !== undefined) {
|
||||
const d = parseReceiptDocs(raw.docs);
|
||||
if (!d.ok) out.push(`docs: ${d.message}`);
|
||||
else { const line = docsExceptionLine(d.docs); if (line && !carries(body, line)) out.push(`the body does not carry the documentation exception line verbatim: ${JSON.stringify(line)}`); }
|
||||
}
|
||||
if (r.review_loop_exception !== undefined) {
|
||||
const e = parseReviewLoopException(r.review_loop_exception);
|
||||
if (!e.ok) out.push(e.message);
|
||||
else {
|
||||
if (!r.review_loop?.fix_checks) out.push('review_loop_exception needs review_loop.fix_checks >= 1 (the stop it accepts follows a fix-check)');
|
||||
if (isAncestor && !isAncestor(e.exception.fix_check.head)) out.push(`review_loop_exception.fix_check.head ${e.exception.fix_check.head.slice(0, 12)} is not the receipt head or an ancestor of it`);
|
||||
const line = reviewLoopExceptionLine(e.exception);
|
||||
if (!carries(body, line)) out.push(`the body does not carry the review-loop exception line verbatim: ${JSON.stringify(line)}`);
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
export interface DepthVerdict { ok: boolean; line: string; message?: string }
|
||||
|
||||
/**
|
||||
* The depth the bound head needs against `baseRef`, recomputed from git
|
||||
* objects; the recorded gate scan counts only when it names the receipt's
|
||||
* head, otherwise the scan is unavailable and the head needs full. A receipt
|
||||
* with no review_depth and no gstack_version predates depth receipts and is
|
||||
* accepted as legacy; one from a writer that records depth but lacks it is not.
|
||||
*/
|
||||
export function receiptDepthVerdict(root: string, baseRef: string, r: ShipReceipt, head: string): DepthVerdict {
|
||||
const rd = r.review_depth;
|
||||
if (!rd && !r.gstack_version) return { ok: true, line: 'REVIEW_DEPTH: legacy receipt (written before receipts recorded review_depth); accepted' };
|
||||
const baseSha = git(root, ['rev-parse', '--verify', '--quiet', `${baseRef}^{commit}`]);
|
||||
const baseRev = baseSha.ok ? baseSha.out : baseRef;
|
||||
const c = collectCommit(root, baseRev, head);
|
||||
const scanBound = !!rd && rd.gate_scan.tagged !== null && /^[0-9a-f]{40,64}$/.test(rd.gate_scan.head) && rd.gate_scan.head === head.toLowerCase();
|
||||
const need = depthOfCommitInput({ ...c, scope: scopeOfRange(root, BIN_DIR, baseRev, head), gateTagged: scanBound ? rd!.gate_scan.tagged : null });
|
||||
const have = rd?.depth;
|
||||
const inputs = `base@${short(baseSha.ok ? baseSha.out : null)},registry@${short(c.registry.sha)},gate_scan@${scanBound ? short(rd!.gate_scan.head) : 'missing'}`;
|
||||
const line = `REVIEW_DEPTH: receipt=${have ?? 'none'} required=${need.depth} runtime_lines=${need.runtimeLines} class=${need.class} reasons=${need.reasons.join(',')} inputs=${inputs}`;
|
||||
if (have && !depthBelow(have, need.depth)) return { ok: true, line };
|
||||
const why = have ? `was reviewed at ${have} depth` : 'records no review_depth though its writer records one';
|
||||
const errs = need.errors.map(e => `${e.code} (${e.input})`).join('; ');
|
||||
return { ok: false, line, message: `the receipt ${why}, but head ${head.slice(0, 12)} needs ${need.depth} (${need.reasons.join(', ')}${errs ? `; ${errs}` : ''}); the receipt is unchanged; run /ship on ${head.slice(0, 12)}` };
|
||||
}
|
||||
|
||||
/** bindReceipt plus the owner exceptions and the review depth: what READY and train build accept. */
|
||||
export function bindShippedReceipt(root: string, baseRef: string, body: string, pr: string | undefined, accepted: readonly string[]):
|
||||
| { ok: true; receipt: ShipReceipt; head: string; line: string; depthLine: string }
|
||||
| { ok: false; code: ReceiptBindingCode | 'QUEUE_RECEIPT_DEPTH_RAISED' | 'QUEUE_RECEIPT_EXCEPTION_INVALID'; message: string; line: string; depthLine?: string } {
|
||||
const b = bindReceipt(body, pr, accepted);
|
||||
if (!b.ok) return b;
|
||||
const ancestor = (commit: string) => b.receipt.carry?.ancestry === 'rewritten' || git(root, ['merge-base', '--is-ancestor', commit, b.head]).ok;
|
||||
const problems = exceptionProblems(body, b.receipt, ancestor);
|
||||
if (problems.length) return { ok: false, code: 'QUEUE_RECEIPT_EXCEPTION_INVALID', message: `the receipt's owner exception does not stand: ${problems.join('; ')}`, line: b.line };
|
||||
const d = receiptDepthVerdict(root, baseRef, b.receipt, b.head);
|
||||
if (!d.ok) return { ok: false, code: 'QUEUE_RECEIPT_DEPTH_RAISED', message: d.message!, line: b.line, depthLine: d.line };
|
||||
return { ...b, depthLine: d.line };
|
||||
}
|
||||
|
||||
+49
-9
@@ -17,7 +17,8 @@ export const RECEIPT_FENCE = 'gstack-ship-receipt';
|
||||
const KEY_ORDER: Array<keyof ShipReceipt | 'docs'> = [
|
||||
'schema_version', 'pr', 'head', 'version', 'base', 'gated_tree', 'predecessor', 'tree', 'gate_reuse', 'gate', 'ci', 'spend_usd',
|
||||
'session_kind', 'artifacts_consumed', 'run', 'thread', 'policy', 'queue_mode', 'preregistration', 'history',
|
||||
'pregate', 'requires_remote', 'issues', 'approval', 'docs', 'review_loop', 'carry',
|
||||
'head_tree', 'product_patch_id', 'gstack_version', 'review_depth', 'pregate', 'requires_remote', 'issues', 'approval', 'docs', 'review_loop',
|
||||
'review_loop_exception', 'carry',
|
||||
];
|
||||
|
||||
/** Keys in the fixed order so identifiers lead; undefined values are dropped. */
|
||||
@@ -118,6 +119,7 @@ export function receiptSummaryLine(r: ShipReceipt): string {
|
||||
if (r.predecessor) parts.push(`predecessor=${r.predecessor.slice(0, 12)}`);
|
||||
if (r.session_kind) parts.push(`session_kind=${r.session_kind}`);
|
||||
if (r.artifacts_consumed) parts.push(`artifacts_consumed=${r.artifacts_consumed}`);
|
||||
if (r.review_depth && typeof r.review_depth.depth === 'string') parts.push(`depth=${r.review_depth.depth}`);
|
||||
if (r.approval) parts.push(`approval=${approvalSummary(r.approval)}`);
|
||||
const loop = parseReviewLoop(r.review_loop);
|
||||
if (loop) parts.push(`passes=${loop.passes} blocking_found=${loop.blocking_found} deferred=${loop.deferred}`
|
||||
@@ -150,7 +152,8 @@ export const CARRY_METADATA_GLOBS: readonly string[] = ['VERSION', 'CHANGELOG.md
|
||||
/** How many differing product paths a RECEIPT_CARRY_PRODUCT_CHANGED refusal names, and how far the per-path patch-id walk goes. */
|
||||
export const CARRY_NAMED_PATHS = 20;
|
||||
|
||||
export type CarryClass = 'product' | 'test' | 'metadata';
|
||||
/** `generated`: an output of a base-registry entry with a command, which the pregate for HEAD proved its command recreates (its inputs are product). */
|
||||
export type CarryClass = 'product' | 'test' | 'metadata' | 'generated';
|
||||
export interface CarryPlanInput {
|
||||
/** The reviewed head the receipt names. */
|
||||
from: string; head: string;
|
||||
@@ -164,8 +167,10 @@ export interface CarryPlanInput {
|
||||
mergeCommits: number;
|
||||
rangeDiff: string;
|
||||
}
|
||||
export interface CarryRecord { from: string; reason: string; product_patch_id: string; changed_paths: string[]; merge_commits: number; range_diff: string; covers: string[]; reruns: string[] }
|
||||
export type CarryPlan = { ok: true; carry: CarryRecord } | { ok: false; code: 'RECEIPT_CARRY_PRODUCT_CHANGED' | 'RECEIPT_CARRY_REFUSED'; message: string };
|
||||
export interface CarryRecord { from: string; reason: string; product_patch_id: string; changed_paths: string[]; merge_commits: number; range_diff: string; covers: string[]; reruns: string[]; trees?: string[]; ancestry?: 'linear' | 'rewritten' }
|
||||
export type CarryPlan = { ok: true; carry: CarryRecord } | { ok: false; code: 'RECEIPT_CARRY_PRODUCT_CHANGED' | 'RECEIPT_CARRY_REFUSED' | 'RECEIPT_CARRY_TREE_MISMATCH'; message: string };
|
||||
const CARRY_COVERS = ['pre-landing review', 'adversarial review', 'gate integrity', 'documentation audit'];
|
||||
const CARRY_RERUNS = ['CI at head (gstack-ship-queue ready requires it); test and helper code changed since the reviewed head runs there unreviewed'];
|
||||
|
||||
/**
|
||||
* The file's text at the reviewed head and at HEAD, with the release version each head carries (from `VERSION`, else
|
||||
@@ -206,9 +211,10 @@ export function stampOnlyText(change: CarryChange): boolean {
|
||||
* the tree receipt. `change` carries the texts; a caller without them gets the
|
||||
* list-only answer.
|
||||
*/
|
||||
export function classifyCarryPath(rel: string, extra: { metadata?: readonly string[] } = {}, change?: CarryChange): CarryClass {
|
||||
export function classifyCarryPath(rel: string, extra: { metadata?: readonly string[]; outputs?: readonly string[] } = {}, change?: CarryChange): CarryClass {
|
||||
const stamp = () => !change || (stampFileKind(rel) ? versionStampOnly(rel, change.before, change.after).stampOnly : stampOnlyText(change));
|
||||
if (matchesAny(CARRY_METADATA_GLOBS, rel)) return !change || !stampFileKind(rel) || versionStampOnly(rel, change.before, change.after).stampOnly ? 'metadata' : 'product';
|
||||
if (matchesAny(extra.outputs ?? [], rel)) return 'generated';
|
||||
if (matchesAny(extra.metadata ?? [], rel)) return stamp() ? 'metadata' : 'product';
|
||||
if (matchesAny(CARRY_TEST_GLOBS, rel)) return 'test';
|
||||
return 'product';
|
||||
@@ -230,14 +236,45 @@ export function planCarry(input: CarryPlanInput): CarryPlan {
|
||||
if (input.mergeCommits > 0) reasons.push(input.mergeCommits === 1 ? 'base merge' : `${input.mergeCommits} base merges`);
|
||||
if (input.testPatchId.from !== input.testPatchId.head) reasons.push('test-only change');
|
||||
if (input.changed.some(c => c.class === 'metadata')) reasons.push('release metadata');
|
||||
if (input.changed.some(c => c.class === 'generated')) reasons.push('regenerated outputs');
|
||||
if (!reasons.length) reasons.push(input.changed.length ? 'no product change' : 'no content change');
|
||||
return {
|
||||
ok: true,
|
||||
carry: {
|
||||
from: input.from, reason: reasons.join(' + '), product_patch_id: input.productPatchId.head || 'none',
|
||||
changed_paths: input.changed.slice(0, 50).map(c => `${c.class}:${c.path}`), merge_commits: input.mergeCommits, range_diff: input.rangeDiff,
|
||||
covers: ['pre-landing review', 'adversarial review', 'gate integrity', 'documentation audit'],
|
||||
reruns: ['CI at head (gstack-ship-queue ready requires it); test and helper code changed since the reviewed head runs there unreviewed'],
|
||||
covers: CARRY_COVERS, reruns: CARRY_RERUNS, ancestry: 'linear',
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export interface TreeCarryInput {
|
||||
from: string; head: string;
|
||||
/** HEAD^{tree}, and every tree the receipt already covers (its head_tree plus earlier carries' trees). */
|
||||
headTree: string; coveredTrees: readonly string[];
|
||||
/** The product patch-id against the base the receipt recorded, and the one HEAD has against the current base. */
|
||||
productPatchId: { recorded: string; head: string };
|
||||
}
|
||||
|
||||
/**
|
||||
* The carry across rewritten history (a rebase or force-push): the receipt
|
||||
* follows HEAD only when HEAD's tree is one the receipt already covers and the
|
||||
* product diff against the current base has the patch-id the receipt recorded.
|
||||
* The tree alone is not enough: a stacked branch rebased onto main after its
|
||||
* base closed unmerged keeps its tree while its diff grows by the base's code.
|
||||
*/
|
||||
export function planTreeCarry(input: TreeCarryInput): CarryPlan {
|
||||
if (!input.coveredTrees.includes(input.headTree)) {
|
||||
return { ok: false, code: 'RECEIPT_CARRY_TREE_MISMATCH', message: `the receipt's head ${input.from.slice(0, 12)} is not an ancestor of HEAD ${input.head.slice(0, 12)} (rebased or force-pushed), and HEAD's tree ${input.headTree.slice(0, 12)} is not a tree the receipt covers (${input.coveredTrees.map(t => t.slice(0, 12)).join(', ') || 'none recorded'}); the receipt is unchanged: run /ship on ${input.head.slice(0, 12)}` };
|
||||
}
|
||||
if (input.productPatchId.recorded !== input.productPatchId.head) {
|
||||
return { ok: false, code: 'RECEIPT_CARRY_PRODUCT_CHANGED', message: `HEAD ${input.head.slice(0, 12)} has the reviewed tree, but its product diff against the current base differs from the one reviewed at ${input.from.slice(0, 12)} (the base itself moved under it); the receipt is unchanged: run /ship on ${input.head.slice(0, 12)}` };
|
||||
}
|
||||
return {
|
||||
ok: true,
|
||||
carry: {
|
||||
from: input.from, reason: 'rebase onto a reviewed tree', product_patch_id: input.productPatchId.head || 'none',
|
||||
changed_paths: [], merge_commits: 0, range_diff: 'tree-equal', covers: CARRY_COVERS, reruns: CARRY_RERUNS, ancestry: 'rewritten',
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -247,14 +284,17 @@ export function planCarry(input: CarryPlanInput): CarryPlan {
|
||||
* recorded. A receipt carried before keeps the reviewed head as `from` and adds
|
||||
* this hop's merges and paths, so the record always names the head a review saw.
|
||||
*/
|
||||
export function carryReceipt(receipt: ShipReceipt, head: string, carry: CarryRecord): ShipReceipt {
|
||||
export function carryReceipt(receipt: ShipReceipt, head: string, carry: CarryRecord, at: { tree: string; fromTree?: string; productPatchId: string }): ShipReceipt {
|
||||
const prior = receipt.carry;
|
||||
const merged: CarryRecord = !prior ? carry : {
|
||||
...carry, from: prior.from, reason: prior.reason === carry.reason ? carry.reason : `${prior.reason} + ${carry.reason}`,
|
||||
merge_commits: prior.merge_commits + carry.merge_commits,
|
||||
changed_paths: [...prior.changed_paths, ...carry.changed_paths.filter(p => !prior.changed_paths.includes(p))].slice(0, 50),
|
||||
ancestry: prior.ancestry === 'rewritten' ? 'rewritten' : carry.ancestry,
|
||||
};
|
||||
return orderReceipt({ ...receipt, head, carry: merged });
|
||||
const fromTree = receipt.head_tree ?? at.fromTree;
|
||||
const trees = [...new Set([...(prior?.trees ?? []), ...(fromTree ? [fromTree] : [])])].filter(t => t !== at.tree).slice(-20);
|
||||
return orderReceipt({ ...receipt, head, head_tree: at.tree, product_patch_id: at.productPatchId || 'none', carry: { ...merged, ...(trees.length ? { trees } : {}) } });
|
||||
}
|
||||
|
||||
/** The loop counters the factory scorecard reads (passes, blocking_found, deferred), as `write --review-loop` records them. */
|
||||
|
||||
Reference in new issue
Block a user