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.
- 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/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 -13
- 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 +5 -4
- package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +12 -0
- package/.agents/scripts/lib/orchestration/review-providers/code-review.js +15 -8
- 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 +6 -0
- 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/review-dispositions-report.js +129 -0
- package/.agents/workflows/helpers/code-review.md +53 -0
- package/docs/CHANGELOG.md +15 -0
- package/package.json +1 -1
|
@@ -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
|
+
}
|
|
@@ -11,9 +11,10 @@
|
|
|
11
11
|
|
|
12
12
|
import { spawnSync } from 'node:child_process';
|
|
13
13
|
import { resolveAgentrcRoot } from '../../config/git-roots.js';
|
|
14
|
-
import { parseProviderFindings } from './parse-findings.js';
|
|
14
|
+
import { BUG_CLASS_RULE, parseProviderFindings } from './parse-findings.js';
|
|
15
15
|
import { PROVIDER_SEVERITY_MAP } from './provider-severity.js';
|
|
16
16
|
import { renderDepthDirective } from './review-depth.js';
|
|
17
|
+
import { renderGuidanceBlock } from './review-guidance.js';
|
|
17
18
|
|
|
18
19
|
export const SECURITY_REVIEW_REMEDIATIONS = Object.freeze({
|
|
19
20
|
install:
|
|
@@ -87,17 +88,23 @@ export function parseSecurityReviewFindings(rawStdout) {
|
|
|
87
88
|
});
|
|
88
89
|
}
|
|
89
90
|
|
|
90
|
-
/**
|
|
91
|
+
/**
|
|
92
|
+
* Wraps `/security-review`: severity rules, then the class rule and any
|
|
93
|
+
* project guidance, then the JSON-emit instruction.
|
|
94
|
+
*/
|
|
91
95
|
const SECURITY_REVIEW_INVOKE_PROMPT =
|
|
92
96
|
'Run /security-review against the diff `{baseRef}`...`{headRef}` ' +
|
|
93
|
-
'for {scopeLabel} #{ticketId}. {depthDirective}
|
|
94
|
-
'ONLY a JSON array of findings on stdout with this exact shape:\n\n' +
|
|
95
|
-
'```\n[{"severity":"critical|high|medium|suggestion","title":"...",' +
|
|
96
|
-
'"body":"...","file":"...","line":1,"category":"security"}]\n```\n\n' +
|
|
97
|
+
'for {scopeLabel} #{ticketId}. {depthDirective}\n\n' +
|
|
97
98
|
'Use severity "critical" for blockers (must fix before merge), ' +
|
|
98
99
|
'"high" for material risks, "medium" for issues worth fixing, and ' +
|
|
99
|
-
|
|
100
|
-
'
|
|
100
|
+
`"suggestion" for advisory notes. ${BUG_CLASS_RULE}\n\n` +
|
|
101
|
+
'{guidance}' +
|
|
102
|
+
'After the review, emit ONLY a JSON array of findings on stdout with ' +
|
|
103
|
+
'this exact shape:\n\n' +
|
|
104
|
+
'```\n[{"severity":"critical|high|medium|suggestion","title":"...",' +
|
|
105
|
+
'"body":"...","file":"...","line":1,"category":"security",' +
|
|
106
|
+
'"class":"...","instances":[{"file":"...","line":1}]}]\n```\n\n' +
|
|
107
|
+
'Emit `[]` if you find nothing. No prose around the JSON.';
|
|
101
108
|
|
|
102
109
|
/**
|
|
103
110
|
* @param {ReviewInput} input
|
|
@@ -115,7 +122,8 @@ export function buildSecurityReviewPrompt(input) {
|
|
|
115
122
|
.replace('{headRef}', headRef)
|
|
116
123
|
.replace('{scopeLabel}', scopeLabel)
|
|
117
124
|
.replace('{ticketId}', ticketId)
|
|
118
|
-
.replace('{depthDirective}', renderDepthDirective(input?.depth))
|
|
125
|
+
.replace('{depthDirective}', renderDepthDirective(input?.depth))
|
|
126
|
+
.replace('{guidance}', () => renderGuidanceBlock(input?.guidance));
|
|
119
127
|
}
|
|
120
128
|
|
|
121
129
|
/**
|
|
@@ -197,7 +205,14 @@ export function createSecurityReviewProvider(deps = {}) {
|
|
|
197
205
|
`[security-review] Invoking /security-review for ${scope} #${ticketId} (${baseRef}...${headRef})...`,
|
|
198
206
|
);
|
|
199
207
|
|
|
200
|
-
const result = invokeFn({
|
|
208
|
+
const result = invokeFn({
|
|
209
|
+
scope,
|
|
210
|
+
ticketId,
|
|
211
|
+
baseRef,
|
|
212
|
+
headRef,
|
|
213
|
+
depth: input.depth,
|
|
214
|
+
guidance: input.guidance,
|
|
215
|
+
});
|
|
201
216
|
if (result.status !== 0) {
|
|
202
217
|
throw new Error(
|
|
203
218
|
`[security-review] claude --print /security-review exited with ` +
|
|
@@ -13,8 +13,12 @@
|
|
|
13
13
|
* @property {string=} category - e.g. 'security', 'lint'.
|
|
14
14
|
* @property {FindingClaim=} claim - Structured, checkable claim.
|
|
15
15
|
* @property {string=} ungrounded - Why a refuted critical was downgraded.
|
|
16
|
+
* @property {string=} unverified - The verifier's reason for refuting a critical.
|
|
16
17
|
* @property {string=} context - 'reviewed-with-truncated-context'.
|
|
17
18
|
* @property {string=} provider - Chain entry that raised it.
|
|
19
|
+
* @property {string=} class - Kebab-case bug class.
|
|
20
|
+
* @property {{ file: string, line?: number }[]=} instances - Every location; the first is `file`/`line`.
|
|
21
|
+
* @property {boolean=} repeat - An earlier run of this Story raised it.
|
|
18
22
|
*
|
|
19
23
|
* @typedef {object} FindingClaim
|
|
20
24
|
* @property {'path-absent'|'symbol-referenced'|'file-unchanged'} kind
|
|
@@ -32,6 +36,8 @@
|
|
|
32
36
|
* @property {string} headRef
|
|
33
37
|
* @property {ReviewDepth=} depth - Diff-derived thoroughness lever; LLM-backed
|
|
34
38
|
* providers MUST render it into their prompt. Absent → `standard`.
|
|
39
|
+
* @property {(string|null)=} guidance - Project review guidance; LLM-backed
|
|
40
|
+
* providers render it via `renderGuidanceBlock`.
|
|
35
41
|
*
|
|
36
42
|
* @typedef {object} ReviewProvider
|
|
37
43
|
* @property {(input: ReviewInput) => Promise<Finding[]>} runReview
|
|
@@ -200,6 +200,8 @@ export async function settleStoryScopeReview({
|
|
|
200
200
|
halted: !!result.halted,
|
|
201
201
|
severity: sev,
|
|
202
202
|
criticalByProvider: result.criticalByProvider,
|
|
203
|
+
// The override records these ids so a re-review does not halt on them.
|
|
204
|
+
findings: Array.isArray(result.findings) ? result.findings : [],
|
|
203
205
|
posted: result.posted,
|
|
204
206
|
postedCommentId: result.postedCommentId ?? null,
|
|
205
207
|
...degradationEnvelope(result.degradations),
|
|
@@ -228,6 +230,7 @@ export async function settleStoryScopeReview({
|
|
|
228
230
|
* skipped?: boolean,
|
|
229
231
|
* severity?: { critical: number, high: number, medium: number, suggestion: number },
|
|
230
232
|
* criticalByProvider?: Record<string, number>,
|
|
233
|
+
* findings?: Array<object>,
|
|
231
234
|
* posted?: boolean,
|
|
232
235
|
* postedCommentId?: number|null,
|
|
233
236
|
* degraded?: boolean,
|
|
@@ -12,6 +12,7 @@ import path from 'node:path';
|
|
|
12
12
|
|
|
13
13
|
import { gitSpawn as defaultGitSpawn } from '../../../git-utils.js';
|
|
14
14
|
import { Logger } from '../../../Logger.js';
|
|
15
|
+
import { recordStoryDispositions as defaultRecordStoryDispositions } from '../../../observability/review-dispositions.js';
|
|
15
16
|
import {
|
|
16
17
|
emitCloseRecoveredFriction as defaultEmitCloseRecoveredFriction,
|
|
17
18
|
emitRecoveredFrictionMarker as defaultEmitRecoveredFrictionMarker,
|
|
@@ -395,7 +396,8 @@ async function runLockedLocalSteps({
|
|
|
395
396
|
|
|
396
397
|
/**
|
|
397
398
|
* Run the post-land tail: friction markers, then the GitHub steps and the
|
|
398
|
-
* locked local steps concurrently, then
|
|
399
|
+
* locked local steps concurrently, then review dispositions, temp purge and
|
|
400
|
+
* lease release.
|
|
399
401
|
*
|
|
400
402
|
* @param {object} args
|
|
401
403
|
* @param {number} args.storyId
|
|
@@ -418,7 +420,8 @@ async function runLockedLocalSteps({
|
|
|
418
420
|
* @param {Function} [args.reapPlanRunLabelsForStoryFn]
|
|
419
421
|
* @param {Function} [args.rollUpEpicForStoryFn]
|
|
420
422
|
* @param {Function} [args.reapWorktreePhaseFn]
|
|
421
|
-
* @
|
|
423
|
+
* @param {Function} [args.recordStoryDispositionsFn]
|
|
424
|
+
* @returns {Promise<{ followUps: boolean, statusResync: boolean, worktreeReap: boolean, refCleanup: boolean, baseFastForward: boolean, reviewDispositions: boolean, tempPurge: boolean, leaseRelease: boolean, epicRollup: boolean, details: Record<string, string|null> }>}
|
|
422
425
|
*/
|
|
423
426
|
export async function runPostLandTail({
|
|
424
427
|
storyId,
|
|
@@ -441,6 +444,7 @@ export async function runPostLandTail({
|
|
|
441
444
|
reapPlanRunLabelsForStoryFn = defaultReapPlanRunLabelsForStory,
|
|
442
445
|
rollUpEpicForStoryFn = defaultRollUpEpicForStory,
|
|
443
446
|
reapWorktreePhaseFn = defaultReapWorktreePhase,
|
|
447
|
+
recordStoryDispositionsFn = defaultRecordStoryDispositions,
|
|
444
448
|
}) {
|
|
445
449
|
progress?.('POST-LAND', `🧾 Running land tail for Story #${storyId}...`);
|
|
446
450
|
|
|
@@ -522,6 +526,12 @@ export async function runPostLandTail({
|
|
|
522
526
|
]);
|
|
523
527
|
const { worktreeReap, refCleanup, baseFastForward } = local;
|
|
524
528
|
|
|
529
|
+
// Before the purge, which reaps the review history it reads.
|
|
530
|
+
const reviewDispositions = await step(
|
|
531
|
+
() => recordStoryDispositionsFn({ storyId, config, progress }),
|
|
532
|
+
{ name: 'review dispositions', progress },
|
|
533
|
+
);
|
|
534
|
+
|
|
525
535
|
// After every step that reads the temp artifacts; `signals.ndjson` survives.
|
|
526
536
|
const tempPurge = await step(
|
|
527
537
|
() => stepTempPurge({ storyId, config, purgeStoryTempArtifactsFn }),
|
|
@@ -546,6 +556,7 @@ export async function runPostLandTail({
|
|
|
546
556
|
worktreeReap: worktreeReap.ok,
|
|
547
557
|
refCleanup: refCleanup.ok,
|
|
548
558
|
baseFastForward: baseFastForward.ok,
|
|
559
|
+
reviewDispositions: reviewDispositions.ok,
|
|
549
560
|
tempPurge: tempPurge.ok,
|
|
550
561
|
leaseRelease: leaseRelease.ok,
|
|
551
562
|
epicRollup: epicRollup.ok,
|
|
@@ -555,6 +566,7 @@ export async function runPostLandTail({
|
|
|
555
566
|
worktreeReap: worktreeReap.detail,
|
|
556
567
|
refCleanup: refCleanup.detail,
|
|
557
568
|
baseFastForward: baseFastForward.detail,
|
|
569
|
+
reviewDispositions: reviewDispositions.detail,
|
|
558
570
|
tempPurge: tempPurge.detail,
|
|
559
571
|
leaseRelease: leaseRelease.detail,
|
|
560
572
|
epicRollup: epicRollup.detail,
|
|
@@ -9,6 +9,8 @@ import {
|
|
|
9
9
|
emitRuntimeFriction,
|
|
10
10
|
RUNTIME_FRICTION_CATEGORIES,
|
|
11
11
|
} from '../../../observability/runtime-friction.js';
|
|
12
|
+
import { recordOverriddenIds } from '../../review-history.js';
|
|
13
|
+
import { findingId } from '../../review-providers/finding-identity.js';
|
|
12
14
|
import {
|
|
13
15
|
postStructuredComment,
|
|
14
16
|
upsertStructuredComment,
|
|
@@ -55,9 +57,27 @@ async function postAuditRecord({ post, surface }) {
|
|
|
55
57
|
}
|
|
56
58
|
}
|
|
57
59
|
|
|
60
|
+
/**
|
|
61
|
+
* Remember the overridden CRITICALs so a re-review does not halt on them
|
|
62
|
+
* again, and the reason so the land-time disposition record carries it.
|
|
63
|
+
*
|
|
64
|
+
* @param {{ storyId: number, findings: Array<object>, reason: string, config?: object }} args
|
|
65
|
+
*/
|
|
66
|
+
function recordOverrides({ storyId, findings, ...deps }) {
|
|
67
|
+
const ids = findings.filter((f) => f?.severity === 'critical').map(findingId);
|
|
68
|
+
if (ids.length === 0) return;
|
|
69
|
+
try {
|
|
70
|
+
recordOverriddenIds(storyId, ids, deps);
|
|
71
|
+
} catch (err) {
|
|
72
|
+
Logger.warn(
|
|
73
|
+
`[single-story-close] failed to record overridden review ids: ${err?.message ?? err}`,
|
|
74
|
+
);
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
|
|
58
78
|
/**
|
|
59
79
|
* Records to the Story (upsert, so re-runs don't stack), the PR (append-only,
|
|
60
|
-
* where reviewers look), and the
|
|
80
|
+
* where reviewers look), the friction stream, and the review history.
|
|
61
81
|
*
|
|
62
82
|
* @param {{
|
|
63
83
|
* provider: object,
|
|
@@ -67,6 +87,7 @@ async function postAuditRecord({ post, surface }) {
|
|
|
67
87
|
* criticalCount: number,
|
|
68
88
|
* criticalByProvider?: Record<string, number>,
|
|
69
89
|
* reason: string,
|
|
90
|
+
* findings?: Array<object>,
|
|
70
91
|
* config?: object,
|
|
71
92
|
* emitFrictionFn?: typeof emitRuntimeFriction,
|
|
72
93
|
* }} args
|
|
@@ -80,6 +101,7 @@ export async function handleOverriddenReviewBlock({
|
|
|
80
101
|
criticalCount,
|
|
81
102
|
criticalByProvider = {},
|
|
82
103
|
reason,
|
|
104
|
+
findings = [],
|
|
83
105
|
config,
|
|
84
106
|
emitFrictionFn = emitRuntimeFriction,
|
|
85
107
|
}) {
|
|
@@ -112,5 +134,6 @@ export async function handleOverriddenReviewBlock({
|
|
|
112
134
|
},
|
|
113
135
|
config,
|
|
114
136
|
});
|
|
137
|
+
recordOverrides({ storyId, findings, reason, config });
|
|
115
138
|
return { overridden: true, reason, criticalCount };
|
|
116
139
|
}
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* review-dispositions-report.js — summarize the local review-dispositions
|
|
5
|
+
* ledger: per provider and per severity, the count and rate of each
|
|
6
|
+
* disposition, plus the precision and false-blocker proxies. Read-only;
|
|
7
|
+
* exits 0 on an empty or absent ledger.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { parseArgs } from 'node:util';
|
|
11
|
+
|
|
12
|
+
import { runAsCli } from './lib/cli-utils.js';
|
|
13
|
+
import { resolveConfig } from './lib/config-resolver.js';
|
|
14
|
+
import {
|
|
15
|
+
DISPOSITIONS,
|
|
16
|
+
readDispositions,
|
|
17
|
+
summarizeDispositions,
|
|
18
|
+
} from './lib/observability/review-dispositions.js';
|
|
19
|
+
|
|
20
|
+
const USAGE = {
|
|
21
|
+
invocation:
|
|
22
|
+
'node .agents/scripts/review-dispositions-report.js [--since <YYYY-MM-DD>] [--json]',
|
|
23
|
+
summary:
|
|
24
|
+
'Summarize the review-dispositions ledger (<tempRoot>/review-dispositions.ndjson): count and rate of each disposition per provider and per severity, with precision ((fixed-on-branch + open-at-merge) / all) and false-blocker ((overridden + refuted-by-verifier + downgraded-ungrounded) / criticals) proxies.',
|
|
25
|
+
flags: [
|
|
26
|
+
['--since <YYYY-MM-DD>', 'Only records written on or after this date.'],
|
|
27
|
+
['--json', 'Emit the summary as JSON instead of a table.'],
|
|
28
|
+
],
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
const DATE = /^\d{4}-\d{2}-\d{2}$/;
|
|
32
|
+
|
|
33
|
+
/** @param {number|null} r */
|
|
34
|
+
const pct = (r) => (r === null ? '-' : `${(r * 100).toFixed(1)}%`);
|
|
35
|
+
|
|
36
|
+
/** @param {string} label @param {Record<string, object>} groups */
|
|
37
|
+
function renderTable(label, groups) {
|
|
38
|
+
const header = [label, 'total', ...DISPOSITIONS, 'precision', 'false-blk'];
|
|
39
|
+
const rows = Object.entries(groups).map(([key, t]) => [
|
|
40
|
+
key,
|
|
41
|
+
String(t.total),
|
|
42
|
+
...DISPOSITIONS.map((d) => `${t.counts[d]} (${pct(t.rates[d])})`),
|
|
43
|
+
pct(t.precision),
|
|
44
|
+
pct(t.falseBlocker),
|
|
45
|
+
]);
|
|
46
|
+
return alignRows([header, ...rows]).join('\n');
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** @param {string[][]} rows @returns {string[]} space-padded columns. */
|
|
50
|
+
function alignRows(rows) {
|
|
51
|
+
const widths = [];
|
|
52
|
+
for (const row of rows) {
|
|
53
|
+
row.forEach((cell, i) => {
|
|
54
|
+
widths[i] = Math.max(widths[i] ?? 0, cell.length);
|
|
55
|
+
});
|
|
56
|
+
}
|
|
57
|
+
return rows.map((row) =>
|
|
58
|
+
row
|
|
59
|
+
.map((cell, i) => cell.padEnd(widths[i]))
|
|
60
|
+
.join(' ')
|
|
61
|
+
.trimEnd(),
|
|
62
|
+
);
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* @param {string[]} [argv]
|
|
67
|
+
* @param {{
|
|
68
|
+
* resolveConfigImpl?: typeof resolveConfig,
|
|
69
|
+
* stdout?: { write: (s: string) => void },
|
|
70
|
+
* cwd?: string,
|
|
71
|
+
* }} [deps]
|
|
72
|
+
* @returns {Promise<object|null>} the summary, or null when nothing recorded.
|
|
73
|
+
*/
|
|
74
|
+
export async function runReviewDispositionsReport(
|
|
75
|
+
argv = process.argv.slice(2),
|
|
76
|
+
deps = {},
|
|
77
|
+
) {
|
|
78
|
+
const {
|
|
79
|
+
resolveConfigImpl = resolveConfig,
|
|
80
|
+
stdout = process.stdout,
|
|
81
|
+
cwd = process.cwd(),
|
|
82
|
+
} = deps;
|
|
83
|
+
const { values } = parseArgs({
|
|
84
|
+
args: argv,
|
|
85
|
+
options: { since: { type: 'string' }, json: { type: 'boolean' } },
|
|
86
|
+
});
|
|
87
|
+
if (values.since !== undefined && !DATE.test(values.since)) {
|
|
88
|
+
throw new Error(
|
|
89
|
+
`review-dispositions-report: --since must be YYYY-MM-DD (got "${values.since}").`,
|
|
90
|
+
);
|
|
91
|
+
}
|
|
92
|
+
const config = resolveConfigImpl({ cwd });
|
|
93
|
+
const records = await readDispositions({
|
|
94
|
+
config,
|
|
95
|
+
since: values.since ?? null,
|
|
96
|
+
});
|
|
97
|
+
if (records.length === 0) {
|
|
98
|
+
stdout.write('[review-dispositions-report] no dispositions recorded.\n');
|
|
99
|
+
return null;
|
|
100
|
+
}
|
|
101
|
+
const summary = summarizeDispositions(records);
|
|
102
|
+
if (values.json) {
|
|
103
|
+
stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
|
|
104
|
+
return summary;
|
|
105
|
+
}
|
|
106
|
+
stdout.write(
|
|
107
|
+
[
|
|
108
|
+
renderTable('provider', summary.byProvider),
|
|
109
|
+
'',
|
|
110
|
+
renderTable('severity', summary.bySeverity),
|
|
111
|
+
'',
|
|
112
|
+
renderTable('all', { all: summary.overall }),
|
|
113
|
+
'',
|
|
114
|
+
].join('\n'),
|
|
115
|
+
);
|
|
116
|
+
return summary;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
async function main() {
|
|
120
|
+
await runReviewDispositionsReport();
|
|
121
|
+
return 0;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
runAsCli(import.meta.url, main, {
|
|
125
|
+
source: 'review-dispositions-report',
|
|
126
|
+
propagateExitCode: true,
|
|
127
|
+
errorPrefix: '[review-dispositions-report] ❌ Fatal error',
|
|
128
|
+
usage: USAGE,
|
|
129
|
+
});
|