mandrel 2.106.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.
Files changed (35) hide show
  1. package/.agents/docs/configuration.md +3 -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/lib/audit-suite/selector.js +13 -5
  5. package/.agents/scripts/lib/audit-suite/sensitive-paths.js +39 -0
  6. package/.agents/scripts/lib/config-settings-schema-quality.js +31 -0
  7. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  8. package/.agents/scripts/lib/observability/metrics-ledger.js +1 -1
  9. package/.agents/scripts/lib/observability/review-dispositions.js +208 -0
  10. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  11. package/.agents/scripts/lib/orchestration/code-review.js +77 -13
  12. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -0
  13. package/.agents/scripts/lib/orchestration/review-depth.js +9 -3
  14. package/.agents/scripts/lib/orchestration/review-history.js +182 -0
  15. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +22 -2
  16. package/.agents/scripts/lib/orchestration/review-providers/claim-grounding.js +5 -4
  17. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +12 -0
  18. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +15 -8
  19. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +26 -5
  20. package/.agents/scripts/lib/orchestration/review-providers/codex.js +4 -2
  21. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +357 -0
  22. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +53 -0
  23. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +85 -15
  24. package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +40 -1
  25. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +68 -0
  26. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +25 -10
  27. package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
  28. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +3 -0
  29. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +14 -2
  30. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +1 -0
  31. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +24 -1
  32. package/.agents/scripts/review-dispositions-report.js +129 -0
  33. package/.agents/workflows/helpers/code-review.md +53 -0
  34. package/docs/CHANGELOG.md +15 -0
  35. package/package.json +1 -1
@@ -48,7 +48,7 @@ export function planMetricsPath(epicId, config) {
48
48
  * @param {number} maxBytes
49
49
  * @returns {Promise<boolean>} true when a rotation happened.
50
50
  */
51
- async function rotateIfNeeded(filePath, incomingBytes, maxBytes) {
51
+ export async function rotateIfNeeded(filePath, incomingBytes, maxBytes) {
52
52
  let size = 0;
53
53
  try {
54
54
  size = (await fs.stat(filePath)).size;
@@ -0,0 +1,208 @@
1
+ /**
2
+ * review-dispositions.js — at land, what became of every finding the
3
+ * Story-scope review raised, appended to a local NDJSON ledger so a review
4
+ * prompt, provider or model change can be judged on fix and override rates.
5
+ * Records carry ids, provider, severity, class and disposition only: never a
6
+ * title, body, path or excerpt.
7
+ */
8
+
9
+ import fs from 'node:fs/promises';
10
+ import path from 'node:path';
11
+
12
+ import { anchorTempRoot, tempRootFrom } from '../config/temp-paths.js';
13
+ import { readReviewHistory } from '../orchestration/review-history.js';
14
+ import { MAX_LEDGER_BYTES, rotateIfNeeded } from './metrics-ledger.js';
15
+
16
+ export const DISPOSITIONS = [
17
+ 'fixed-on-branch',
18
+ 'open-at-merge',
19
+ 'overridden',
20
+ 'refuted-by-verifier',
21
+ 'downgraded-ungrounded',
22
+ ];
23
+
24
+ const LEDGER_BASENAME = 'review-dispositions.ndjson';
25
+
26
+ /** @param {object} [config] @returns {string} */
27
+ function ledgerPath(config) {
28
+ return path.join(anchorTempRoot(tempRootFrom(config)), LEDGER_BASENAME);
29
+ }
30
+
31
+ /** Precedence: overridden, then the final run's flags, then presence. */
32
+ function dispositionOf(id, final, overridden) {
33
+ if (overridden.has(id)) return 'overridden';
34
+ if (!final) return 'fixed-on-branch';
35
+ if (final.ungrounded) return 'downgraded-ungrounded';
36
+ if (final.unverified) return 'refuted-by-verifier';
37
+ return 'open-at-merge';
38
+ }
39
+
40
+ /** @param {object} run @returns {object[]} */
41
+ const runFindings = (run) => (Array.isArray(run?.findings) ? run.findings : []);
42
+
43
+ /**
44
+ * First occurrence and appearance count of every finding id.
45
+ *
46
+ * @param {object[][]} runs
47
+ * @returns {Map<string, { first: object, runs: number }>}
48
+ */
49
+ function firstSeen(runs) {
50
+ const byId = new Map();
51
+ for (const findings of runs) {
52
+ const seenHere = new Set();
53
+ for (const f of findings) {
54
+ if (!f?.id || seenHere.has(f.id)) continue;
55
+ seenHere.add(f.id);
56
+ const entry = byId.get(f.id) ?? { first: f, runs: 0 };
57
+ entry.runs += 1;
58
+ byId.set(f.id, entry);
59
+ }
60
+ }
61
+ return byId;
62
+ }
63
+
64
+ /**
65
+ * One entry per finding id ever raised; provider and severity as first raised.
66
+ *
67
+ * @param {import('../orchestration/review-history.js').ReviewHistory} history
68
+ */
69
+ function deriveDispositions(history) {
70
+ const runs = history.runs.map(runFindings);
71
+ const finalRun = new Map((runs.at(-1) ?? []).map((f) => [f.id, f]));
72
+ const overridden = new Set(history.overridden);
73
+ return [...firstSeen(runs)].map(([id, entry]) => ({
74
+ findingId: id,
75
+ provider: entry.first.provider ?? null,
76
+ severity: entry.first.severity ?? null,
77
+ class: entry.first.class ?? null,
78
+ disposition: dispositionOf(id, finalRun.get(id), overridden),
79
+ runs: entry.runs,
80
+ }));
81
+ }
82
+
83
+ /** @param {string} filePath @returns {Promise<object[]>} */
84
+ async function readLedgerFile(filePath) {
85
+ let text;
86
+ try {
87
+ text = await fs.readFile(filePath, 'utf8');
88
+ } catch {
89
+ return [];
90
+ }
91
+ return text.split('\n').flatMap((line) => {
92
+ try {
93
+ return line ? [JSON.parse(line)] : [];
94
+ } catch {
95
+ return [];
96
+ }
97
+ });
98
+ }
99
+
100
+ /**
101
+ * Every record in the ledger and its rotated generation.
102
+ *
103
+ * @param {{ config?: object, since?: string|null }} [opts] - `since` keeps
104
+ * records whose `ts` is on or after that ISO date.
105
+ * @returns {Promise<object[]>}
106
+ */
107
+ export async function readDispositions({ config, since = null } = {}) {
108
+ const file = ledgerPath(config);
109
+ const records = [
110
+ ...(await readLedgerFile(`${file}.1`)),
111
+ ...(await readLedgerFile(file)),
112
+ ];
113
+ return since ? records.filter((r) => String(r.ts) >= since) : records;
114
+ }
115
+
116
+ /**
117
+ * Append one record per finding the Story's reviews raised. Idempotent per
118
+ * Story; throws on an fs failure (the post-land step owns best-effort).
119
+ *
120
+ * @param {{ storyId: number, config?: object, now?: () => string,
121
+ * progress?: (tag: string, msg: string) => void }} args
122
+ * @returns {Promise<{ ok: true, appended: number, detail: string|null }>}
123
+ */
124
+ export async function recordStoryDispositions({
125
+ storyId,
126
+ config,
127
+ now = () => new Date().toISOString(),
128
+ progress,
129
+ }) {
130
+ const history = readReviewHistory(storyId, { config });
131
+ if (history.runs.length === 0) {
132
+ return { ok: true, appended: 0, detail: null };
133
+ }
134
+ const existing = await readDispositions({ config });
135
+ if (existing.some((r) => r.storyId === storyId)) {
136
+ return { ok: true, appended: 0, detail: 'already recorded' };
137
+ }
138
+ const ts = now();
139
+ const lines = deriveDispositions(history)
140
+ .map((d) => {
141
+ const reason =
142
+ d.disposition === 'overridden' && history.overrideReason
143
+ ? { reason: history.overrideReason }
144
+ : {};
145
+ return JSON.stringify({ v: 1, ts, storyId, ...d, ...reason });
146
+ })
147
+ .join('\n');
148
+ const chunk = `${lines}\n`;
149
+ const file = ledgerPath(config);
150
+ await fs.mkdir(path.dirname(file), { recursive: true });
151
+ await rotateIfNeeded(file, Buffer.byteLength(chunk), MAX_LEDGER_BYTES);
152
+ await fs.appendFile(file, chunk, 'utf8');
153
+ const appended = lines.split('\n').length;
154
+ progress?.('POST-LAND', `📒 Recorded ${appended} review disposition(s).`);
155
+ return { ok: true, appended, detail: null };
156
+ }
157
+
158
+ /** @param {object[]} records */
159
+ function tally(records) {
160
+ const counts = Object.fromEntries(DISPOSITIONS.map((d) => [d, 0]));
161
+ for (const r of records) {
162
+ if (r.disposition in counts) counts[r.disposition] += 1;
163
+ }
164
+ const total = records.length;
165
+ const rate = (n, of) => (of === 0 ? null : n / of);
166
+ const criticals = records.filter((r) => r.severity === 'critical');
167
+ const falseBlockers = criticals.filter((r) =>
168
+ ['overridden', 'refuted-by-verifier', 'downgraded-ungrounded'].includes(
169
+ r.disposition,
170
+ ),
171
+ ).length;
172
+ return {
173
+ total,
174
+ counts,
175
+ rates: Object.fromEntries(
176
+ DISPOSITIONS.map((d) => [d, rate(counts[d], total)]),
177
+ ),
178
+ precision: rate(counts['fixed-on-branch'] + counts['open-at-merge'], total),
179
+ falseBlocker: rate(falseBlockers, criticals.length),
180
+ };
181
+ }
182
+
183
+ /** @param {object[]} records @param {string} key */
184
+ function groupTally(records, key) {
185
+ const groups = new Map();
186
+ for (const r of records) {
187
+ const k = String(r[key] ?? 'unknown');
188
+ groups.set(k, [...(groups.get(k) ?? []), r]);
189
+ }
190
+ return Object.fromEntries(
191
+ [...groups]
192
+ .sort(([a], [b]) => a.localeCompare(b))
193
+ .map(([k, rs]) => [k, tally(rs)]),
194
+ );
195
+ }
196
+
197
+ /**
198
+ * Counts and rates of each disposition, overall, per provider and per severity.
199
+ *
200
+ * @param {object[]} records
201
+ */
202
+ export function summarizeDispositions(records) {
203
+ return {
204
+ overall: tally(records),
205
+ byProvider: groupTally(records, 'provider'),
206
+ bySeverity: groupTally(records, 'severity'),
207
+ };
208
+ }
@@ -72,6 +72,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
72
72
  'resolve-doc-tiers.js',
73
73
  'resolve-stories.js',
74
74
  'resync-status-column.js',
75
+ 'review-dispositions-report.js',
75
76
  'run-tests.js',
76
77
  'single-story-close.js',
77
78
  'single-story-confirm-merge.js',
@@ -5,20 +5,29 @@
5
5
  * never post), and report `halted` on any surviving critical finding.
6
6
  */
7
7
 
8
+ import picomatch from 'picomatch';
8
9
  import { hasSurvivingCritical } from '../audit-suite/findings.js';
9
10
  import { resolveConfig } from '../config-resolver.js';
11
+ import { PROJECT_ROOT } from '../project-root.js';
10
12
  import { computeChangeSet } from './change-set.js';
11
13
  import { remoteBaseRef } from './review-base-ref.js';
12
14
  import { deriveChangeLevel, resolveDepth } from './review-depth.js';
13
- import { groundFindings } from './review-providers/claim-grounding.js';
15
+ import {
16
+ appendReviewRun,
17
+ markRepeats,
18
+ readReviewHistory,
19
+ } from './review-history.js';
20
+ import { vetFindings } from './review-providers/critical-verifier.js';
14
21
  import {
15
22
  collectProviderDegradations,
16
23
  degradationEnvelope,
17
24
  } from './review-providers/degraded-gates.js';
25
+ import { findingInstances } from './review-providers/finding-identity.js';
18
26
  import {
19
27
  countBySeverity,
20
28
  renderFindings,
21
29
  } from './review-providers/findings-renderer.js';
30
+ import { loadReviewGuidance } from './review-providers/review-guidance.js';
22
31
  import { createReviewProvider } from './review-providers/review-provider-factory.js';
23
32
  import { upsertStructuredComment } from './ticketing.js';
24
33
 
@@ -102,6 +111,8 @@ function resolveStoryScope(opts, config) {
102
111
  * createReviewProviderFn?: typeof createReviewProvider,
103
112
  * upsertCommentFn?: typeof upsertStructuredComment,
104
113
  * renderFindingsFn?: typeof renderFindings,
114
+ * verifier?: { spawnFn?: Function, probeFn?: Function, gitSpawnFn?: Function },
115
+ * historyDeps?: { config?: object, fsImpl?: object },
105
116
  * deferPost?: boolean,
106
117
  * }} opts
107
118
  * @returns {Promise<{
@@ -283,6 +294,49 @@ function scoreFindings(findings, providerName) {
283
294
  };
284
295
  }
285
296
 
297
+ /**
298
+ * Drop findings whose file, or every instance file, matches a `skipPaths`
299
+ * glob. Config only: guidance prose cannot reach this.
300
+ */
301
+ function applySkipPaths(findings, skipPaths) {
302
+ if (!Array.isArray(skipPaths) || skipPaths.length === 0) {
303
+ return { findings, skipped: 0 };
304
+ }
305
+ const isSkipped = picomatch(skipPaths, { dot: true });
306
+ const kept = findings.filter((f) => {
307
+ const files = findingInstances(f).map((i) => i.file);
308
+ return !(files.length > 0 && files.every((file) => isSkipped(file)));
309
+ });
310
+ return { findings: kept, skipped: findings.length - kept.length };
311
+ }
312
+
313
+ /**
314
+ * The Story's review history seam. An injected review provider runs without
315
+ * one unless `opts.historyDeps` is given, so tests never share a history.
316
+ */
317
+ function resolveHistoryDeps(opts, config) {
318
+ if (opts.historyDeps) return opts.historyDeps;
319
+ return opts.reviewProvider ? null : { config };
320
+ }
321
+
322
+ /** Mark the findings an earlier run of this Story already raised. */
323
+ function markAgainstHistory(findings, ticketId, historyDeps) {
324
+ if (!historyDeps) return findings;
325
+ return markRepeats(findings, readReviewHistory(ticketId, historyDeps));
326
+ }
327
+
328
+ /** Best-effort: a history write failure never fails the review. */
329
+ function recordRun({ ticketId, headRef, findings, historyDeps, logger }) {
330
+ if (!historyDeps) return;
331
+ try {
332
+ appendReviewRun(ticketId, { headSha: headRef, findings }, historyDeps);
333
+ } catch (err) {
334
+ logger?.warn?.(
335
+ `[code-review] Could not record the review history: ${err?.message ?? err}`,
336
+ );
337
+ }
338
+ }
339
+
286
340
  async function executeReviewPipeline({ opts, config, envelope }) {
287
341
  const {
288
342
  provider,
@@ -303,13 +357,14 @@ async function executeReviewPipeline({ opts, config, envelope }) {
303
357
  `[code-review] Running ${providerName} adapter for Story #${ticketId} (${baseRef}...${headRef})...`,
304
358
  );
305
359
 
306
- const reviewInput = buildReviewInput({
307
- opts,
308
- scope,
309
- ticketId,
310
- baseRef,
311
- headRef,
360
+ const guidance = loadReviewGuidance({
361
+ codeReviewConfig,
362
+ root: opts.cwd ?? PROJECT_ROOT,
312
363
  });
364
+ const reviewInput = {
365
+ ...buildReviewInput({ opts, scope, ticketId, baseRef, headRef }),
366
+ guidance: guidance.guidance,
367
+ };
313
368
 
314
369
  const rawFindings = await reviewProvider.runReview(reviewInput);
315
370
  if (!Array.isArray(rawFindings)) {
@@ -325,14 +380,19 @@ async function executeReviewPipeline({ opts, config, envelope }) {
325
380
  );
326
381
 
327
382
  // Degraded gates ride beside the findings, never inside them.
328
- const { findings, degradations } = groundFindings({
383
+ const vetted = await vetFindings({
329
384
  findings: rawFindings,
330
- headRef,
331
- baseRef,
332
- cwd: opts.cwd,
333
- degradations: await collectProviderDegradations(reviewProvider, logger),
334
- gitSpawnFn: opts.gitSpawnFn,
385
+ reviewInput,
386
+ opts,
387
+ degradations: [
388
+ ...(await collectProviderDegradations(reviewProvider, logger)),
389
+ ...(guidance.degradation ? [guidance.degradation] : []),
390
+ ],
335
391
  });
392
+ const { degradations, verification } = vetted;
393
+ const skip = applySkipPaths(vetted.findings, codeReviewConfig?.skipPaths);
394
+ const historyDeps = resolveHistoryDeps(opts, config);
395
+ const findings = markAgainstHistory(skip.findings, ticketId, historyDeps);
336
396
  const scored = scoreFindings(findings, providerName);
337
397
  const report = renderFindingsFn({
338
398
  scope,
@@ -343,7 +403,10 @@ async function executeReviewPipeline({ opts, config, envelope }) {
343
403
  provider: providerName,
344
404
  promptMessages,
345
405
  degradations,
406
+ verification,
407
+ skipped: skip.skipped,
346
408
  });
409
+ recordRun({ ticketId, headRef, findings, historyDeps, logger });
347
410
 
348
411
  const { posted, postedCommentId } = await postUnlessDeferred(opts, {
349
412
  upsertCommentFn,
@@ -365,6 +428,7 @@ async function executeReviewPipeline({ opts, config, envelope }) {
365
428
  halted: scored.halted,
366
429
  criticalByProvider: scored.criticalByProvider,
367
430
  ...degradationEnvelope(degradations),
431
+ verification,
368
432
  blockerReason: scored.blockerReason,
369
433
  };
370
434
  }
@@ -115,6 +115,7 @@ export function buildReviewDeposit({
115
115
  report: result.report ?? '',
116
116
  degraded: !!result.degraded,
117
117
  degradations: Array.isArray(result.degradations) ? result.degradations : [],
118
+ verification: result.verification ?? null,
118
119
  blockerReason: result.blockerReason ?? null,
119
120
  };
120
121
  }
@@ -140,6 +141,7 @@ export function depositAsComputedReview(deposit) {
140
141
  criticalByProvider: deposit.criticalByProvider,
141
142
  degraded: deposit.degraded,
142
143
  degradations: deposit.degradations,
144
+ verification: deposit.verification ?? null,
143
145
  blockerReason: deposit.blockerReason,
144
146
  },
145
147
  };
@@ -16,8 +16,9 @@ export const DEFAULT_DIFF_WIDTH = Object.freeze({
16
16
  });
17
17
 
18
18
  /**
19
- * `high` when the changed files hit a `sensitivePaths` class in
20
- * `audit-rules.json` — this is what keeps a narrow auth or migration diff
19
+ * `high` when the changed files hit a `sensitivePaths` class (the shipped
20
+ * `audit-rules.json` classes merged with `delivery.codeReview.sensitivePaths`)
21
+ * — this is what keeps a narrow auth or migration diff
21
22
  * deep. Single source of the level for review depth and dispatch routing
22
23
  * (predicted footprint vs actual diff). `null` on an empty set or unreadable
23
24
  * manifest; consumers treat `null` as the more thorough posture. Never throws.
@@ -25,6 +26,7 @@ export const DEFAULT_DIFF_WIDTH = Object.freeze({
25
26
  * @param {{
26
27
  * changedFiles?: string[]|null,
27
28
  * injectedRules?: object,
29
+ * injectedConfig?: object,
28
30
  * selectSensitivePathClassesFn?: typeof selectSensitivePathClasses,
29
31
  * }} [input]
30
32
  * @returns {{ level: ChangeLevel|null, classes: string[] }}
@@ -40,7 +42,11 @@ export function deriveChangeLevel(input = {}) {
40
42
  input.selectSensitivePathClassesFn ?? selectSensitivePathClasses;
41
43
  let classes;
42
44
  try {
43
- classes = select({ changedFiles, injectedRules: input.injectedRules });
45
+ classes = select({
46
+ changedFiles,
47
+ injectedRules: input.injectedRules,
48
+ injectedConfig: input.injectedConfig,
49
+ });
44
50
  } catch {
45
51
  // An unreadable/invalid manifest is not evidence the change is safe.
46
52
  return { level: null, classes: [] };
@@ -0,0 +1,182 @@
1
+ /**
2
+ * review-history.js — every Story-scope review run of a Story and the
3
+ * CRITICAL ids an operator overrode, beside the held-review deposit. A re-review
4
+ * reads it to mark a finding it already raised as a repeat; the Story temp
5
+ * purge reaps it with the deposit.
6
+ *
7
+ * @typedef {import('./review-providers/types.js').Finding} Finding
8
+ * @typedef {{ id: string, severity: string, provider: string|null,
9
+ * class: string|null, instances: { file: string, line?: number }[],
10
+ * ungrounded?: string, unverified?: string }} HistoryFinding
11
+ * @typedef {{ runs: { headSha: string, findings: HistoryFinding[] }[],
12
+ * overridden: string[], overrideReason?: string }} ReviewHistory
13
+ */
14
+
15
+ import nodeFs from 'node:fs';
16
+ import path from 'node:path';
17
+
18
+ import { storyReviewDepositPath } from '../config/temp-paths.js';
19
+ import { redactErrorMessage } from '../error-redactor.js';
20
+ import { writeFileAtomic } from '../util/atomic-write.js';
21
+ import {
22
+ findingId,
23
+ findingInstances,
24
+ } from './review-providers/finding-identity.js';
25
+
26
+ const KIND = 'story-review-history';
27
+ /** An instance this many lines from an earlier one is the same location. */
28
+ const LINE_WINDOW = 10;
29
+ /** Same bound as the `review-block-overridden` friction signal. */
30
+ const OVERRIDE_REASON_LIMIT = 500;
31
+
32
+ /**
33
+ * @param {number} storyId
34
+ * @param {object} [config]
35
+ * @returns {string}
36
+ */
37
+ function historyPath(storyId, config) {
38
+ return path.join(
39
+ path.dirname(storyReviewDepositPath(storyId, config)),
40
+ `story-review-history-${storyId}.json`,
41
+ );
42
+ }
43
+
44
+ /** @param {string} reason */
45
+ const redactReason = (reason) =>
46
+ redactErrorMessage(reason.slice(0, OVERRIDE_REASON_LIMIT));
47
+
48
+ /** @param {unknown} reason @param {(r: string) => string} [map] */
49
+ const reasonField = (reason, map = (r) => r) =>
50
+ typeof reason === 'string' ? { overrideReason: map(reason) } : {};
51
+
52
+ /**
53
+ * @param {number} storyId
54
+ * @param {{ config?: object, fsImpl?: typeof nodeFs }} [deps]
55
+ * @returns {ReviewHistory} empty when absent or malformed.
56
+ */
57
+ export function readReviewHistory(storyId, { config, fsImpl = nodeFs } = {}) {
58
+ try {
59
+ const record = JSON.parse(
60
+ fsImpl.readFileSync(historyPath(storyId, config), 'utf8'),
61
+ );
62
+ if (record?.kind === KIND && Array.isArray(record.runs)) {
63
+ return {
64
+ runs: record.runs,
65
+ overridden: Array.isArray(record.overridden) ? record.overridden : [],
66
+ ...reasonField(record.overrideReason),
67
+ };
68
+ }
69
+ } catch {
70
+ // Absent or unreadable: no earlier runs.
71
+ }
72
+ return { runs: [], overridden: [] };
73
+ }
74
+
75
+ /**
76
+ * @param {number} storyId
77
+ * @param {(history: ReviewHistory) => ReviewHistory} update
78
+ * @param {{ config?: object, fsImpl?: typeof nodeFs }} [deps]
79
+ */
80
+ function updateReviewHistory(storyId, update, deps = {}) {
81
+ const next = update(readReviewHistory(storyId, deps));
82
+ writeFileAtomic(
83
+ historyPath(storyId, deps.config),
84
+ `${JSON.stringify({ kind: KIND, storyId, ...next }, null, 2)}\n`,
85
+ { fsImpl: deps.fsImpl ?? nodeFs },
86
+ );
87
+ }
88
+
89
+ /** @param {Finding} f @returns {HistoryFinding} */
90
+ function toHistoryFinding(f) {
91
+ return {
92
+ id: findingId(f),
93
+ severity: f.severity,
94
+ provider: f.provider ?? null,
95
+ class: f.class ?? null,
96
+ instances: findingInstances(f),
97
+ ...(f.ungrounded ? { ungrounded: f.ungrounded } : {}),
98
+ ...(f.unverified ? { unverified: f.unverified } : {}),
99
+ };
100
+ }
101
+
102
+ /**
103
+ * @param {number} storyId
104
+ * @param {{ headSha: string, findings: Finding[] }} run
105
+ * @param {{ config?: object, fsImpl?: typeof nodeFs }} [deps]
106
+ */
107
+ export function appendReviewRun(storyId, { headSha, findings }, deps) {
108
+ updateReviewHistory(
109
+ storyId,
110
+ (h) => ({
111
+ ...h,
112
+ runs: [...h.runs, { headSha, findings: findings.map(toHistoryFinding) }],
113
+ }),
114
+ deps,
115
+ );
116
+ }
117
+
118
+ /**
119
+ * @param {number} storyId
120
+ * @param {string[]} ids - the overridden CRITICALs.
121
+ * @param {{ config?: object, fsImpl?: typeof nodeFs, reason?: string }} [deps]
122
+ * `reason` is stored redacted and clipped.
123
+ */
124
+ export function recordOverriddenIds(storyId, ids, deps) {
125
+ updateReviewHistory(
126
+ storyId,
127
+ (h) => ({
128
+ ...h,
129
+ overridden: [...new Set([...h.overridden, ...ids])],
130
+ ...reasonField(deps?.reason, redactReason),
131
+ }),
132
+ deps,
133
+ );
134
+ }
135
+
136
+ /** Same file and within the line window, or both lineless. */
137
+ function sameLocation(a, b) {
138
+ if (a.file !== b.file) return false;
139
+ if (!Number.isInteger(a.line) || !Number.isInteger(b.line)) {
140
+ return !Number.isInteger(a.line) && !Number.isInteger(b.line);
141
+ }
142
+ return Math.abs(a.line - b.line) <= LINE_WINDOW;
143
+ }
144
+
145
+ /** @param {{ file: string, line?: number }[]} now @param {object[]} before */
146
+ function overlaps(now, before) {
147
+ if (now.length === 0 && before.length === 0) return true;
148
+ return now.some((a) => before.some((b) => sameLocation(a, b)));
149
+ }
150
+
151
+ /**
152
+ * Mark each finding an earlier run raised (same id, overlapping location) as
153
+ * a `repeat`. A repeat of an overridden CRITICAL is downgraded so it does not
154
+ * halt again; any other repeat keeps its severity.
155
+ *
156
+ * @param {Finding[]} findings
157
+ * @param {ReviewHistory} history
158
+ * @returns {Finding[]}
159
+ */
160
+ export function markRepeats(findings, history) {
161
+ const earlier = history.runs.flatMap((r) =>
162
+ Array.isArray(r?.findings) ? r.findings : [],
163
+ );
164
+ const overridden = new Set(history.overridden);
165
+ return findings.map((f) => {
166
+ const id = findingId(f);
167
+ const instances = findingInstances(f);
168
+ const seen = earlier.some(
169
+ (e) => e?.id === id && overlaps(instances, e.instances ?? []),
170
+ );
171
+ if (!seen) return f;
172
+ if (f.severity === 'critical' && overridden.has(id)) {
173
+ return {
174
+ ...f,
175
+ severity: 'suggestion',
176
+ ungrounded: 'overridden earlier',
177
+ repeat: true,
178
+ };
179
+ }
180
+ return { ...f, repeat: true };
181
+ });
182
+ }
@@ -27,8 +27,16 @@ const DECLARATION_PATTERNS = Object.freeze([
27
27
  ]);
28
28
  const EXPORT_LIST = /\bexport\s*\{([^}]*)\}/g;
29
29
  const NEW_FILE_HEADER = /^\+\+\+ b\/(.+)$/;
30
+ /** `+++ b/` follows `--- a/`, so a deletion keeps its old path. */
31
+ const FILE_HEADER = /^(?:\+\+\+ b|--- a)\//;
30
32
  /** Comment prose ("the function returns…") declares nothing. */
31
33
  const COMMENT_LINE = /^\s*(?:\/\/|\/\*|\*)/;
34
+ /** Docs and data hunks are prose: "the class or function…" declares nothing. */
35
+ const PROSE_FILE =
36
+ /\.(?:md|mdx|markdown|txt|rst|json|jsonc|ya?ml|toml|lock|csv|html|svg)$/i;
37
+ /** A string runs to its close quote, or to end of line when unclosed. */
38
+ const STRING_LITERAL = /(['"`])(?:\\.|(?!\1)[^\\])*(?:\1|$)/g;
39
+ const INLINE_COMMENT = /\/\*.*?\*\/|\/\/.*$/g;
32
40
 
33
41
  /** `export { A, B as C }` exports `A` and `C`. */
34
42
  function exportListNames(list) {
@@ -62,27 +70,39 @@ function scanDiff(diff) {
62
70
  const found = new Set();
63
71
  const files = [];
64
72
  let inHunk = false;
73
+ let prose = false;
65
74
  for (const line of diff.split('\n')) {
66
75
  if (line.startsWith('diff --git ')) {
67
76
  inHunk = false;
77
+ prose = false;
68
78
  continue;
69
79
  }
70
80
  if (!inHunk) {
71
81
  const header = NEW_FILE_HEADER.exec(line);
72
82
  if (header && !files.includes(header[1])) files.push(header[1]);
83
+ if (FILE_HEADER.test(line)) prose = PROSE_FILE.test(line);
73
84
  if (line.startsWith('@@')) inHunk = true;
74
85
  continue;
75
86
  }
87
+ if (prose) continue;
76
88
  for (const name of symbolsOnLine(changedCode(line))) found.add(name);
77
89
  }
78
90
  return { found, files };
79
91
  }
80
92
 
81
- /** The code of a `+`/`-` hunk line; `''` for context and comment-only lines. */
93
+ /**
94
+ * The code of a `+`/`-` hunk line with strings blanked, then comments cut
95
+ * (that order keeps a `//` inside a URL string); `''` for context and
96
+ * comment-only lines.
97
+ */
82
98
  function changedCode(line) {
83
99
  const body = line.slice(1);
84
100
  if (!/^[+-]/.test(line) || COMMENT_LINE.test(body)) return '';
85
- return body;
101
+ return withoutProse(body);
102
+ }
103
+
104
+ function withoutProse(code) {
105
+ return code.replace(STRING_LITERAL, "''").replace(INLINE_COMMENT, '');
86
106
  }
87
107
 
88
108
  /** Longest first: short names grep noisily. */
@@ -57,6 +57,8 @@ export function buildClaim(raw) {
57
57
  return path ? { kind: raw.kind, symbol, path } : { kind: raw.kind, symbol };
58
58
  }
59
59
 
60
+ const NOT_BLOCKING = ['ungrounded', 'unverified'];
61
+
60
62
  /**
61
63
  * Report lines saying why a finding did not block, or was reviewed blind.
62
64
  *
@@ -64,10 +66,9 @@ export function buildClaim(raw) {
64
66
  * @returns {string[]}
65
67
  */
66
68
  export function groundingNotes(finding) {
67
- const notes = [];
68
- if (finding.ungrounded) {
69
- notes.push(`_Not blocking: ungrounded — ${finding.ungrounded}._`);
70
- }
69
+ const notes = NOT_BLOCKING.filter((key) => finding[key]).map(
70
+ (key) => `_Not blocking: ${key} — ${finding[key]}._`,
71
+ );
71
72
  if (finding.context) notes.push(`_Context: ${finding.context}._`);
72
73
  return notes;
73
74
  }