mandrel 2.68.0 → 2.70.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/scripts/audit-to-stories.js +39 -247
- package/.agents/scripts/lib/audit-to-stories/finding-adapter.js +1 -1
- package/.agents/scripts/lib/findings/route-finding.js +15 -0
- package/.agents/scripts/lib/orchestration/plan-context.js +14 -1
- package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js +35 -117
- package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -6
- package/.agents/templates/docs/audit-sweep-runbook.md +29 -59
- package/.agents/workflows/audit-security.md +0 -1
- package/.agents/workflows/audit-to-stories.md +40 -67
- package/docs/CHANGELOG.md +18 -0
- package/lib/migrations/index.js +2 -0
- package/lib/migrations/steps/2.70.0-retire-audit-ledger.js +36 -0
- package/package.json +1 -1
- package/.agents/scripts/lib/audit-to-stories/ledger-commit.js +0 -184
- package/.agents/scripts/lib/audit-to-stories/ledger-pr.js +0 -279
- package/.agents/scripts/lib/audit-to-stories/ledger-record.js +0 -88
- package/.agents/scripts/lib/findings/audit-ledger.js +0 -289
|
@@ -1,289 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* lib/findings/audit-ledger.js — committed cross-run memory of audit
|
|
3
|
-
* findings, keyed by fingerprint and `semanticKey`. Status: `new` · `filed` ·
|
|
4
|
-
* `fixed` · `accepted-risk` (closed `not_planned`; suppressed) · `regressed`.
|
|
5
|
-
*/
|
|
6
|
-
|
|
7
|
-
import nodeFs from 'node:fs';
|
|
8
|
-
import nodePath from 'node:path';
|
|
9
|
-
import { fingerprintFinding, semanticKeyFor } from './route-finding.js';
|
|
10
|
-
|
|
11
|
-
export const DEFAULT_LEDGER_PATH = 'baselines/audit-ledger.json';
|
|
12
|
-
const LEDGER_SCHEMA_URL =
|
|
13
|
-
'https://mandrel.dev/baselines/audit-ledger.schema.json';
|
|
14
|
-
|
|
15
|
-
/**
|
|
16
|
-
* @param {string} [now] — ISO timestamp to stamp.
|
|
17
|
-
* @returns {{ $schema: string, generatedAt: string, entries: [] }}
|
|
18
|
-
*/
|
|
19
|
-
function createEmptyLedger(now = new Date().toISOString()) {
|
|
20
|
-
return { $schema: LEDGER_SCHEMA_URL, generatedAt: now, entries: [] };
|
|
21
|
-
}
|
|
22
|
-
|
|
23
|
-
/**
|
|
24
|
-
* `toCanonical` is injected: importing the audit adapter would close a cycle.
|
|
25
|
-
*
|
|
26
|
-
* @param {object} finding
|
|
27
|
-
* @param {(finding: object) => object} [toCanonical]
|
|
28
|
-
* @returns {{ fingerprint: string, semanticKey: string }}
|
|
29
|
-
*/
|
|
30
|
-
function findingIdentity(finding, toCanonical) {
|
|
31
|
-
const canonical = toCanonical ? toCanonical(finding) : finding;
|
|
32
|
-
return {
|
|
33
|
-
fingerprint: fingerprintFinding(canonical).full,
|
|
34
|
-
semanticKey: semanticKeyFor(canonical),
|
|
35
|
-
};
|
|
36
|
-
}
|
|
37
|
-
|
|
38
|
-
/**
|
|
39
|
-
* An absent or unparseable file reads as an empty ledger, never an error.
|
|
40
|
-
* @param {string} filePath
|
|
41
|
-
* @param {{ fs?: typeof import('node:fs') }} [deps]
|
|
42
|
-
* @returns {{ $schema?: string, generatedAt?: string, entries: object[] }}
|
|
43
|
-
*/
|
|
44
|
-
export function readLedger(filePath, { fs } = {}) {
|
|
45
|
-
const fsLike = fs ?? nodeFs;
|
|
46
|
-
if (!fsLike || !fsLike.existsSync(filePath)) return createEmptyLedger();
|
|
47
|
-
try {
|
|
48
|
-
const parsed = JSON.parse(fsLike.readFileSync(filePath, 'utf8'));
|
|
49
|
-
if (!parsed || !Array.isArray(parsed.entries)) return createEmptyLedger();
|
|
50
|
-
return parsed;
|
|
51
|
-
} catch (_) {
|
|
52
|
-
return createEmptyLedger();
|
|
53
|
-
}
|
|
54
|
-
}
|
|
55
|
-
|
|
56
|
-
/**
|
|
57
|
-
* @param {string} filePath
|
|
58
|
-
* @param {object} ledger
|
|
59
|
-
* @param {{ fs?: typeof import('node:fs'), path?: typeof import('node:path') }} [deps]
|
|
60
|
-
*/
|
|
61
|
-
export function writeLedger(filePath, ledger, { fs, path } = {}) {
|
|
62
|
-
const fsLike = fs ?? nodeFs;
|
|
63
|
-
const pathLike = path ?? nodePath;
|
|
64
|
-
if (!fsLike) return;
|
|
65
|
-
fsLike.mkdirSync(pathLike.dirname(filePath), { recursive: true });
|
|
66
|
-
fsLike.writeFileSync(filePath, `${JSON.stringify(ledger, null, 2)}\n`);
|
|
67
|
-
}
|
|
68
|
-
|
|
69
|
-
/**
|
|
70
|
-
* @param {{ entries?: object[] }} ledger
|
|
71
|
-
*/
|
|
72
|
-
function indexLedger(ledger) {
|
|
73
|
-
const byFingerprint = new Map();
|
|
74
|
-
const bySemanticKey = new Map();
|
|
75
|
-
for (const entry of ledger?.entries ?? []) {
|
|
76
|
-
if (entry?.fingerprint) byFingerprint.set(entry.fingerprint, entry);
|
|
77
|
-
if (entry?.semanticKey) bySemanticKey.set(entry.semanticKey, entry);
|
|
78
|
-
}
|
|
79
|
-
return { byFingerprint, bySemanticKey };
|
|
80
|
-
}
|
|
81
|
-
|
|
82
|
-
/**
|
|
83
|
-
* An `issueStates` override beats the recorded Issue.
|
|
84
|
-
* @param {{ fingerprint: string, semanticKey: string }} id
|
|
85
|
-
* @param {object|null} existing
|
|
86
|
-
* @param {Record<string, { state?: string, stateReason?: string|null, number?: number }>} issueStates
|
|
87
|
-
* @returns {{ state: string, stateReason: string|null, number: number|null }|null}
|
|
88
|
-
*/
|
|
89
|
-
function resolveIssueState(id, existing, issueStates) {
|
|
90
|
-
const override = issueStates[id.fingerprint] ?? issueStates[id.semanticKey];
|
|
91
|
-
const raw = override ?? existing?.issue ?? null;
|
|
92
|
-
if (!raw) return null;
|
|
93
|
-
return {
|
|
94
|
-
state: (raw.state ?? '').toLowerCase(),
|
|
95
|
-
stateReason: raw.stateReason ? String(raw.stateReason).toLowerCase() : null,
|
|
96
|
-
number: typeof raw.number === 'number' ? raw.number : null,
|
|
97
|
-
};
|
|
98
|
-
}
|
|
99
|
-
|
|
100
|
-
/**
|
|
101
|
-
* @type {Record<string, { status: string, action: string }>}
|
|
102
|
-
*/
|
|
103
|
-
const VERDICT = Object.freeze({
|
|
104
|
-
filed: Object.freeze({ status: 'filed', action: 'known' }),
|
|
105
|
-
propose: Object.freeze({ status: 'new', action: 'propose' }),
|
|
106
|
-
suppress: Object.freeze({ status: 'accepted-risk', action: 'suppress' }),
|
|
107
|
-
regressed: Object.freeze({ status: 'regressed', action: 'regressed' }),
|
|
108
|
-
});
|
|
109
|
-
|
|
110
|
-
/**
|
|
111
|
-
* The whole reconciliation policy.
|
|
112
|
-
* @param {object|null} existing — prior ledger entry (or null when unseen).
|
|
113
|
-
* @param {{ state: string, stateReason: string|null }|null} issue
|
|
114
|
-
* @returns {{ status: string, action: 'propose'|'known'|'suppress'|'regressed' }}
|
|
115
|
-
*/
|
|
116
|
-
function decideStatus(existing, issue) {
|
|
117
|
-
// A closed Issue outranks any recorded status.
|
|
118
|
-
if (issue && issue.state === 'closed') {
|
|
119
|
-
return issue.stateReason === 'not_planned'
|
|
120
|
-
? VERDICT.suppress
|
|
121
|
-
: VERDICT.regressed;
|
|
122
|
-
}
|
|
123
|
-
|
|
124
|
-
// An open Issue means filed even with no prior entry.
|
|
125
|
-
const unseen = issue?.state === 'open' ? VERDICT.filed : VERDICT.propose;
|
|
126
|
-
if (!existing) return unseen;
|
|
127
|
-
|
|
128
|
-
switch (existing.status) {
|
|
129
|
-
case 'accepted-risk':
|
|
130
|
-
return VERDICT.suppress;
|
|
131
|
-
case 'filed':
|
|
132
|
-
return VERDICT.filed;
|
|
133
|
-
// Recorded fixed yet detected again: a regression, open Issue or not.
|
|
134
|
-
case 'fixed':
|
|
135
|
-
return VERDICT.regressed;
|
|
136
|
-
case 'regressed':
|
|
137
|
-
return VERDICT.regressed;
|
|
138
|
-
default:
|
|
139
|
-
return unseen;
|
|
140
|
-
}
|
|
141
|
-
}
|
|
142
|
-
|
|
143
|
-
/**
|
|
144
|
-
* Fold a scan and live Issue states onto the prior ledger; untouched entries
|
|
145
|
-
* are preserved.
|
|
146
|
-
*
|
|
147
|
-
* @param {object} params
|
|
148
|
-
* @param {{ entries?: object[] }} [params.ledger]
|
|
149
|
-
* @param {Array<object>} params.findings
|
|
150
|
-
* @param {Record<string, { state?: string, stateReason?: string|null, number?: number }>} [params.issueStates]
|
|
151
|
-
* @param {string} [params.now]
|
|
152
|
-
* @param {(finding: object) => object} [params.toCanonical]
|
|
153
|
-
* @returns {{
|
|
154
|
-
* ledger: { $schema: string, generatedAt: string, entries: object[] },
|
|
155
|
-
* classifications: Array<{ fingerprint: string, semanticKey: string, status: string, action: string, issue: object|null }>,
|
|
156
|
-
* }}
|
|
157
|
-
*/
|
|
158
|
-
export function reconcileLedger({
|
|
159
|
-
ledger = createEmptyLedger(),
|
|
160
|
-
findings,
|
|
161
|
-
issueStates = {},
|
|
162
|
-
now = new Date().toISOString(),
|
|
163
|
-
toCanonical,
|
|
164
|
-
} = {}) {
|
|
165
|
-
if (!Array.isArray(findings)) {
|
|
166
|
-
throw new Error('reconcileLedger: findings must be an array');
|
|
167
|
-
}
|
|
168
|
-
|
|
169
|
-
const { byFingerprint, bySemanticKey } = indexLedger(ledger);
|
|
170
|
-
const nextByFingerprint = new Map(byFingerprint);
|
|
171
|
-
const classifications = [];
|
|
172
|
-
|
|
173
|
-
for (const finding of findings) {
|
|
174
|
-
const id = findingIdentity(finding, toCanonical);
|
|
175
|
-
const existing =
|
|
176
|
-
byFingerprint.get(id.fingerprint) ??
|
|
177
|
-
(id.semanticKey ? bySemanticKey.get(id.semanticKey) : undefined) ??
|
|
178
|
-
null;
|
|
179
|
-
|
|
180
|
-
const issue = resolveIssueState(id, existing, issueStates);
|
|
181
|
-
const { status, action } = decideStatus(existing, issue);
|
|
182
|
-
|
|
183
|
-
const entry = {
|
|
184
|
-
fingerprint: id.fingerprint,
|
|
185
|
-
semanticKey: id.semanticKey,
|
|
186
|
-
title: finding?.title ?? existing?.title ?? '',
|
|
187
|
-
dimension: finding?.dimension ?? existing?.dimension ?? '',
|
|
188
|
-
primaryFile:
|
|
189
|
-
(Array.isArray(finding?.files) && finding.files[0]) ??
|
|
190
|
-
existing?.primaryFile ??
|
|
191
|
-
'',
|
|
192
|
-
status,
|
|
193
|
-
issue: issue
|
|
194
|
-
? {
|
|
195
|
-
number: issue.number,
|
|
196
|
-
state: issue.state,
|
|
197
|
-
stateReason: issue.stateReason,
|
|
198
|
-
}
|
|
199
|
-
: (existing?.issue ?? null),
|
|
200
|
-
firstSeen: existing?.firstSeen ?? now,
|
|
201
|
-
lastSeen: now,
|
|
202
|
-
};
|
|
203
|
-
|
|
204
|
-
// Re-key a reworded finding matched by semanticKey.
|
|
205
|
-
if (existing?.fingerprint && existing.fingerprint !== id.fingerprint) {
|
|
206
|
-
nextByFingerprint.delete(existing.fingerprint);
|
|
207
|
-
}
|
|
208
|
-
nextByFingerprint.set(id.fingerprint, entry);
|
|
209
|
-
|
|
210
|
-
classifications.push({
|
|
211
|
-
fingerprint: id.fingerprint,
|
|
212
|
-
semanticKey: id.semanticKey,
|
|
213
|
-
status,
|
|
214
|
-
action,
|
|
215
|
-
issue: entry.issue,
|
|
216
|
-
});
|
|
217
|
-
}
|
|
218
|
-
|
|
219
|
-
return {
|
|
220
|
-
ledger: {
|
|
221
|
-
$schema: ledger?.$schema ?? LEDGER_SCHEMA_URL,
|
|
222
|
-
generatedAt: now,
|
|
223
|
-
entries: [...nextByFingerprint.values()],
|
|
224
|
-
},
|
|
225
|
-
classifications,
|
|
226
|
-
};
|
|
227
|
-
}
|
|
228
|
-
|
|
229
|
-
/**
|
|
230
|
-
* Record identity strings (`plan-persist` has no findings) as filed. An
|
|
231
|
-
* identity whose Issue is closed is skipped, so its verdict survives.
|
|
232
|
-
*
|
|
233
|
-
* @param {object} params
|
|
234
|
-
* @param {{ entries?: object[] }} [params.ledger]
|
|
235
|
-
* @param {Array<{ fingerprint: string, semanticKey?: string, title?: string, dimension?: string, primaryFile?: string }>} params.identities
|
|
236
|
-
* @param {{ number: number }} params.issue
|
|
237
|
-
* @param {string} [params.now]
|
|
238
|
-
* @returns {{ ledger: object, recorded: number, skipped: number }}
|
|
239
|
-
*/
|
|
240
|
-
export function recordFiledIdentities({
|
|
241
|
-
ledger = createEmptyLedger(),
|
|
242
|
-
identities,
|
|
243
|
-
issue,
|
|
244
|
-
now = new Date().toISOString(),
|
|
245
|
-
} = {}) {
|
|
246
|
-
if (!Array.isArray(identities)) {
|
|
247
|
-
throw new Error('recordFiledIdentities: identities must be an array');
|
|
248
|
-
}
|
|
249
|
-
if (!issue || typeof issue.number !== 'number') {
|
|
250
|
-
throw new Error('recordFiledIdentities: issue.number must be a number');
|
|
251
|
-
}
|
|
252
|
-
|
|
253
|
-
const { byFingerprint } = indexLedger(ledger);
|
|
254
|
-
const next = new Map(byFingerprint);
|
|
255
|
-
let recorded = 0;
|
|
256
|
-
let skipped = 0;
|
|
257
|
-
|
|
258
|
-
for (const identity of identities) {
|
|
259
|
-
const fingerprint = identity?.fingerprint;
|
|
260
|
-
if (typeof fingerprint !== 'string' || fingerprint.length === 0) continue;
|
|
261
|
-
const existing = byFingerprint.get(fingerprint) ?? null;
|
|
262
|
-
if (existing?.issue && existing.issue.state === 'closed') {
|
|
263
|
-
skipped += 1;
|
|
264
|
-
continue;
|
|
265
|
-
}
|
|
266
|
-
next.set(fingerprint, {
|
|
267
|
-
fingerprint,
|
|
268
|
-
semanticKey: identity.semanticKey ?? existing?.semanticKey ?? '',
|
|
269
|
-
title: identity.title ?? existing?.title ?? '',
|
|
270
|
-
dimension: identity.dimension ?? existing?.dimension ?? '',
|
|
271
|
-
primaryFile: identity.primaryFile ?? existing?.primaryFile ?? '',
|
|
272
|
-
status: 'filed',
|
|
273
|
-
issue: { number: issue.number, state: 'open', stateReason: null },
|
|
274
|
-
firstSeen: existing?.firstSeen ?? now,
|
|
275
|
-
lastSeen: now,
|
|
276
|
-
});
|
|
277
|
-
recorded += 1;
|
|
278
|
-
}
|
|
279
|
-
|
|
280
|
-
return {
|
|
281
|
-
ledger: {
|
|
282
|
-
$schema: ledger?.$schema ?? LEDGER_SCHEMA_URL,
|
|
283
|
-
generatedAt: now,
|
|
284
|
-
entries: [...next.values()],
|
|
285
|
-
},
|
|
286
|
-
recorded,
|
|
287
|
-
skipped,
|
|
288
|
-
};
|
|
289
|
-
}
|