From 31fb896ca1c62096a384c784602697ca571be228 Mon Sep 17 00:00:00 2001 From: garrytan Date: Sat, 31 Oct 2026 19:35:25 +0000 Subject: [PATCH] fix: keep every review_exclude_paths candidate when the gate scan is unknown; docs example names its version Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- changelog.d/gst-508-review-exclude-paths.md | 2 +- docs/ship-policy.md | 3 ++- lib/review-exclude.ts | 7 ++++--- test/review-exclude.test.ts | 18 +++++++++++++++++- 4 files changed, 24 insertions(+), 6 deletions(-) diff --git a/changelog.d/gst-508-review-exclude-paths.md b/changelog.d/gst-508-review-exclude-paths.md index 4859bfa95..fe3765093 100644 --- a/changelog.d/gst-508-review-exclude-paths.md +++ b/changelog.d/gst-508-review-exclude-paths.md @@ -2,7 +2,7 @@ ### Added - **`review_exclude_paths` in `.gstack/ship-policy.json`** (`["receipts/**"]`, with `min_gstack_version` at least the release that adds it). It is read from the base branch only, so a branch cannot exclude its own files; a branch that adds the key gets a normal review and `REVIEW_EXCLUDE: none (head sets review_exclude_paths; …)`. Patterns are git glob pathspecs, root-anchored, and git itself lists the matches. -- **Only content is excluded**: data files, docs, `.log` files and files whose bytes are binary and whose extension is not source or script (a branch's `.gitattributes` cannot make a text file count as binary, and a NUL byte cannot hide a `.js` file). Untracked files are never part of the selection. Code, tests, executables, symlinks, submodule commits, gate paths, agent prose, config, `.gstack/` and `.github/` files, gate-tagged files and files with a credential line stay in every reader's diff, each with a reason code. A data file a code or test file names by its full path stays too. A basename, a directory reference or a data manifest that lists receipts does not keep anything. +- **Only content is excluded**: data files, docs, `.log` files and files whose bytes are binary and whose extension is not source or script (a branch's `.gitattributes` cannot make a text file count as binary, and a NUL byte cannot hide a `.js` file). Untracked files are never part of the selection. Code, tests, executables, symlinks, submodule commits, gate paths, agent prose, config, `.gstack/` and `.github/` files, gate-tagged files and files with a credential line stay in every reader's diff, each with a reason code. A data file a code or test file names by its full path stays too, and when the gate scan fails nothing is excluded. A basename, a directory reference or a data manifest that lists receipts does not keep anything. - **`gstack-review-plan` prints `REVIEW_EXCLUDE:`** with the counts, the excluded files by kind, the kept files and a digest. Every reader's `DIFF_CMD:`, the fixture command the security specialist and the Red Team use, and the outside voice's diff leave the files out; kept files come back through `DIFF_KEEP:`. Every brief says what was left out. The kept-file command is bounded at 24,000 argument bytes, and a pattern over that bound is not applied and the plan says why. - **Excluded lines no longer trigger the numeric-claim scan or the targeted money, gate and auth classes**, and they count as docs for the review depth. - **The receipt records `review_exclude`.** `gstack-review-dispatch verify` prints `REVIEW_EXCLUDE_RECORD: digest=` from the briefs the readers got, and `gstack-ship-receipt write --review-exclude ` must match the digest HEAD has under the base policy (`RECEIPT_INVALID field=review_exclude`, nothing written). Carry and the queue compare the digest, not the base commit, so a base merge that leaves the policy alone still carries. diff --git a/docs/ship-policy.md b/docs/ship-policy.md index a4d29de3e..9c09f9808 100644 --- a/docs/ship-policy.md +++ b/docs/ship-policy.md @@ -1104,7 +1104,7 @@ no reviewer needs to read. `review_exclude_paths` lists git glob pathspecs whose content files `/ship`'s reviewers leave out: ```json -{ "review_exclude_paths": ["receipts/**"], "min_gstack_version": "1.92.0.0" } +{ "review_exclude_paths": ["receipts/**"], "min_gstack_version": "" } ``` **Read from the base only.** `gstack-review-plan` reads the policy committed on @@ -1146,6 +1146,7 @@ Everything else stays in every reader's diff with one reason code: | `secret-line` | an added line reads a credential (the targeted pass's secret rule) | | `named-by-code` | a code or test file that stays in review (not docs, a data file, a `.log` or binary, and not itself excluded) names its full repository path, at the head or the merge base | | `consumer-scan-unavailable` | the `git grep` for those names failed, so every candidate is kept | +| `gate-scan-unavailable` | the gate scan failed or did not run at the head, so no hunk's tag is known and every candidate is kept | Only a full path counts as a name. A basename such as `result.json` would keep every receipt in the tree, and a directory reference such as `receipts/` (the diff --git a/lib/review-exclude.ts b/lib/review-exclude.ts index ea5e071bc..a92e0f136 100644 --- a/lib/review-exclude.ts +++ b/lib/review-exclude.ts @@ -35,7 +35,7 @@ export const KEEP_ARG_MAX_BYTES = 24_000; /** How long one reader's `git diff` may run. */ export const REVIEW_DIFF_TIMEOUT_MS = 120_000; const MAX_BUFFER = 256 * 1024 * 1024; -export const KEPT_REASONS = ['policy-dir', 'gate-path', 'executable', 'agent-prose', 'config', 'gate-tagged', 'code', 'secret-line', 'named-by-code', 'consumer-scan-unavailable', 'link'] as const; +export const KEPT_REASONS = ['policy-dir', 'gate-path', 'executable', 'agent-prose', 'config', 'gate-tagged', 'code', 'secret-line', 'named-by-code', 'consumer-scan-unavailable', 'gate-scan-unavailable', 'link'] as const; export type KeptReason = (typeof KEPT_REASONS)[number]; /** What the receipt records and the queue and carry compare (by `digest`, never by `source`). */ @@ -218,7 +218,7 @@ function grepFixed(i: ExcludeInput, strings: readonly string[], candidates: Read * nothing); `head-only` when only the head does (a notice, never applied); `refused` when the base policy cannot be read or * does not validate, or git cannot list the matches; `active` otherwise. Named-by-code keeps a file only when a kept code * file names its full repository path (never its basename: receipt trees reuse result.json thousands of times); a git grep - * failure keeps every candidate (consumer-scan-unavailable). + * failure keeps every candidate (consumer-scan-unavailable), and so does an unknown gate scan (gate-scan-unavailable). */ export function reviewExclude(i: ExcludeInput): Exclusion { const load = loadPolicyAt(i.root, i.baseSha, i.ref); @@ -238,7 +238,8 @@ export function reviewExclude(i: ExcludeInput): Exclusion { const candidates = new Set([...reasons].filter(([, r]) => r === null).map(([p]) => p)); const named = grepFixed(i, [...candidates].filter(p => !p.includes('\n')), candidates, [i.mergeBase]); for (const p of candidates) { - if (named === null || p.includes('\n')) reasons.set(p, 'consumer-scan-unavailable'); + if (i.gateTagged === null) reasons.set(p, 'gate-scan-unavailable'); + else if (named === null || p.includes('\n')) reasons.set(p, 'consumer-scan-unavailable'); else if (named.has(p)) reasons.set(p, 'named-by-code'); } const applied: string[] = []; diff --git a/test/review-exclude.test.ts b/test/review-exclude.test.ts index 8884239e9..c86b3a3ad 100644 --- a/test/review-exclude.test.ts +++ b/test/review-exclude.test.ts @@ -8,7 +8,8 @@ import { spawnSync } from 'node:child_process'; import * as fs from 'node:fs'; import * as path from 'node:path'; import { EXIT } from '../lib/headless-artifacts'; -import { KEEP_ARG_MAX_BYTES, readSelection, tooLargeLine, unreadableLine } from '../lib/review-exclude'; +import { KEEP_ARG_MAX_BYTES, readSelection, reviewExclude, tooLargeLine, unreadableLine } from '../lib/review-exclude'; +import { collectCommit } from '../lib/review-collect'; import { extractReceipt } from '../lib/ship-receipt'; import { bindShippedReceipt } from '../lib/ship-receipt-depth'; import { REVIEW_EXCLUDE_KEY_VERSION, isUnavailable, loadPolicyAt } from '../lib/ship-policy'; @@ -308,5 +309,20 @@ describe('a branch cannot hide code under a base pattern', () => { expect(p.review_exclude.content).toMatchObject({ binary: 1 }); expect(p).toMatchObject({ depth: 'full', errors: expect.arrayContaining([expect.objectContaining({ code: 'binary_code_path', input: 'assets/loader.js' })]) }); }, 120_000); + + test('an unavailable gate scan keeps every candidate instead of excluding it', () => { + const repo = census(); + const head = repo.git('rev-parse', 'HEAD'); + const baseSha = repo.git('rev-parse', 'origin/main'); + const c = collectCommit(repo.work, baseSha, head); + const at = (gateTagged: ReadonlySet | null) => reviewExclude({ root: repo.work, baseSha, ref: 'origin/main', mergeBase: c.mergeBase!, head, perPath: c.perPath, added: c.added, classRoot: c.root ?? [], gateTagged, context: 'test' }); + const scanned = at(new Set()); + expect(scanned.state === 'active' && [...scanned.excluded].sort()).toEqual([...EXCLUDED].sort()); + const blind = at(null); + expect(blind.state).toBe('active'); + if (blind.state !== 'active') return; + expect(blind.excluded.size).toBe(0); + expect(blind.kept.filter(k => k.reason === 'gate-scan-unavailable').map(k => k.path).sort()).toEqual([...EXCLUDED, 'receipts/b/result.json', 'receipts/d/fixture.json'].sort()); + }, 120_000); });