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.
@@ -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
- }