mandrel 2.75.0 → 2.77.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 (36) hide show
  1. package/.agents/audit-checklists/exceptions.md +24 -0
  2. package/.agents/docs/workflows.md +2 -1
  3. package/.agents/schemas/audit-exceptions-envelope.schema.json +268 -0
  4. package/.agents/schemas/audit-rules.json +43 -0
  5. package/.agents/scripts/audit-exceptions.js +145 -0
  6. package/.agents/scripts/lib/audit-exceptions/adapters/ci-gates.js +65 -0
  7. package/.agents/scripts/lib/audit-exceptions/adapters/code-allowlists.js +143 -0
  8. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-audit.js +160 -0
  9. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-patches.js +124 -0
  10. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-pins.js +177 -0
  11. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-policy.js +243 -0
  12. package/.agents/scripts/lib/audit-exceptions/adapters/index.js +30 -0
  13. package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +107 -0
  14. package/.agents/scripts/lib/audit-exceptions/adapters/sca-exceptions.js +55 -0
  15. package/.agents/scripts/lib/audit-exceptions/adapters/test-skips.js +96 -0
  16. package/.agents/scripts/lib/audit-exceptions/adapters/tool-config.js +273 -0
  17. package/.agents/scripts/lib/audit-exceptions/classify.js +64 -0
  18. package/.agents/scripts/lib/audit-exceptions/dependency-index.js +266 -0
  19. package/.agents/scripts/lib/audit-exceptions/engine.js +249 -0
  20. package/.agents/scripts/lib/audit-exceptions/globs.js +106 -0
  21. package/.agents/scripts/lib/audit-exceptions/history.js +126 -0
  22. package/.agents/scripts/lib/audit-exceptions/locate.js +59 -0
  23. package/.agents/scripts/lib/audit-exceptions/probe.js +196 -0
  24. package/.agents/scripts/lib/audit-exceptions/range-subset.js +153 -0
  25. package/.agents/scripts/lib/audit-exceptions/read.js +101 -0
  26. package/.agents/scripts/lib/audit-exceptions/record.js +102 -0
  27. package/.agents/scripts/lib/audit-exceptions/scope.js +131 -0
  28. package/.agents/scripts/lib/audit-exceptions/tickets.js +98 -0
  29. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  30. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  31. package/.agents/scripts/lib/orchestration/plan-persist/supersede-ops.js +34 -5
  32. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +8 -4
  33. package/.agents/workflows/audit-exceptions.md +235 -0
  34. package/.agents/workflows/helpers/plan-reference.md +10 -3
  35. package/docs/CHANGELOG.md +19 -0
  36. package/package.json +1 -1
@@ -0,0 +1,249 @@
1
+ /**
2
+ * Assembles the `/audit-exceptions` evidence envelope: every exception the
3
+ * adapter registry finds, each with a mechanical verdict, plus the clusters,
4
+ * skips, delegations and degradations the lens reads before judging. Read-only:
5
+ * the only write is the caller's `--out` file. Evidence, not a verdict —
6
+ * assembling it is success, including on every degraded input.
7
+ *
8
+ * @module lib/audit-exceptions/engine
9
+ */
10
+
11
+ import path from 'node:path';
12
+ import { tempRootFrom } from '../config/temp-paths.js';
13
+ import { resolveConfig } from '../config-resolver.js';
14
+ import { ADAPTERS } from './adapters/index.js';
15
+ import { classifyAll, VERDICTS } from './classify.js';
16
+ import { buildDependencyIndex } from './dependency-index.js';
17
+ import { addBlame, DEFAULT_BLAME_LIMIT, markIntroduced } from './history.js';
18
+ import { runProbes } from './probe.js';
19
+ import { buildScope } from './scope.js';
20
+ import { DEFAULT_TICKET_LIMIT, resolveTicketStates } from './tickets.js';
21
+
22
+ /** Matches the shipped schema's const. */
23
+ const ENVELOPE_KIND = 'audit-exceptions-envelope';
24
+
25
+ /** Bump on any breaking shape change. */
26
+ const ENVELOPE_SCHEMA_VERSION = '1';
27
+
28
+ export const DEFAULT_MAX_RECORDS = 2000;
29
+
30
+ const CLUSTER_FILE_SAMPLE = 10;
31
+
32
+ /**
33
+ * The temp root relative to the analysed repo; an unreadable config falls
34
+ * back to the default so the run never aborts on it.
35
+ *
36
+ * @param {string} root
37
+ * @returns {string}
38
+ */
39
+ function tempRelFor(root) {
40
+ try {
41
+ const temp = tempRootFrom(resolveConfig({ cwd: root }));
42
+ return path.isAbsolute(temp) ? path.relative(root, temp) : temp;
43
+ } catch {
44
+ return 'temp';
45
+ }
46
+ }
47
+
48
+ function createContext(root, scope, degradations) {
49
+ let index;
50
+ return {
51
+ root,
52
+ scope,
53
+ cache: {},
54
+ deps: () => {
55
+ if (!index) {
56
+ index = buildDependencyIndex(scope, root);
57
+ degradations.push(...index.degradations);
58
+ }
59
+ return index;
60
+ },
61
+ degrade: (input, detail) =>
62
+ degradations.push({
63
+ input,
64
+ reason: 'input could not be read statically',
65
+ detail,
66
+ }),
67
+ };
68
+ }
69
+
70
+ function runAdapters(ctx, degradations) {
71
+ const adapters = [];
72
+ const skipped = [];
73
+ const records = [];
74
+ for (const adapter of ADAPTERS) {
75
+ const { applies, reason } = adapter.applies(ctx);
76
+ if (!applies) {
77
+ skipped.push({ id: adapter.id, reason });
78
+ continue;
79
+ }
80
+ try {
81
+ const found = adapter.extract(ctx);
82
+ records.push(...found);
83
+ adapters.push({
84
+ id: adapter.id,
85
+ category: adapter.category,
86
+ recordCount: found.length,
87
+ });
88
+ } catch (err) {
89
+ degradations.push({
90
+ input: `adapter:${adapter.id}`,
91
+ reason: 'adapter failed',
92
+ detail: err?.message ?? String(err),
93
+ });
94
+ }
95
+ }
96
+ return { adapters, skipped, records };
97
+ }
98
+
99
+ function delegations(scope) {
100
+ if (!scope.fileSet.has('.agentrc.json')) return [];
101
+ return [
102
+ {
103
+ surface: '.agentrc.json delivery.quality.gates.*.ignoreGlobs',
104
+ lens: 'audit-baselines',
105
+ reason:
106
+ '/audit-baselines owns dead gate ignore globs (gateSurface[].deadIgnoreGlobs)',
107
+ },
108
+ ];
109
+ }
110
+
111
+ function countBy(records, key, keys) {
112
+ const counts = Object.fromEntries(keys.map((k) => [k, 0]));
113
+ for (const r of records) counts[r[key]] = (counts[r[key]] ?? 0) + 1;
114
+ return counts;
115
+ }
116
+
117
+ /** One cluster per `(adapter, rule)` — the unit the lens files a finding for. */
118
+ function buildClusters(records) {
119
+ const clusters = new Map();
120
+ for (const r of records) {
121
+ const key = `${r.adapter}␟${r.rule}`;
122
+ if (!clusters.has(key)) {
123
+ clusters.set(key, {
124
+ adapter: r.adapter,
125
+ category: r.category,
126
+ rule: r.rule,
127
+ count: 0,
128
+ byVerdict: countBy([], 'verdict', VERDICTS),
129
+ files: [],
130
+ });
131
+ }
132
+ const c = clusters.get(key);
133
+ c.count += 1;
134
+ c.byVerdict[r.verdict] += 1;
135
+ if (c.files.length < CLUSTER_FILE_SAMPLE && !c.files.includes(r.file))
136
+ c.files.push(r.file);
137
+ }
138
+ return [...clusters.values()].sort(
139
+ (a, b) => b.count - a.count || a.rule.localeCompare(b.rule),
140
+ );
141
+ }
142
+
143
+ const byLocation = (a, b) =>
144
+ a.category.localeCompare(b.category) ||
145
+ a.adapter.localeCompare(b.adapter) ||
146
+ a.file.localeCompare(b.file) ||
147
+ a.line - b.line;
148
+
149
+ function dedupe(degradations) {
150
+ const seen = new Set();
151
+ return degradations.filter((d) => {
152
+ const key = `${d.input}␟${d.detail}`;
153
+ if (seen.has(key)) return false;
154
+ seen.add(key);
155
+ return true;
156
+ });
157
+ }
158
+
159
+ /**
160
+ * @param {object} opts
161
+ * @param {string} opts.cwd - analysed repository root.
162
+ * @param {boolean} [opts.probe]
163
+ * @param {string|null} [opts.changedSince]
164
+ * @param {number} [opts.ticketLimit]
165
+ * @param {number} [opts.blameLimit]
166
+ * @param {number} [opts.maxRecords]
167
+ * @param {string} [opts.today] - ISO date (test seam).
168
+ * @param {object} [opts.gh] - gh facade (test seam).
169
+ * @param {Function} [opts.spawn] - probe spawn (test seam).
170
+ * @returns {Promise<object>} the envelope.
171
+ */
172
+ export async function runEngine({
173
+ cwd,
174
+ probe = false,
175
+ changedSince = null,
176
+ ticketLimit = DEFAULT_TICKET_LIMIT,
177
+ blameLimit = DEFAULT_BLAME_LIMIT,
178
+ maxRecords = DEFAULT_MAX_RECORDS,
179
+ today = new Date().toISOString().slice(0, 10),
180
+ gh,
181
+ spawn,
182
+ }) {
183
+ const root = path.resolve(cwd);
184
+ const scope = buildScope({ root, tempRel: tempRelFor(root) });
185
+ const degradations = [...scope.degradations];
186
+ const ctx = createContext(root, scope, degradations);
187
+ const { adapters, skipped, records } = runAdapters(ctx, degradations);
188
+
189
+ const probed = probe
190
+ ? await runProbes(records, { root, scope, spawn })
191
+ : { tools: [], degradations: [] };
192
+ degradations.push(...probed.degradations);
193
+ const tickets = await resolveTicketStates(
194
+ records.flatMap((r) => r.ticketRefs),
195
+ { root, limit: ticketLimit, gh },
196
+ );
197
+ degradations.push(...tickets.degradations);
198
+ classifyAll(records, { ticketStates: tickets.states, today });
199
+ if (changedSince)
200
+ degradations.push(...markIntroduced(records, { root, ref: changedSince }));
201
+
202
+ records.sort(byLocation);
203
+ const kept = records.slice(0, maxRecords);
204
+ degradations.push(...addBlame(kept, { root, limit: blameLimit }));
205
+
206
+ return {
207
+ kind: ENVELOPE_KIND,
208
+ schemaVersion: ENVELOPE_SCHEMA_VERSION,
209
+ generatedAt: new Date().toISOString(),
210
+ cwd: root,
211
+ isFrameworkSource: scope.isFrameworkSource,
212
+ options: { probe, changedSince, ticketLimit, blameLimit, maxRecords },
213
+ adapters,
214
+ skipped,
215
+ delegated: delegations(scope),
216
+ probes: probed.tools,
217
+ degradations: dedupe(degradations),
218
+ totals: {
219
+ records: records.length,
220
+ byVerdict: countBy(records, 'verdict', VERDICTS),
221
+ byCategory: countBy(records, 'category', []),
222
+ introduced: records.filter((r) => r.introduced).length,
223
+ },
224
+ clusters: buildClusters(records),
225
+ truncated:
226
+ records.length > maxRecords
227
+ ? { kept: maxRecords, dropped: records.length - maxRecords }
228
+ : null,
229
+ records: kept,
230
+ };
231
+ }
232
+
233
+ /**
234
+ * @param {object} envelope
235
+ * @param {string} outPath
236
+ * @returns {object}
237
+ */
238
+ export function summarize(envelope, outPath) {
239
+ return {
240
+ kind: 'audit-exceptions-summary',
241
+ out: outPath,
242
+ records: envelope.totals.records,
243
+ byVerdict: envelope.totals.byVerdict,
244
+ clusters: envelope.clusters.length,
245
+ skipped: envelope.skipped.map((s) => s.id),
246
+ degradations: [...new Set(envelope.degradations.map((d) => d.input))],
247
+ truncated: envelope.truncated,
248
+ };
249
+ }
@@ -0,0 +1,106 @@
1
+ /**
2
+ * The shared probe for an exemption expressed as a glob: does it still exempt
3
+ * anything? A glob matching a tracked file is `live`. One matching nothing is
4
+ * `dead` only when its static base path is absent from disk and is not a
5
+ * gitignored location — `dist/**` on a fresh clone matches nothing yet still
6
+ * guards the build output — and `unknown` when the glob has no static base.
7
+ *
8
+ * @module lib/audit-exceptions/globs
9
+ */
10
+
11
+ import fs from 'node:fs';
12
+ import path from 'node:path';
13
+ import picomatch from 'picomatch';
14
+ import { gitSpawn } from '../git-utils.js';
15
+
16
+ const GLOB_CHAR_RE = /[*?[\]{}()!]/;
17
+
18
+ /**
19
+ * Leading static directory of a glob (`src/gen/**\/*.ts` → `src/gen`).
20
+ *
21
+ * @param {string} glob
22
+ * @returns {string}
23
+ */
24
+ function staticBase(glob) {
25
+ const segments = glob.split('/');
26
+ const out = [];
27
+ for (const seg of segments) {
28
+ if (GLOB_CHAR_RE.test(seg)) break;
29
+ out.push(seg);
30
+ }
31
+ return out.join('/');
32
+ }
33
+
34
+ /**
35
+ * gitignore-style line (`dist`, `/build/`, `*.log`) → globs relative to `dir`.
36
+ *
37
+ * @param {string} line
38
+ * @param {string} [dir]
39
+ * @returns {string[]}
40
+ */
41
+ export function ignoreLineGlobs(line, dir = '') {
42
+ const anchored = line.startsWith('/') || line.slice(0, -1).includes('/');
43
+ const body = line.replace(/^\/|\/$/g, '');
44
+ // An unanchored line also matches at the top level, which carries a static base.
45
+ const bases = anchored ? [body] : [body, `**/${body}`];
46
+ return bases
47
+ .flatMap((b) => [b, `${b}/**`])
48
+ .map((g) => (dir ? `${dir}/${g}` : g));
49
+ }
50
+
51
+ /**
52
+ * @param {object} ctx
53
+ * @param {string} glob - repo-relative.
54
+ * @returns {{ verdict: string, basis: string }}
55
+ */
56
+ function probeOne(ctx, glob) {
57
+ const clean = glob.replace(/^\.\//, '').replace(/^!/, '');
58
+ const isMatch = picomatch([clean, `${clean.replace(/\/+$/, '')}/**`], {
59
+ dot: true,
60
+ });
61
+ if (ctx.scope.files.some((f) => isMatch(f)))
62
+ return { verdict: 'live', basis: 'matches-tracked' };
63
+ const base = staticBase(clean);
64
+ if (base === '') return { verdict: 'unknown', basis: 'no-static-base' };
65
+ if (fs.existsSync(path.join(ctx.root, base))) {
66
+ return {
67
+ verdict: 'live',
68
+ basis: 'matches-untracked-path',
69
+ permanentHint: 'untracked-path',
70
+ };
71
+ }
72
+ // A child path, so a directory-only pattern (`/temp/`) matches an absent dir.
73
+ if (
74
+ gitSpawn(ctx.root, 'check-ignore', '-q', '--no-index', `${base}/.probe`)
75
+ .status === 0
76
+ ) {
77
+ return {
78
+ verdict: 'live',
79
+ basis: 'gitignored-path',
80
+ permanentHint: 'untracked-path',
81
+ };
82
+ }
83
+ return { verdict: 'dead', basis: 'matches-nothing' };
84
+ }
85
+
86
+ /**
87
+ * Probe several globs that form one exemption: `live` if any is live, `dead`
88
+ * only if every one is dead, otherwise `unknown`.
89
+ *
90
+ * @param {object} ctx
91
+ * @param {string[]} globs
92
+ * @returns {{ verdict: string, basis: string }}
93
+ */
94
+ export function globsProbe(ctx, globs) {
95
+ const results = globs.map((g) => probeOne(ctx, g));
96
+ const live = results.find((r) => r.verdict === 'live');
97
+ if (live) return live;
98
+ if (results.length > 0 && results.every((r) => r.verdict === 'dead'))
99
+ return results[0];
100
+ return (
101
+ results.find((r) => r.verdict === 'unknown') ?? {
102
+ verdict: 'unknown',
103
+ basis: 'no-globs',
104
+ }
105
+ );
106
+ }
@@ -0,0 +1,126 @@
1
+ /**
2
+ * Git-history facts about records: when each exception line was added
3
+ * (`addedAt`, from `git blame`, capped because blame is the slowest read on a
4
+ * large repo or on Windows) and whether it was added since a ref
5
+ * (`introduced`, from `git diff -U0`).
6
+ *
7
+ * @module lib/audit-exceptions/history
8
+ */
9
+
10
+ import { gitSpawn } from '../git-utils.js';
11
+
12
+ export const DEFAULT_BLAME_LIMIT = 200;
13
+
14
+ const UNCOMMITTED_SHA = /^0{40}$/;
15
+
16
+ /**
17
+ * @param {string} porcelain - `git blame --porcelain` output.
18
+ * @returns {Map<number, string>} final line → ISO date.
19
+ */
20
+ function parseBlame(porcelain) {
21
+ const timeBySha = new Map();
22
+ const shaByLine = new Map();
23
+ let current = null;
24
+ for (const line of porcelain.split('\n')) {
25
+ const header = /^([0-9a-f]{40}) \d+ (\d+)/.exec(line);
26
+ if (header) {
27
+ current = header[1];
28
+ shaByLine.set(Number(header[2]), current);
29
+ continue;
30
+ }
31
+ const time = /^author-time (\d+)$/.exec(line);
32
+ if (time && current) timeBySha.set(current, Number(time[1]));
33
+ }
34
+ const out = new Map();
35
+ for (const [n, sha] of shaByLine) {
36
+ const t = timeBySha.get(sha);
37
+ if (t !== undefined && !UNCOMMITTED_SHA.test(sha))
38
+ out.set(n, new Date(t * 1000).toISOString().slice(0, 10));
39
+ }
40
+ return out;
41
+ }
42
+
43
+ /**
44
+ * Sets `addedAt` on up to `limit` records, one `git blame` per file.
45
+ *
46
+ * @param {object[]} records
47
+ * @param {{ root: string, limit?: number }} opts
48
+ * @returns {object[]} degradations
49
+ */
50
+ export function addBlame(records, { root, limit = DEFAULT_BLAME_LIMIT }) {
51
+ const byFile = new Map();
52
+ for (const r of records.slice(0, limit)) {
53
+ if (!byFile.has(r.file)) byFile.set(r.file, []);
54
+ byFile.get(r.file).push(r);
55
+ }
56
+ for (const [file, group] of byFile) {
57
+ const ranges = group.flatMap((r) => ['-L', `${r.line},${r.line}`]);
58
+ const res = gitSpawn(root, 'blame', '--porcelain', ...ranges, '--', file);
59
+ if (res.status !== 0) continue;
60
+ const dates = parseBlame(res.stdout);
61
+ for (const r of group) r.addedAt = dates.get(r.line) ?? null;
62
+ }
63
+ if (records.length <= limit) return [];
64
+ return [
65
+ {
66
+ input: 'blame-limit',
67
+ reason: `addedAt resolved for the first ${limit} of ${records.length} records`,
68
+ detail: '',
69
+ },
70
+ ];
71
+ }
72
+
73
+ /**
74
+ * @param {string} diff - `git diff -U0` output.
75
+ * @returns {Map<string, Set<number>>}
76
+ */
77
+ function parseAddedLines(diff) {
78
+ const added = new Map();
79
+ let file = null;
80
+ for (const line of diff.split('\n')) {
81
+ const target = /^\+\+\+ (?:b\/)?(.*)$/.exec(line);
82
+ if (target) {
83
+ file = target[1] === '/dev/null' ? null : target[1];
84
+ if (file && !added.has(file)) added.set(file, new Set());
85
+ continue;
86
+ }
87
+ const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
88
+ if (!hunk || !file) continue;
89
+ const start = Number(hunk[1]);
90
+ const count = hunk[2] === undefined ? 1 : Number(hunk[2]);
91
+ for (let n = start; n < start + count; n += 1) added.get(file).add(n);
92
+ }
93
+ return added;
94
+ }
95
+
96
+ /**
97
+ * Marks `introduced: true` on records whose line was added relative to `ref`.
98
+ *
99
+ * @param {object[]} records
100
+ * @param {{ root: string, ref: string }} opts
101
+ * @returns {object[]} degradations
102
+ */
103
+ export function markIntroduced(records, { root, ref }) {
104
+ const res = gitSpawn(
105
+ root,
106
+ 'diff',
107
+ '-U0',
108
+ '--no-color',
109
+ '--no-ext-diff',
110
+ ref,
111
+ '--',
112
+ );
113
+ if (res.status !== 0) {
114
+ return [
115
+ {
116
+ input: 'changed-since',
117
+ reason: `could not diff against ${ref}`,
118
+ detail: res.stderr,
119
+ },
120
+ ];
121
+ }
122
+ const added = parseAddedLines(res.stdout);
123
+ for (const r of records)
124
+ r.introduced = added.get(r.file)?.has(r.line) ?? false;
125
+ return [];
126
+ }
@@ -0,0 +1,59 @@
1
+ /**
2
+ * Text positions for records: the line an exception lives on, and whether a
3
+ * match sits inside a string literal.
4
+ *
5
+ * @module lib/audit-exceptions/locate
6
+ */
7
+
8
+ /**
9
+ * 1-based line of `needle` in `text`, searched after each of `anchors` in
10
+ * turn — the section keys that contain it (`"pnpm"`, then `"overrides"`). A
11
+ * pin's package also appears as its `dependencies` entry, so a bare
12
+ * first-occurrence search lands on the wrong line, and that line's blame and
13
+ * diff membership are wrong with it. Returns 1 when the needle does not occur:
14
+ * a record always carries a line a reader can open.
15
+ *
16
+ * @param {string|null} text
17
+ * @param {string} needle
18
+ * @param {string[]} [anchors]
19
+ * @returns {number}
20
+ */
21
+ export function lineOf(text, needle, anchors = []) {
22
+ if (!text) return 1;
23
+ let from = 0;
24
+ for (const anchor of anchors) {
25
+ const hit = text.indexOf(anchor, from);
26
+ if (hit !== -1) from = hit + anchor.length;
27
+ }
28
+ const at = text.indexOf(needle, from);
29
+ if (at === -1) return 1;
30
+ return text.slice(0, at).split('\n').length;
31
+ }
32
+
33
+ /**
34
+ * `lineOf` for a package or key name: JSON quotes it, YAML does not, so try
35
+ * the quoted form first.
36
+ *
37
+ * @param {string|null} text
38
+ * @param {string} name
39
+ * @param {string[]} [anchors]
40
+ * @returns {number}
41
+ */
42
+ export function lineOfName(text, name, anchors = []) {
43
+ const quoted = lineOf(text, `"${name}"`, anchors);
44
+ return quoted === 1 ? lineOf(text, name, anchors) : quoted;
45
+ }
46
+
47
+ /**
48
+ * True when an odd number of one quote kind precede `index` on `line` — the
49
+ * position sits inside a string literal, so a directive or declaration there
50
+ * is data (a fixture, a message), not code.
51
+ *
52
+ * @param {string} line
53
+ * @param {number} index
54
+ * @returns {boolean}
55
+ */
56
+ export function insideString(line, index) {
57
+ const before = line.slice(0, index);
58
+ return ['"', "'", '`'].some((q) => before.split(q).length % 2 === 0);
59
+ }