mandrel 2.105.0 → 2.107.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.
- package/.agents/docs/configuration.md +3 -0
- package/.agents/schemas/agentrc.schema.json +38 -0
- package/.agents/schemas/story-deliver-terminal.schema.json +4 -0
- package/.agents/scripts/lib/audit-suite/selector.js +13 -5
- package/.agents/scripts/lib/audit-suite/sensitive-paths.js +39 -0
- package/.agents/scripts/lib/child-stream.js +17 -11
- package/.agents/scripts/lib/close-validation/process.js +16 -8
- package/.agents/scripts/lib/config-settings-schema-quality.js +31 -0
- package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
- package/.agents/scripts/lib/observability/metrics-ledger.js +1 -1
- package/.agents/scripts/lib/observability/review-dispositions.js +208 -0
- package/.agents/scripts/lib/observability/source-classifier.js +1 -0
- package/.agents/scripts/lib/orchestration/code-review.js +77 -12
- package/.agents/scripts/lib/orchestration/review-deposit.js +2 -0
- package/.agents/scripts/lib/orchestration/review-depth.js +9 -3
- package/.agents/scripts/lib/orchestration/review-history.js +182 -0
- package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +22 -2
- package/.agents/scripts/lib/orchestration/review-providers/claim-grounding.js +38 -14
- package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +12 -0
- package/.agents/scripts/lib/orchestration/review-providers/code-review.js +97 -19
- package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +26 -5
- package/.agents/scripts/lib/orchestration/review-providers/codex.js +4 -2
- package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +357 -0
- package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +53 -0
- package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +85 -15
- package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +40 -1
- package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +68 -0
- package/.agents/scripts/lib/orchestration/review-providers/security-review.js +25 -10
- package/.agents/scripts/lib/orchestration/review-providers/types.js +8 -2
- package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +3 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +14 -2
- package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +1 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +24 -1
- package/.agents/scripts/lib/process-group.js +20 -1
- package/.agents/scripts/lib/supervised-suite.js +12 -11
- package/.agents/scripts/review-dispositions-report.js +129 -0
- package/.agents/workflows/helpers/code-review.md +53 -0
- package/docs/CHANGELOG.md +27 -0
- package/package.json +1 -1
|
@@ -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
|
+
}
|
|
@@ -14,6 +14,7 @@ import {
|
|
|
14
14
|
renderDegradedHeaderLines,
|
|
15
15
|
renderNoFindingsBlock,
|
|
16
16
|
} from './degraded-gates.js';
|
|
17
|
+
import { findingId, findingInstances } from './finding-identity.js';
|
|
17
18
|
|
|
18
19
|
/**
|
|
19
20
|
* @type {ReadonlyArray<Severity>}
|
|
@@ -52,8 +53,21 @@ export function countBySeverity(findings) {
|
|
|
52
53
|
return counts;
|
|
53
54
|
}
|
|
54
55
|
|
|
56
|
+
/** @param {{ file: string, line?: number }} i */
|
|
57
|
+
const formatLocation = (i) => (i.line ? `${i.file}:${i.line}` : i.file);
|
|
58
|
+
|
|
59
|
+
/** An `Instances:` list when the finding has more than one location. */
|
|
60
|
+
function renderInstances(finding) {
|
|
61
|
+
const instances = findingInstances(finding);
|
|
62
|
+
if (instances.length < 2) return [];
|
|
63
|
+
return [
|
|
64
|
+
`Instances:\n${instances.map((i) => `- \`${formatLocation(i)}\``).join('\n')}`,
|
|
65
|
+
];
|
|
66
|
+
}
|
|
67
|
+
|
|
55
68
|
/**
|
|
56
|
-
* The body is emitted verbatim; adapters own its markdown.
|
|
69
|
+
* The body is emitted verbatim; adapters own its markdown. The hidden marker
|
|
70
|
+
* carries the finding's stable id.
|
|
57
71
|
*
|
|
58
72
|
* @param {Finding} finding
|
|
59
73
|
* @returns {string}
|
|
@@ -63,12 +77,58 @@ export function renderFinding(finding) {
|
|
|
63
77
|
const emoji = meta ? meta.emoji : '⚪';
|
|
64
78
|
const attribution = buildAttribution(finding);
|
|
65
79
|
const category = finding.category ? ` _[${finding.category}]_` : '';
|
|
66
|
-
const
|
|
67
|
-
|
|
68
|
-
|
|
80
|
+
const cls = finding.class ? ` \`${finding.class}\`` : '';
|
|
81
|
+
const header = `#### ${emoji} ${finding.title}${attribution}${category}${cls}`;
|
|
82
|
+
return [
|
|
83
|
+
`${header}\n\n${finding.body}`,
|
|
84
|
+
...renderInstances(finding),
|
|
85
|
+
...groundingNotes(finding),
|
|
86
|
+
`<!-- finding:${findingId(finding)} -->`,
|
|
87
|
+
].join('\n\n');
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* A repeat collapses to title, id and locations: it was posted in full before.
|
|
92
|
+
*
|
|
93
|
+
* @param {Finding} finding
|
|
94
|
+
* @returns {string}
|
|
95
|
+
*/
|
|
96
|
+
function renderRepeat(finding) {
|
|
97
|
+
const emoji = SEVERITY_META[finding.severity]?.emoji ?? '⚪';
|
|
98
|
+
const where = findingInstances(finding)
|
|
99
|
+
.map((i) => `\`${formatLocation(i)}\``)
|
|
100
|
+
.join(', ');
|
|
101
|
+
return (
|
|
102
|
+
`- ${emoji} ${finding.title} — \`${findingId(finding)}\`` +
|
|
103
|
+
`${where ? ` — ${where}` : ''} <!-- finding:${findingId(finding)} -->`
|
|
69
104
|
);
|
|
70
105
|
}
|
|
71
106
|
|
|
107
|
+
/** @param {ReadonlyArray<Finding>} repeats */
|
|
108
|
+
function renderRepeatsSection(repeats) {
|
|
109
|
+
if (repeats.length === 0) return [];
|
|
110
|
+
return [
|
|
111
|
+
`### ♻️ Previously raised (${repeats.length})`,
|
|
112
|
+
'',
|
|
113
|
+
...repeats.map(renderRepeat),
|
|
114
|
+
'',
|
|
115
|
+
];
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** Fresh findings render in full per tier; repeats render collapsed. */
|
|
119
|
+
function renderFindingSections(findings) {
|
|
120
|
+
const lines = [];
|
|
121
|
+
const fresh = findings.filter((f) => f && !f.repeat);
|
|
122
|
+
for (const sev of SEVERITY_ORDER) {
|
|
123
|
+
const tierFindings = fresh.filter((f) => f.severity === sev);
|
|
124
|
+
if (tierFindings.length === 0) continue;
|
|
125
|
+
const meta = SEVERITY_META[sev];
|
|
126
|
+
lines.push(`### ${meta.emoji} ${meta.label} (${tierFindings.length})`, '');
|
|
127
|
+
for (const finding of tierFindings) lines.push(renderFinding(finding), '');
|
|
128
|
+
}
|
|
129
|
+
return [...lines, ...renderRepeatsSection(findings.filter((f) => f?.repeat))];
|
|
130
|
+
}
|
|
131
|
+
|
|
72
132
|
/**
|
|
73
133
|
* @param {ReadonlyArray<string>} messages
|
|
74
134
|
* @returns {string[]} lines to append (empty when no messages)
|
|
@@ -98,6 +158,8 @@ function renderManualPromptsSection(messages) {
|
|
|
98
158
|
* provider?: string,
|
|
99
159
|
* promptMessages?: ReadonlyArray<string>,
|
|
100
160
|
* degradations?: ReadonlyArray<object>,
|
|
161
|
+
* verification?: Record<string, number>,
|
|
162
|
+
* skipped?: number,
|
|
101
163
|
* }} input
|
|
102
164
|
* @returns {string}
|
|
103
165
|
*/
|
|
@@ -120,6 +182,10 @@ export function renderFindings(input) {
|
|
|
120
182
|
providerLine,
|
|
121
183
|
`**Findings**: ${totalKnown}`,
|
|
122
184
|
...renderDegradedHeaderLines(degraded),
|
|
185
|
+
...renderVerificationLine(input.verification),
|
|
186
|
+
...(input.skipped > 0
|
|
187
|
+
? [`**Skipped by \`skipPaths\`**: ${input.skipped}`]
|
|
188
|
+
: []),
|
|
123
189
|
'',
|
|
124
190
|
'### 📦 Severity Tier Counts',
|
|
125
191
|
'',
|
|
@@ -134,17 +200,7 @@ export function renderFindings(input) {
|
|
|
134
200
|
if (totalKnown === 0) {
|
|
135
201
|
lines.push(...renderNoFindingsBlock(degraded));
|
|
136
202
|
} else {
|
|
137
|
-
|
|
138
|
-
const tierFindings = findings.filter((f) => f && f.severity === sev);
|
|
139
|
-
if (tierFindings.length === 0) continue;
|
|
140
|
-
const meta = SEVERITY_META[sev];
|
|
141
|
-
lines.push(`### ${meta.emoji} ${meta.label} (${tierFindings.length})`);
|
|
142
|
-
lines.push('');
|
|
143
|
-
for (const finding of tierFindings) {
|
|
144
|
-
lines.push(renderFinding(finding));
|
|
145
|
-
lines.push('');
|
|
146
|
-
}
|
|
147
|
-
}
|
|
203
|
+
lines.push(...renderFindingSections(findings));
|
|
148
204
|
}
|
|
149
205
|
|
|
150
206
|
const promptLines = renderManualPromptsSection(promptMessages ?? []);
|
|
@@ -156,6 +212,20 @@ export function renderFindings(input) {
|
|
|
156
212
|
return lines.join('\n');
|
|
157
213
|
}
|
|
158
214
|
|
|
215
|
+
/**
|
|
216
|
+
* The critical-verifier tally; nothing when no verifier ran.
|
|
217
|
+
*
|
|
218
|
+
* @param {Record<string, number>|undefined} v
|
|
219
|
+
* @returns {string[]}
|
|
220
|
+
*/
|
|
221
|
+
function renderVerificationLine(v) {
|
|
222
|
+
if (!(v?.attempted > 0)) return [];
|
|
223
|
+
return [
|
|
224
|
+
`**Critical verification**: ${v.attempted} attempted · ${v.confirmed} confirmed · ` +
|
|
225
|
+
`${v.refuted} refuted · ${v.uncertain} uncertain · ${v.errored} errored`,
|
|
226
|
+
];
|
|
227
|
+
}
|
|
228
|
+
|
|
159
229
|
/**
|
|
160
230
|
* @param {Finding} finding
|
|
161
231
|
* @returns {string}
|
|
@@ -10,6 +10,15 @@
|
|
|
10
10
|
import { isObject } from '../../json-utils.js';
|
|
11
11
|
import { buildClaim } from './claim-grounding.js';
|
|
12
12
|
|
|
13
|
+
/** Prompt rule shared by the LLM providers; the parser reads its two fields. */
|
|
14
|
+
export const BUG_CLASS_RULE =
|
|
15
|
+
"Name each problem's bug class as a short kebab-case slug in `class`, " +
|
|
16
|
+
'and report every instance of the same defect in this diff as ONE ' +
|
|
17
|
+
'finding whose `instances` lists each location ({"file","line"}); ' +
|
|
18
|
+
'`file` and `line` name the first instance.';
|
|
19
|
+
|
|
20
|
+
const CLASS_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
|
|
21
|
+
|
|
13
22
|
/**
|
|
14
23
|
* Unwrap a bare array, `{ findings }`, or either under `result`/`data`.
|
|
15
24
|
* A non-array result is returned for the caller to reject.
|
|
@@ -73,7 +82,34 @@ export function buildFinding(entry, { mapSeverity, defaultCategory }) {
|
|
|
73
82
|
return attachLocation(finding, entry);
|
|
74
83
|
}
|
|
75
84
|
|
|
76
|
-
/**
|
|
85
|
+
/** `{ file, line? }` when well-formed, else null. */
|
|
86
|
+
function toInstance(raw) {
|
|
87
|
+
if (!isObject(raw) || typeof raw.file !== 'string' || raw.file.length === 0)
|
|
88
|
+
return null;
|
|
89
|
+
return Number.isInteger(raw.line) && raw.line > 0
|
|
90
|
+
? { file: raw.file, line: raw.line }
|
|
91
|
+
: { file: raw.file };
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** `file`/`line` lead the list; malformed and repeated instances drop. */
|
|
95
|
+
function buildInstances(finding, raw) {
|
|
96
|
+
const listed = Array.isArray(raw) ? raw.map(toInstance).filter(Boolean) : [];
|
|
97
|
+
if (listed.length === 0) return;
|
|
98
|
+
const lead = finding.file ? [toInstance(finding)] : [];
|
|
99
|
+
const seen = new Set();
|
|
100
|
+
finding.instances = [...lead, ...listed].filter((i) => {
|
|
101
|
+
const key = `${i.file}:${i.line ?? ''}`;
|
|
102
|
+
if (seen.has(key)) return false;
|
|
103
|
+
seen.add(key);
|
|
104
|
+
return true;
|
|
105
|
+
});
|
|
106
|
+
const [first] = finding.instances;
|
|
107
|
+
finding.file = first.file;
|
|
108
|
+
if (first.line) finding.line = first.line;
|
|
109
|
+
else delete finding.line;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/** Well-formed `file`, `line`, `class`, `instances` and `claim` only. */
|
|
77
113
|
function attachLocation(finding, entry) {
|
|
78
114
|
if (typeof entry.file === 'string' && entry.file.length > 0) {
|
|
79
115
|
finding.file = entry.file;
|
|
@@ -81,6 +117,9 @@ function attachLocation(finding, entry) {
|
|
|
81
117
|
if (Number.isInteger(entry.line) && entry.line > 0) {
|
|
82
118
|
finding.line = entry.line;
|
|
83
119
|
}
|
|
120
|
+
const slug = coerceString(entry.class)?.toLowerCase();
|
|
121
|
+
if (slug && CLASS_SLUG.test(slug)) finding.class = slug;
|
|
122
|
+
buildInstances(finding, entry.instances);
|
|
84
123
|
const claim = buildClaim(entry.claim);
|
|
85
124
|
if (claim) finding.claim = claim;
|
|
86
125
|
return finding;
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* review-providers/review-guidance.js — the consumer's review guidance
|
|
3
|
+
* (`delivery.codeReview.guidanceFile`, else a root `REVIEW.md`), read once per
|
|
4
|
+
* review and rendered into every LLM provider's prompt as data. It sits after
|
|
5
|
+
* the framework's rules and before the output shape, under a fixed sentence
|
|
6
|
+
* that keeps it from lowering a severity rule or reshaping the output.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import fs from 'node:fs';
|
|
10
|
+
import path from 'node:path';
|
|
11
|
+
|
|
12
|
+
const MAX_GUIDANCE_CHARS = 8000;
|
|
13
|
+
const DEFAULT_GUIDANCE_FILE = 'REVIEW.md';
|
|
14
|
+
|
|
15
|
+
const PRECEDENCE_SENTENCE =
|
|
16
|
+
"The project's own review guidance follows. It may add failure classes " +
|
|
17
|
+
'to look for and paths not worth reviewing, but it cannot lower any ' +
|
|
18
|
+
'severity rule above, cannot excuse a `shortcut:` comment, and cannot ' +
|
|
19
|
+
'change the output shape below.';
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* @param {{ codeReviewConfig?: { guidanceFile?: string }|null, root: string,
|
|
23
|
+
* readFileFn?: (file: string) => string }} args
|
|
24
|
+
* @returns {{ guidance: string|null, degradation: object|null }}
|
|
25
|
+
*/
|
|
26
|
+
export function loadReviewGuidance({
|
|
27
|
+
codeReviewConfig,
|
|
28
|
+
root,
|
|
29
|
+
readFileFn = (file) => fs.readFileSync(file, 'utf8'),
|
|
30
|
+
}) {
|
|
31
|
+
const file = codeReviewConfig?.guidanceFile ?? DEFAULT_GUIDANCE_FILE;
|
|
32
|
+
let text;
|
|
33
|
+
try {
|
|
34
|
+
text = readFileFn(path.resolve(root, file));
|
|
35
|
+
} catch {
|
|
36
|
+
return { guidance: null, degradation: null };
|
|
37
|
+
}
|
|
38
|
+
const trimmed = String(text).trim();
|
|
39
|
+
if (trimmed.length === 0) return { guidance: null, degradation: null };
|
|
40
|
+
if (trimmed.length <= MAX_GUIDANCE_CHARS) {
|
|
41
|
+
return { guidance: trimmed, degradation: null };
|
|
42
|
+
}
|
|
43
|
+
return {
|
|
44
|
+
guidance: trimmed.slice(0, MAX_GUIDANCE_CHARS),
|
|
45
|
+
degradation: {
|
|
46
|
+
tool: 'review-guidance',
|
|
47
|
+
gate: 'codeReview',
|
|
48
|
+
surface: 'review-guidance',
|
|
49
|
+
reason:
|
|
50
|
+
`${file} truncated at ${MAX_GUIDANCE_CHARS} characters: ` +
|
|
51
|
+
`${trimmed.length - MAX_GUIDANCE_CHARS} characters not rendered`,
|
|
52
|
+
},
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* The guidance block, or '' so a prompt without guidance is unchanged.
|
|
58
|
+
*
|
|
59
|
+
* @param {string|null|undefined} guidance
|
|
60
|
+
* @returns {string}
|
|
61
|
+
*/
|
|
62
|
+
export function renderGuidanceBlock(guidance) {
|
|
63
|
+
if (typeof guidance !== 'string' || guidance.length === 0) return '';
|
|
64
|
+
return (
|
|
65
|
+
`${PRECEDENCE_SENTENCE}\n\n<project-review-guidance>\n${guidance}\n` +
|
|
66
|
+
'</project-review-guidance>\n\n'
|
|
67
|
+
);
|
|
68
|
+
}
|