mandrel 2.106.0 → 2.108.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/.agents/docs/configuration.md +32 -0
  2. package/.agents/schemas/agentrc.schema.json +38 -0
  3. package/.agents/schemas/story-deliver-terminal.schema.json +4 -0
  4. package/.agents/scripts/evidence-gate.js +2 -2
  5. package/.agents/scripts/lib/audit-suite/selector.js +13 -5
  6. package/.agents/scripts/lib/audit-suite/sensitive-paths.js +39 -0
  7. package/.agents/scripts/lib/close-validation/process.js +1 -1
  8. package/.agents/scripts/lib/config-settings-schema-quality.js +31 -0
  9. package/.agents/scripts/lib/full-suite-lock.js +81 -8
  10. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  11. package/.agents/scripts/lib/observability/metrics-ledger.js +1 -1
  12. package/.agents/scripts/lib/observability/review-dispositions.js +208 -0
  13. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  14. package/.agents/scripts/lib/orchestration/code-review.js +77 -13
  15. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -0
  16. package/.agents/scripts/lib/orchestration/review-depth.js +9 -3
  17. package/.agents/scripts/lib/orchestration/review-history.js +182 -0
  18. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +22 -2
  19. package/.agents/scripts/lib/orchestration/review-providers/claim-grounding.js +5 -4
  20. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +12 -0
  21. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +15 -8
  22. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +26 -5
  23. package/.agents/scripts/lib/orchestration/review-providers/codex.js +4 -2
  24. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +357 -0
  25. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +53 -0
  26. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +85 -15
  27. package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +40 -1
  28. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +68 -0
  29. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +25 -10
  30. package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
  31. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +3 -0
  32. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +14 -2
  33. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +1 -0
  34. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +24 -1
  35. package/.agents/scripts/lib/suite-admission.js +45 -3
  36. package/.agents/scripts/review-dispositions-report.js +129 -0
  37. package/.agents/workflows/helpers/code-review.md +53 -0
  38. package/docs/CHANGELOG.md +22 -0
  39. package/package.json +1 -1
@@ -22,6 +22,18 @@ export const FINDINGS_SCHEMA_JSON = JSON.stringify({
22
22
  file: { type: 'string' },
23
23
  line: { type: 'integer' },
24
24
  category: { type: 'string' },
25
+ class: { type: 'string' },
26
+ instances: {
27
+ type: 'array',
28
+ items: {
29
+ type: 'object',
30
+ properties: {
31
+ file: { type: 'string' },
32
+ line: { type: 'integer' },
33
+ },
34
+ required: ['file'],
35
+ },
36
+ },
25
37
  claim: CLAIM_SCHEMA,
26
38
  },
27
39
  required: ['title', 'body'],
@@ -38,7 +38,9 @@ import {
38
38
  resolveVerdict,
39
39
  } from './claude-verdict.js';
40
40
  import { readDiff } from './generated-diff.js';
41
+ import { BUG_CLASS_RULE } from './parse-findings.js';
41
42
  import { renderDepthDirective } from './review-depth.js';
43
+ import { renderGuidanceBlock } from './review-guidance.js';
42
44
  import { probeClaudeCli } from './security-review.js';
43
45
 
44
46
  const CLAUDE_ARGS = Object.freeze([
@@ -79,16 +81,18 @@ const PROMPT_HEAD =
79
81
  'input, command or test that exposes it). A `shortcut:` comment naming ' +
80
82
  'its ceiling and trigger is a decision, not a finding, unless this diff ' +
81
83
  'itself crosses the ceiling.\n\n' +
82
- '{scopeNote}' +
83
- 'Answer with a JSON object of this exact shape, no prose around it:\n\n' +
84
- '{"findings":[{"title":"...","body":"Why it is wrong: ... How to show it ' +
85
- 'fails: ...","file":"...","line":1,"category":"bug","claim":null}]}\n\n' +
84
+ `${BUG_CLASS_RULE}\n\n` +
86
85
  'Set `claim` when the problem rests on a checkable fact: ' +
87
86
  '{"kind":"path-absent","path":"<file>"} when a file the change needs is ' +
88
87
  'missing, or {"kind":"symbol-referenced","symbol":"<name>","path":"<its ' +
89
88
  'definition file>"} when a removed or renamed symbol still has callers, ' +
90
89
  'or {"kind":"file-unchanged","path":"<file>"} when the problem is that ' +
91
90
  'another file was not updated. Otherwise leave it null.\n\n' +
91
+ '{scopeNote}{guidance}' +
92
+ 'Answer with a JSON object of this exact shape, no prose around it:\n\n' +
93
+ '{"findings":[{"title":"...","body":"Why it is wrong: ... How to show it ' +
94
+ 'fails: ...","file":"...","line":1,"category":"bug","class":"...",' +
95
+ '"instances":[{"file":"...","line":1}],"claim":null}]}\n\n' +
92
96
  'Emit {"findings":[]} if there is nothing you would block the merge for.\n\n';
93
97
 
94
98
  const WHOLE_DIFF_NOTE =
@@ -210,7 +214,8 @@ function buildPrompt(
210
214
  .replace('{headRef}', input.headRef)
211
215
  .replace('{ticketId}', String(input.ticketId))
212
216
  .replace('{scopeNote}', scope)
213
- .replace('{depthDirective}', renderDepthDirective(input.depth));
217
+ .replace('{depthDirective}', renderDepthDirective(input.depth))
218
+ .replace('{guidance}', () => renderGuidanceBlock(input.guidance));
214
219
  return `${head}<diff>\n${body}${note}\n</diff>\n${callers}`;
215
220
  }
216
221
 
@@ -227,13 +232,14 @@ function quoteWindowsArg(arg) {
227
232
  }
228
233
 
229
234
  /**
230
- * Async, so close's concurrent gate children keep draining.
235
+ * Async, so close's concurrent gate children keep draining. Shared with the
236
+ * critical verifier.
231
237
  *
232
238
  * @param {ReadonlyArray<string>} args
233
239
  * @param {{ cwd: string, input?: string, timeout: number, run?: Function, platform: string }} opts
234
240
  * @returns {Promise<{ status: number, stdout: string, stderr: string }>}
235
241
  */
236
- function runClaude(args, { cwd, input, timeout, run, platform }) {
242
+ export function runClaude(args, { cwd, input, timeout, run, platform }) {
237
243
  const shell = platform === 'win32';
238
244
  return spawnCaptureAsync(
239
245
  'claude',
@@ -346,7 +352,7 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
346
352
  }
347
353
 
348
354
  /**
349
- * The `<callers>` block, the slice note and the manifest ride every chunk,
355
+ * The `<callers>` block, guidance, the slice note and the manifest ride every chunk,
350
356
  * so they come out of the budget; chunk numbers are one digit, so the
351
357
  * note's length is fixed before packing.
352
358
  */
@@ -359,6 +365,7 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
359
365
  const budget =
360
366
  MAX_DIFF_CHARS -
361
367
  callers.length -
368
+ renderGuidanceBlock(input.guidance).length -
362
369
  manifest.length -
363
370
  sliceNote(MAX_REVIEW_CHUNKS, MAX_REVIEW_CHUNKS).length;
364
371
  const chunks = packChunks(sections, budget);
@@ -18,8 +18,10 @@ import { resolveAgentrcRoot } from '../../config/git-roots.js';
18
18
  import { resolvedTempRoot } from '../../config/temp-paths.js';
19
19
  import { resolveConfig } from '../../config-resolver.js';
20
20
  import { STRICT_CLAIM_SCHEMA } from './claim-grounding.js';
21
+ import { BUG_CLASS_RULE } from './parse-findings.js';
21
22
  import { PROVIDER_SEVERITY_MAP } from './provider-severity.js';
22
23
  import { renderDepthDirective } from './review-depth.js';
24
+ import { renderGuidanceBlock } from './review-guidance.js';
23
25
 
24
26
  const PROBE_TIMEOUT_MS = 5000;
25
27
  const INVOKE_TIMEOUT_MS = 15 * 60 * 1000;
@@ -55,6 +57,8 @@ const FINDINGS_SCHEMA = Object.freeze({
55
57
  'file',
56
58
  'line',
57
59
  'category',
60
+ 'class',
61
+ 'instances',
58
62
  'claim',
59
63
  ],
60
64
  properties: {
@@ -64,6 +68,19 @@ const FINDINGS_SCHEMA = Object.freeze({
64
68
  file: { type: ['string', 'null'] },
65
69
  line: { type: ['integer', 'null'] },
66
70
  category: { type: 'string' },
71
+ class: { type: ['string', 'null'] },
72
+ instances: {
73
+ type: ['array', 'null'],
74
+ items: {
75
+ type: 'object',
76
+ additionalProperties: false,
77
+ required: ['file', 'line'],
78
+ properties: {
79
+ file: { type: 'string' },
80
+ line: { type: ['integer', 'null'] },
81
+ },
82
+ },
83
+ },
67
84
  claim: STRICT_CLAIM_SCHEMA,
68
85
  },
69
86
  },
@@ -91,10 +108,11 @@ export function defaultProbeCodexCommand(opts = {}) {
91
108
  }
92
109
 
93
110
  /**
94
- * @param {{ baseRef: string, headRef: string, depth?: ReviewDepth }} args
111
+ * @param {{ baseRef: string, headRef: string, depth?: ReviewDepth,
112
+ * guidance?: string|null }} args
95
113
  * @returns {string}
96
114
  */
97
- function buildReviewPrompt({ baseRef, headRef, depth }) {
115
+ function buildReviewPrompt({ baseRef, headRef, depth, guidance }) {
98
116
  return (
99
117
  `Review the code changes in the git diff \`${baseRef}...${headRef}\` ` +
100
118
  `of this repository (run \`git diff ${baseRef}...${headRef}\` to read ` +
@@ -103,8 +121,10 @@ function buildReviewPrompt({ baseRef, headRef, depth }) {
103
121
  'the change introduces. For each one give the file and line in the new ' +
104
122
  'version when attributable (otherwise null), a short title, a markdown ' +
105
123
  'body explaining why it is wrong and how to fix it, and a category. ' +
106
- 'Do not modify any file. Report findings ONLY through the required ' +
107
- 'output schema; an empty `findings` array means no problems.\n'
124
+ `Do not modify any file.\n\n${BUG_CLASS_RULE}\n\n` +
125
+ renderGuidanceBlock(guidance) +
126
+ 'Report findings ONLY through the required output schema; an empty ' +
127
+ '`findings` array means no problems.\n'
108
128
  );
109
129
  }
110
130
 
@@ -125,7 +145,8 @@ function readIfPresent(file) {
125
145
  * tempRoot (removed afterwards). The prompt rides stdin; the last-message
126
146
  * file becomes `stdout`.
127
147
  *
128
- * @param {{ baseRef: string, headRef: string, depth?: ReviewDepth }} args
148
+ * @param {{ baseRef: string, headRef: string, depth?: ReviewDepth,
149
+ * guidance?: string|null }} args
129
150
  * @param {{ run?: Function, tempRoot?: string, cwd?: string }} [deps]
130
151
  * @returns {Promise<InvokeResult>}
131
152
  */
@@ -66,7 +66,7 @@ export function parseCodexFindings(rawOutput) {
66
66
  /**
67
67
  * @param {{
68
68
  * probeFn?: () => boolean,
69
- * invokeFn?: (args: { baseRef: string, headRef: string, scope: string, ticketId: number, depth?: import('./types.js').ReviewDepth }) => { status: number, stdout: string, stderr: string } | Promise<{ status: number, stdout: string, stderr: string }>,
69
+ * invokeFn?: (args: { baseRef: string, headRef: string, scope: string, ticketId: number, depth?: import('./types.js').ReviewDepth, guidance?: string|null }) => { status: number, stdout: string, stderr: string } | Promise<{ status: number, stdout: string, stderr: string }>,
70
70
  * logger?: { info?: Function, warn?: Function, error?: Function },
71
71
  * }} [deps]
72
72
  * @returns {ReviewProvider}
@@ -86,7 +86,8 @@ export function createCodexProvider(deps = {}) {
86
86
  * @returns {Promise<Finding[]>}
87
87
  */
88
88
  async runReview(input) {
89
- const { scope, ticketId, baseRef, headRef, depth } = input ?? {};
89
+ const { scope, ticketId, baseRef, headRef, depth, guidance } =
90
+ input ?? {};
90
91
  if (!baseRef || !headRef) {
91
92
  throw new TypeError(
92
93
  '[codex-review] runReview requires baseRef and headRef.',
@@ -109,6 +110,7 @@ export function createCodexProvider(deps = {}) {
109
110
  scope,
110
111
  ticketId,
111
112
  depth,
113
+ guidance,
112
114
  });
113
115
  if (result.status !== 0) {
114
116
  throw new Error(
@@ -0,0 +1,357 @@
1
+ /**
2
+ * review-providers/critical-verifier.js — a fresh-context, read-only
3
+ * `claude --print` check of each CRITICAL left after claim grounding. It sees
4
+ * one finding and the refs, nothing else, so it stays a bug check. Only a
5
+ * strict-majority refutation downgrades; an error, a timeout, a missing CLI or
6
+ * unproven evidence leaves the CRITICAL blocking and records a degradation.
7
+ *
8
+ * @typedef {import('./types.js').Finding} Finding
9
+ * @typedef {import('./degraded-gates.js').GateDegradation} GateDegradation
10
+ * @typedef {{ attempted: number, confirmed: number, refuted: number,
11
+ * uncertain: number, errored: number }} VerificationSummary
12
+ */
13
+
14
+ import { gitSpawn } from '../../git-utils.js';
15
+ import { isObject } from '../../json-utils.js';
16
+ import { PROJECT_ROOT } from '../../project-root.js';
17
+ import { groundFindings } from './claim-grounding.js';
18
+ import { clip } from './claude-verdict.js';
19
+ import { runClaude } from './code-review.js';
20
+ import { probeClaudeCli } from './security-review.js';
21
+
22
+ const VERDICTS = ['confirmed', 'refuted', 'uncertain'];
23
+
24
+ const VERDICT_SCHEMA_JSON = JSON.stringify({
25
+ type: 'object',
26
+ properties: {
27
+ verdict: { enum: VERDICTS },
28
+ evidence: {
29
+ type: ['object', 'null'],
30
+ properties: {
31
+ file: { type: 'string' },
32
+ line: { type: 'integer' },
33
+ excerpt: { type: 'string' },
34
+ },
35
+ required: ['file', 'line'],
36
+ },
37
+ reason: { type: 'string' },
38
+ },
39
+ required: ['verdict', 'reason'],
40
+ });
41
+
42
+ /** Read-only by construction: no edit tool, Bash only for three git reads. */
43
+ const VERIFIER_ARGS = Object.freeze([
44
+ '--print',
45
+ '--output-format',
46
+ 'json',
47
+ '--json-schema',
48
+ VERDICT_SCHEMA_JSON,
49
+ '--setting-sources',
50
+ 'user',
51
+ '--strict-mcp-config',
52
+ '--tools',
53
+ 'Read,Grep,Glob,Bash',
54
+ '--allowedTools',
55
+ 'Read',
56
+ 'Grep',
57
+ 'Glob',
58
+ 'Bash(git show:*)',
59
+ 'Bash(git grep:*)',
60
+ 'Bash(git log:*)',
61
+ ]);
62
+
63
+ const VERIFY_TIMEOUT_MS = 5 * 60 * 1000;
64
+ const MAX_VERIFIED_CRITICALS = 10;
65
+ const MAX_IN_FLIGHT = 3;
66
+ const DEGRADATION_BASE = Object.freeze({
67
+ tool: 'critical-verifier',
68
+ gate: 'codeReview',
69
+ surface: 'critical-verification',
70
+ });
71
+
72
+ const emptyVerification = () => ({
73
+ attempted: 0,
74
+ confirmed: 0,
75
+ refuted: 0,
76
+ uncertain: 0,
77
+ errored: 0,
78
+ });
79
+
80
+ /** An injected review provider's findings are scored as returned. */
81
+ const skipVerification = async ({ findings }) => ({
82
+ findings,
83
+ degradations: [],
84
+ verification: emptyVerification(),
85
+ });
86
+
87
+ /** @param {Finding} f */
88
+ const findingName = (f) =>
89
+ f.file
90
+ ? `"${f.title}" (${f.file}${f.line ? `:${f.line}` : ''})`
91
+ : `"${f.title}"`;
92
+
93
+ /**
94
+ * @param {Finding} finding
95
+ * @param {{ baseRef: string, headRef: string }} refs
96
+ * @returns {string}
97
+ */
98
+ function buildVerifierPrompt(finding, { baseRef, headRef }) {
99
+ const subject = {
100
+ title: finding.title,
101
+ body: finding.body,
102
+ file: finding.file ?? null,
103
+ line: finding.line ?? null,
104
+ claim: finding.claim ?? null,
105
+ };
106
+ return (
107
+ `A code reviewer raised the finding below against the change \`${baseRef}...${headRef}\`. ` +
108
+ `Decide whether it is a real bug in the code at \`${headRef}\`.\n\n` +
109
+ `Read code only at \`${headRef}\` (\`git show ${headRef}:<path>\`, ` +
110
+ `\`git grep <pattern> ${headRef}\`, \`git log\`): the working tree may not be at it.\n\n` +
111
+ 'Answer `confirmed` only with the file and line at that ref that show the bug, ' +
112
+ '`refuted` when the code there shows the finding is wrong, `uncertain` otherwise. ' +
113
+ 'Give the reason in one or two sentences, as JSON: ' +
114
+ '{"verdict":"...","evidence":{"file":"...","line":1,"excerpt":"..."},"reason":"..."}\n\n' +
115
+ `<finding>\n${JSON.stringify(subject, null, 2)}\n</finding>\n`
116
+ );
117
+ }
118
+
119
+ function tryParseJson(text) {
120
+ try {
121
+ return JSON.parse(text);
122
+ } catch {
123
+ return undefined;
124
+ }
125
+ }
126
+
127
+ /** @returns {object|null} the verdict object of a successful envelope. */
128
+ function verdictPayload(result) {
129
+ const envelope = result.status === 0 ? tryParseJson(result.stdout) : null;
130
+ if (!isObject(envelope) || envelope.subtype !== 'success') return null;
131
+ if (envelope.is_error === true) return null;
132
+ const payload = isObject(envelope.structured_output)
133
+ ? envelope.structured_output
134
+ : tryParseJson(String(envelope.result ?? ''));
135
+ return isObject(payload) && VERDICTS.includes(payload.verdict)
136
+ ? payload
137
+ : null;
138
+ }
139
+
140
+ /**
141
+ * @param {{ status: number, stdout: string, stderr: string }} result
142
+ * @returns {{ verdict: string, evidence: object|null, reason: string } | { error: string }}
143
+ */
144
+ function parseVerifierResult(result) {
145
+ const payload = verdictPayload(result);
146
+ if (!payload) {
147
+ return result.status === 0
148
+ ? { error: 'verifier output did not parse as a verdict' }
149
+ : {
150
+ error: `claude --print exited ${result.status}: ${clip(result.stderr || result.stdout) || '<no output>'}`,
151
+ };
152
+ }
153
+ return {
154
+ verdict: payload.verdict,
155
+ evidence: isObject(payload.evidence) ? payload.evidence : null,
156
+ reason: clip(payload.reason) || '(no reason given)',
157
+ };
158
+ }
159
+
160
+ /** True when `evidence` names a file and an in-range line at `headRef`. */
161
+ function evidenceExists(evidence, { headRef, cwd, gitSpawnFn }) {
162
+ if (typeof evidence?.file !== 'string' || !Number.isInteger(evidence.line)) {
163
+ return false;
164
+ }
165
+ try {
166
+ const shown = gitSpawnFn(cwd, 'show', `${headRef}:${evidence.file}`);
167
+ if (shown?.status !== 0) return false;
168
+ const lines = String(shown.stdout ?? '')
169
+ .replace(/\n$/, '')
170
+ .split('\n');
171
+ return evidence.line >= 1 && evidence.line <= lines.length;
172
+ } catch {
173
+ return false;
174
+ }
175
+ }
176
+
177
+ /**
178
+ * One verifier call, settled to an outcome; never throws.
179
+ *
180
+ * @returns {Promise<{ outcome: 'confirmed'|'refuted'|'uncertain'|'errored', reason: string }>}
181
+ */
182
+ async function runVoter(finding, ctx) {
183
+ if (!ctx.cliPresent)
184
+ return { outcome: 'errored', reason: 'claude CLI not found on PATH' };
185
+ let parsed;
186
+ try {
187
+ parsed = parseVerifierResult(
188
+ await runClaude(VERIFIER_ARGS, {
189
+ cwd: ctx.cwd,
190
+ input: buildVerifierPrompt(finding, ctx),
191
+ timeout: VERIFY_TIMEOUT_MS,
192
+ run: ctx.spawnFn,
193
+ platform: ctx.platform,
194
+ }),
195
+ );
196
+ } catch (err) {
197
+ parsed = { error: clip(err?.message ?? err) };
198
+ }
199
+ if ('error' in parsed) return { outcome: 'errored', reason: parsed.error };
200
+ if (parsed.verdict === 'confirmed' && !evidenceExists(parsed.evidence, ctx)) {
201
+ return {
202
+ outcome: 'uncertain',
203
+ reason: 'confirmation evidence not found at head',
204
+ unproven: true,
205
+ };
206
+ }
207
+ return { outcome: parsed.verdict, reason: parsed.reason };
208
+ }
209
+
210
+ /** Run `tasks` (thunks) with at most `limit` in flight; results keep order. */
211
+ async function runPooled(tasks, limit) {
212
+ const results = new Array(tasks.length);
213
+ let next = 0;
214
+ async function worker() {
215
+ while (next < tasks.length) {
216
+ const index = next;
217
+ next += 1;
218
+ results[index] = await tasks[index]();
219
+ }
220
+ }
221
+ await Promise.all(
222
+ Array.from({ length: Math.min(limit, tasks.length) }, worker),
223
+ );
224
+ return results;
225
+ }
226
+
227
+ /** Downgrade on a strict majority of refutations; otherwise unchanged. */
228
+ function settleFinding(finding, votes) {
229
+ const refutations = votes.filter((v) => v.outcome === 'refuted');
230
+ if (refutations.length * 2 <= votes.length) return finding;
231
+ return {
232
+ ...finding,
233
+ severity: 'suggestion',
234
+ unverified: refutations[0].reason,
235
+ };
236
+ }
237
+
238
+ function voteDegradations(finding, votes) {
239
+ return votes
240
+ .filter((v) => v.outcome === 'errored' || v.unproven)
241
+ .map((v) => ({
242
+ ...DEGRADATION_BASE,
243
+ reason: `${findingName(finding)} stays blocking: ${v.reason}`,
244
+ }));
245
+ }
246
+
247
+ function boundDegradation(skipped) {
248
+ if (skipped.length === 0) return [];
249
+ return [
250
+ {
251
+ ...DEGRADATION_BASE,
252
+ reason:
253
+ `verification bounded at ${MAX_VERIFIED_CRITICALS} criticals: ` +
254
+ `${skipped.length} stand unverified: ${skipped.map(findingName).join(', ')}`,
255
+ },
256
+ ];
257
+ }
258
+
259
+ /**
260
+ * Verify every `critical` finding; findings below critical are never sent.
261
+ * One verifier at `light`/`standard`, three at `deep`.
262
+ *
263
+ * @param {{
264
+ * findings: Finding[], baseRef: string, headRef: string,
265
+ * depth?: 'light'|'standard'|'deep', cwd?: string,
266
+ * spawnFn?: Function, probeFn?: () => boolean,
267
+ * gitSpawnFn?: typeof gitSpawn, platform?: string,
268
+ * logger?: { info?: Function },
269
+ * }} args
270
+ * @returns {Promise<{ findings: Finding[], degradations: GateDegradation[],
271
+ * verification: VerificationSummary }>}
272
+ */
273
+ async function verifyCriticals(args) {
274
+ const verification = emptyVerification();
275
+ const criticals = args.findings.filter((f) => f?.severity === 'critical');
276
+ if (criticals.length === 0) {
277
+ return { findings: args.findings, degradations: [], verification };
278
+ }
279
+ const checked = criticals.slice(0, MAX_VERIFIED_CRITICALS);
280
+ const voters = args.depth === 'deep' ? 3 : 1;
281
+ const ctx = {
282
+ baseRef: args.baseRef,
283
+ headRef: args.headRef,
284
+ cwd: args.cwd ?? PROJECT_ROOT,
285
+ spawnFn: args.spawnFn,
286
+ platform: args.platform ?? process.platform,
287
+ gitSpawnFn: args.gitSpawnFn ?? gitSpawn,
288
+ cliPresent: (args.probeFn ?? probeClaudeCli)(),
289
+ };
290
+ args.logger?.info?.(
291
+ `[code-review] Verifying ${checked.length} critical(s) with ${voters} verifier(s) each...`,
292
+ );
293
+ const tasks = checked.flatMap((f) =>
294
+ Array.from({ length: voters }, () => () => runVoter(f, ctx)),
295
+ );
296
+ const outcomes = await runPooled(tasks, MAX_IN_FLIGHT);
297
+ const settled = new Map();
298
+ const degradations = [];
299
+ checked.forEach((finding, i) => {
300
+ const votes = outcomes.slice(i * voters, (i + 1) * voters);
301
+ for (const v of votes) verification[v.outcome] += 1;
302
+ settled.set(finding, settleFinding(finding, votes));
303
+ degradations.push(...voteDegradations(finding, votes));
304
+ });
305
+ verification.attempted = tasks.length;
306
+ degradations.push(
307
+ ...boundDegradation(criticals.slice(MAX_VERIFIED_CRITICALS)),
308
+ );
309
+ return {
310
+ findings: args.findings.map((f) => settled.get(f) ?? f),
311
+ degradations,
312
+ verification,
313
+ };
314
+ }
315
+
316
+ /**
317
+ * The pipeline step: ground every finding, then verify the CRITICALs left.
318
+ * An injected review provider gets no verifier unless `opts.verifier` (the
319
+ * spawn/probe/git seams) is given too.
320
+ *
321
+ * @param {{ findings: Finding[], reviewInput: { baseRef: string,
322
+ * headRef: string, depth?: string }, opts: object,
323
+ * degradations: GateDegradation[] }} args
324
+ */
325
+ export async function vetFindings({
326
+ findings,
327
+ reviewInput,
328
+ opts,
329
+ degradations,
330
+ }) {
331
+ const { baseRef, headRef, depth } = reviewInput;
332
+ const grounded = groundFindings({
333
+ findings,
334
+ headRef,
335
+ baseRef,
336
+ cwd: opts.cwd,
337
+ degradations,
338
+ gitSpawnFn: opts.gitSpawnFn,
339
+ });
340
+ const verify =
341
+ opts.verifier || !opts.reviewProvider ? verifyCriticals : skipVerification;
342
+ const verified = await verify({
343
+ findings: grounded.findings,
344
+ baseRef,
345
+ headRef,
346
+ depth,
347
+ cwd: opts.cwd,
348
+ gitSpawnFn: opts.gitSpawnFn,
349
+ logger: opts.logger,
350
+ ...opts.verifier,
351
+ });
352
+ return {
353
+ findings: verified.findings,
354
+ degradations: [...grounded.degradations, ...verified.degradations],
355
+ verification: verified.verification,
356
+ };
357
+ }
@@ -0,0 +1,53 @@
1
+ /**
2
+ * review-providers/finding-identity.js — a finding's stable identity across
3
+ * review runs. Line numbers are left out because they move between heads.
4
+ *
5
+ * @typedef {import('./types.js').Finding} Finding
6
+ */
7
+
8
+ import { createHash } from 'node:crypto';
9
+
10
+ /**
11
+ * Every location of a finding: its `instances`, else its own `file`/`line`.
12
+ *
13
+ * @param {Finding} finding
14
+ * @returns {{ file: string, line?: number }[]}
15
+ */
16
+ export function findingInstances(finding) {
17
+ if (Array.isArray(finding?.instances) && finding.instances.length > 0) {
18
+ return finding.instances;
19
+ }
20
+ if (!finding?.file) return [];
21
+ return Number.isInteger(finding.line)
22
+ ? [{ file: finding.file, line: finding.line }]
23
+ : [{ file: finding.file }];
24
+ }
25
+
26
+ /** @param {unknown} title */
27
+ function normalizeTitle(title) {
28
+ return String(title ?? '')
29
+ .toLowerCase()
30
+ .replace(/\d+/g, '')
31
+ .replace(/\s+/g, ' ')
32
+ .trim();
33
+ }
34
+
35
+ /**
36
+ * First 12 hex chars of sha256 over class (else category), first instance
37
+ * file and, for a class-less finding, its normalized title.
38
+ *
39
+ * @param {Finding} finding
40
+ * @returns {string}
41
+ */
42
+ export function findingId(finding) {
43
+ const cls = finding?.class;
44
+ const parts = [
45
+ cls || finding?.category || 'bug',
46
+ findingInstances(finding)[0]?.file ?? '',
47
+ cls ? '' : normalizeTitle(finding?.title),
48
+ ];
49
+ return createHash('sha256')
50
+ .update(JSON.stringify(parts))
51
+ .digest('hex')
52
+ .slice(0, 12);
53
+ }