mandrel 2.79.0 → 2.80.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 (30) hide show
  1. package/.agents/agents/auditor.md +8 -3
  2. package/.agents/audit-checklists/data-model.md +9 -1
  3. package/.agents/docs/agentrc-reference.json +3 -0
  4. package/.agents/docs/configuration.md +1 -1
  5. package/.agents/docs/workflows.md +1 -1
  6. package/.agents/schemas/agentrc.schema.json +19 -1
  7. package/.agents/schemas/audit-rules.json +5 -1
  8. package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js +37 -2
  9. package/.agents/scripts/lib/config/explain.js +1 -1
  10. package/.agents/scripts/lib/config-settings-schema.js +18 -1
  11. package/.agents/scripts/lib/findings/audit-finding-record.js +95 -0
  12. package/.agents/scripts/lib/findings/route-finding.js +4 -3
  13. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  14. package/.agents/scripts/lib/orchestration/plan-persist/audit-attribution.js +182 -0
  15. package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js +11 -10
  16. package/.agents/scripts/lib/orchestration/plan-persist/collision-message.js +52 -0
  17. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -3
  18. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +28 -14
  19. package/.agents/scripts/lib/orchestration/plan-persist/wave-collision-gate.js +8 -4
  20. package/.agents/scripts/lib/orchestration/plan-persist/wave-serialisation.js +3 -2
  21. package/.agents/scripts/lib/qa/resolve-qa-contract.js +28 -9
  22. package/.agents/scripts/lib/templates/decomposer-prompts.js +2 -2
  23. package/.agents/scripts/lib/wave-runner/footprint.js +114 -17
  24. package/.agents/scripts/lib/wave-runner/ready-set.js +16 -5
  25. package/.agents/workflows/audit-data-model.md +94 -10
  26. package/.agents/workflows/audit-to-stories.md +22 -7
  27. package/.agents/workflows/helpers/audit-lens-core.md +8 -5
  28. package/.agents/workflows/helpers/plan-reference.md +11 -3
  29. package/docs/CHANGELOG.md +9 -0
  30. package/package.json +1 -1
@@ -68,9 +68,14 @@ file is its standalone-agent form.
68
68
  (e.g. `perf-baseline.json`).
69
69
  - Running **non-mutating** measurements/scanners the lens calls for (profilers,
70
70
  timers, `npm audit`, read-only status commands) is permitted; running
71
- anything that installs, mutates git/labels, edits source, or connects to a
72
- production database is forbidden. A lens that names a stricter carve-out
73
- tightens this for that lens.
71
+ anything that installs, mutates git/labels, or edits source is forbidden.
72
+ A lens that names a stricter carve-out tightens this for that lens.
73
+ - **Databases.** Never connect to a production database, under any
74
+ configuration. Connect to any other database only when the lens body
75
+ provides for it **and** that environment opts in via `allowAudit`, through
76
+ the environment variable named by `urlEnv`, read-only, with
77
+ `default_transaction_read_only=on` on any session you open. Never run a
78
+ migration or any statement that writes.
74
79
 
75
80
  ## Scope
76
81
 
@@ -6,7 +6,7 @@
6
6
 
7
7
  # Data Model & Persistence Audit — authoring checklist
8
8
 
9
- > Audit the persistence layer as a first-class artifact — model↔migration↔seed drift, constraint completeness, migration hygiene, type fidelity, and access-pattern fit; gated by a persistence-layer applicability probe so DB-less repos skip cleanly.
9
+ > Audit the persistence layer as a first-class artifact — model↔migration↔seed drift, constraint completeness, migration hygiene, type fidelity, access-pattern fit, and dead schema — with an opt-in read-only live-schema pass; gated by a persistence-layer applicability probe so DB-…
10
10
 
11
11
  Self-check your change against this lens's concerns before you ship:
12
12
 
@@ -20,3 +20,11 @@ Self-check your change against this lens's concerns before you ship:
20
20
  - [ ] Migration hygiene
21
21
  - [ ] Type fidelity
22
22
  - [ ] Access-pattern fit
23
+ - [ ] Dead schema
24
+ - [ ] Unused schema
25
+ - [ ] Schema gap
26
+ - [ ] Provisional until corroborated
27
+ - [ ] Common identifiers are runtime-only
28
+ - [ ] Introspection diff
29
+ - [ ] Migration ledger
30
+ - [ ] Catalog statistics (Postgres)
@@ -263,6 +263,9 @@
263
263
  "baseUrl": "http://localhost:3000",
264
264
  "signInSeam": {
265
265
  "urlTemplate": "/dev/sign-in-as/{persona}"
266
+ },
267
+ "database": {
268
+ "urlEnv": "DATABASE_URL"
266
269
  }
267
270
  },
268
271
  "staging": {
@@ -264,7 +264,7 @@ Agent-driven QA harness contract (Epic #3214; environment-keyed by Epic #4326).
264
264
  | --- | --- | --- | --- | --- |
265
265
  | `featureRoot` | No | `string` | `"tests/features"` | Directory holding the Gherkin feature files the QA sweep drives. |
266
266
  | `fixturesManifest` | No | `string` | `"tests/fixtures/personas.json"` | Path to the persona/fixture manifest the harness seeds from. |
267
- | `environments` | No | `object<map>` | `{"local":{"baseUrl":"http://localhost:3000","signInSeam":{"urlTemplate":"/dev/sign-in-as/{persona}"}},"staging":{"baseUrl":"https://staging.example.test","allowWrites":false}}` | Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`. |
267
+ | `environments` | No | `object<map>` | `{"local":{"baseUrl":"http://localhost:3000","signInSeam":{"urlTemplate":"/dev/sign-in-as/{persona}"},"database":{"urlEnv":"DATABASE_URL"}},"staging":{"baseUrl":"https://staging.example.test","allowWrites":false}}` | Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. An optional `database` object `{ urlEnv, allowAudit? }` names the environment variable holding that target's database connection string (the name only, never the URL) for the `/audit-data-model` live-schema pass; `allowAudit` gates that read-only pass and, like `allowWrites`, defaults to true only for `local`. Point `urlEnv` at a role granted catalog read only. A production database is never audited live, whatever this block says. Replaces the retired top-level single `signInSeam`. |
268
268
  | `personas` | No | one of: `array`, `object` | `{"admin":{"credentialRef":"QA_ADMIN_CREDENTIAL"},"member":{"credentialRef":"QA_MEMBER_CREDENTIAL"}}` | Personas the QA-harness sign-in seam accepts. Two accepted shapes: (1) a plain array of persona names — the honest shape for a `urlTemplate` dev-impersonation seam, where the persona name is the sole input the workflow consumes; (2) the object-map form keyed by persona name, where each entry carries per-persona auth material (`credentialRef` or `signInSkill`) consulted only under a skill-based or credential-based seam. |
269
269
  | `gherkinLint` | No | `object` | `{"scopes":{"web":{"featureRoots":["apps/web/tests/features"],"stepRoots":["apps/web/tests/steps"]}},"exemptionTags":["@skip"],"stepWaivers":[]}` | Static Gherkin corpus gate (Story #5013). Optional; the gate runs only when this block is present, so an upgrade never reddens the lint of a consumer that never asked the framework to police its `.feature` files. Inside the opt-in it fails closed: an unresolvable `@cucumber/gherkin` parser, or a scope resolving zero step definitions, exits 1 rather than reporting a clean run. |
270
270
  | `gherkinLint.scopes` | Yes | `object<map>` | — | Binding scopes, keyed by name. Each scope resolves its own features against its own step definitions only — pooling every step root into one matcher list is what makes a cross-app false bind possible, where a step defined solely in app B silently vouches for app A. The scope name appears verbatim in every unbound finding. |
@@ -41,7 +41,7 @@ description, edit the workflow file’s front-matter and regenerate.
41
41
  | `/audit-architecture` | Audit architectural boundaries, module coupling, layering violations, and shipped-but-uncalled seams; emit a structured findings report keyed to the canonical severity scale. |
42
42
  | `/audit-baselines` | Audit the committed baseline surface — dead instruments, stale baselines, cross-gate hotspot clusters, trend drift, and floor-tightening headroom — and emit findings whose remediation burns the measured debt down and tightens the ratchet behind it. |
43
43
  | `/audit-clean-code` | Audit code smells, dead code, complexity hotspots, and maintainability-index outliers; emit a structured findings report. |
44
- | `/audit-data-model` | Audit the persistence layer as a first-class artifact — model↔migration↔seed drift, constraint completeness, migration hygiene, type fidelity, and access-pattern fit; gated by a persistence-layer applicability probe so DB-less repos skip cleanly. |
44
+ | `/audit-data-model` | Audit the persistence layer as a first-class artifact — model↔migration↔seed drift, constraint completeness, migration hygiene, type fidelity, access-pattern fit, and dead schema — with an opt-in read-only live-schema pass; gated by a persistence-layer applicability probe so DB-less repos skip cleanly. |
45
45
  | `/audit-dependencies` | Audit `package.json` for unused, outdated, and major-version-stale dependencies; surface Node-engine drift and propose upgrade batches. |
46
46
  | `/audit-devops` | Audit CI/CD workflows, container images, infrastructure-as-code, and deployment pipelines; surface failure modes and hardening gaps. |
47
47
  | `/audit-documentation` | Audit the repository's main documentation for staleness, semantic drift, and completeness; emit a structured High/Medium/Low findings report. |
@@ -1439,12 +1439,15 @@
1439
1439
  },
1440
1440
  "environments": {
1441
1441
  "type": "object",
1442
- "description": "Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`.",
1442
+ "description": "Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. An optional `database` object `{ urlEnv, allowAudit? }` names the environment variable holding that target's database connection string (the name only, never the URL) for the `/audit-data-model` live-schema pass; `allowAudit` gates that read-only pass and, like `allowWrites`, defaults to true only for `local`. Point `urlEnv` at a role granted catalog read only. A production database is never audited live, whatever this block says. Replaces the retired top-level single `signInSeam`.",
1443
1443
  "default": {
1444
1444
  "local": {
1445
1445
  "baseUrl": "http://localhost:3000",
1446
1446
  "signInSeam": {
1447
1447
  "urlTemplate": "/dev/sign-in-as/{persona}"
1448
+ },
1449
+ "database": {
1450
+ "urlEnv": "DATABASE_URL"
1448
1451
  }
1449
1452
  },
1450
1453
  "staging": {
@@ -1499,6 +1502,21 @@
1499
1502
  },
1500
1503
  "allowWrites": {
1501
1504
  "type": "boolean"
1505
+ },
1506
+ "database": {
1507
+ "type": "object",
1508
+ "description": "Database target for the `/audit-data-model` read-only live-schema pass. `urlEnv` is the name of the environment variable carrying the connection string — never the URL itself. `allowAudit` opts the environment in to that pass; it defaults to true only for `local`.",
1509
+ "properties": {
1510
+ "urlEnv": {
1511
+ "type": "string",
1512
+ "pattern": "^[A-Z_][A-Z0-9_]*$"
1513
+ },
1514
+ "allowAudit": {
1515
+ "type": "boolean"
1516
+ }
1517
+ },
1518
+ "required": ["urlEnv"],
1519
+ "additionalProperties": false
1502
1520
  }
1503
1521
  },
1504
1522
  "required": ["baseUrl"],
@@ -25,7 +25,11 @@
25
25
  "foreign key",
26
26
  "constraint",
27
27
  "cascade",
28
- "backfill"
28
+ "backfill",
29
+ "unused table",
30
+ "dead column",
31
+ "drop column",
32
+ "introspect"
29
33
  ],
30
34
  "filePatterns": [
31
35
  "**/migrations/**",
@@ -3,11 +3,18 @@
3
3
  * Pure: returns a string.
4
4
  */
5
5
 
6
+ import { auditFindingRecord } from '../findings/audit-finding-record.js';
7
+ import { semanticKeyFor } from '../findings/route-finding.js';
6
8
  import { SEVERITIES, sortBySeverity } from '../findings/severity.js';
7
- import { auditLabelFooterForFindings } from './audit-label-taxonomy.js';
9
+ import {
10
+ auditLabelFooterForFindings,
11
+ definesAuditLabel,
12
+ } from './audit-label-taxonomy.js';
13
+ import { auditLabelsForFindings } from './audit-lenses.js';
8
14
  import {
9
15
  renderFingerprintFooter,
10
16
  renderSemanticKeyFooter,
17
+ toCanonicalFinding,
11
18
  } from './finding-adapter.js';
12
19
  import { findingBullets, SEED_FINDING_FIELDS } from './finding-bullets.js';
13
20
 
@@ -126,6 +133,29 @@ function formatDedupFooters(groups) {
126
133
  .join('\n');
127
134
  }
128
135
 
136
+ /**
137
+ * One `audit-finding` record per fingerprinted finding, so an N>1 plan can
138
+ * attribute each identity to the Stories that cover its files instead of
139
+ * smearing the group footers across every Story. Seed-only.
140
+ *
141
+ * @param {object[]} groups
142
+ * @returns {string}
143
+ */
144
+ function formatFindingRecords(groups) {
145
+ return groups
146
+ .flatMap((g) => (Array.isArray(g.findings) ? g.findings : []))
147
+ .filter((f) => typeof f?.fingerprint?.full === 'string')
148
+ .map((f) =>
149
+ auditFindingRecord({
150
+ sha: f.fingerprint.full,
151
+ key: semanticKeyFor(toCanonicalFinding(f)),
152
+ label: auditLabelsForFindings([f]).find(definesAuditLabel) ?? null,
153
+ files: Array.isArray(f.files) ? f.files : [],
154
+ }),
155
+ )
156
+ .join('\n');
157
+ }
158
+
129
159
  function formatKeyFiles(groups) {
130
160
  const files = new Set();
131
161
  for (const g of groups) for (const f of g.files) files.add(f);
@@ -168,7 +198,12 @@ export function buildPlanSeedMarkdown({ groups, findings, sourceReports }) {
168
198
  const scope = formatFindingsList(findings);
169
199
  const files = formatKeyFiles(groups);
170
200
  const assumptions = formatKeyAssumptions(sourceReports);
171
- const dedupFooters = formatDedupFooters(groups);
201
+ const dedupFooters = [
202
+ formatDedupFooters(groups),
203
+ formatFindingRecords(groups),
204
+ ]
205
+ .filter(Boolean)
206
+ .join('\n');
172
207
 
173
208
  return [
174
209
  '# Idea Seed: Audit Remediation',
@@ -173,7 +173,7 @@ const PREFIX_MEANINGS = Object.freeze([
173
173
  ],
174
174
  [
175
175
  'qa.environments',
176
- 'QA harness deployment target (baseUrl, per-environment sign-in seam, allowWrites gate).',
176
+ 'QA harness deployment target (baseUrl, per-environment sign-in seam, allowWrites gate, optional read-only database audit target).',
177
177
  ],
178
178
  ['qa.personas', 'QA harness persona / credential mapping.'],
179
179
  [
@@ -467,15 +467,31 @@ const QA_PERSONAS_SCHEMA = {
467
467
  ],
468
468
  };
469
469
 
470
+ // The connection string is a secret, so the config carries only the NAME of
471
+ // the environment variable that holds it — a literal URL cannot match the
472
+ // pattern, and there is no `url` key to put one in.
473
+ const QA_DATABASE_SCHEMA = {
474
+ type: 'object',
475
+ description:
476
+ 'Database target for the `/audit-data-model` read-only live-schema pass. `urlEnv` is the name of the environment variable carrying the connection string — never the URL itself. `allowAudit` opts the environment in to that pass; it defaults to true only for `local`.',
477
+ properties: {
478
+ urlEnv: { type: 'string', pattern: '^[A-Z_][A-Z0-9_]*$' },
479
+ allowAudit: { type: 'boolean' },
480
+ },
481
+ required: ['urlEnv'],
482
+ additionalProperties: false,
483
+ };
484
+
470
485
  const QA_ENVIRONMENTS_SCHEMA = {
471
486
  type: 'object',
472
487
  description:
473
- 'Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`.',
488
+ "Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. An optional `database` object `{ urlEnv, allowAudit? }` names the environment variable holding that target's database connection string (the name only, never the URL) for the `/audit-data-model` live-schema pass; `allowAudit` gates that read-only pass and, like `allowWrites`, defaults to true only for `local`. Point `urlEnv` at a role granted catalog read only. A production database is never audited live, whatever this block says. Replaces the retired top-level single `signInSeam`.",
474
489
  // Illustrative; `staging` omits `signInSeam` to show it is optional.
475
490
  default: {
476
491
  local: {
477
492
  baseUrl: 'http://localhost:3000',
478
493
  signInSeam: { urlTemplate: '/dev/sign-in-as/{persona}' },
494
+ database: { urlEnv: 'DATABASE_URL' },
479
495
  },
480
496
  staging: {
481
497
  baseUrl: 'https://staging.example.test',
@@ -489,6 +505,7 @@ const QA_ENVIRONMENTS_SCHEMA = {
489
505
  baseUrl: { ...SAFE_STRING, minLength: 1 },
490
506
  signInSeam: QA_SIGN_IN_SEAM_SCHEMA,
491
507
  allowWrites: { type: 'boolean' },
508
+ database: QA_DATABASE_SCHEMA,
492
509
  },
493
510
  // No seam is a state QA workflows handle (unauthenticated drive).
494
511
  required: ['baseUrl'],
@@ -0,0 +1,95 @@
1
+ /**
2
+ * lib/findings/audit-finding-record.js — the seed-only `audit-finding` record:
3
+ * one finding's exact sha → files → label identity, so plan-persist can
4
+ * attribute it to the Stories whose `changes[]` cover its files. Sits beside
5
+ * the footer helpers in `route-finding.js`, whose `extractProvenanceFooters`
6
+ * carries these records through a truncated seed.
7
+ *
8
+ * @module lib/findings/audit-finding-record
9
+ */
10
+
11
+ import { SHA1_RE } from './route-finding.js';
12
+
13
+ const RECORD_MARKER = 'audit-finding:';
14
+
15
+ /**
16
+ * Render one record. Every value is URI-encoded: no path can inject the `,`, space or `>` the record
17
+ * is delimited by. Never stamped on a Story body.
18
+ *
19
+ * @param {{ sha: string, key?: string, label?: string|null, files?: string[] }} record
20
+ * @returns {string}
21
+ */
22
+ export function auditFindingRecord({
23
+ sha,
24
+ key = '',
25
+ label = null,
26
+ files = [],
27
+ }) {
28
+ if (typeof sha !== 'string' || !SHA1_RE.test(sha)) {
29
+ throw new Error(
30
+ 'auditFindingRecord: sha must be a 40-char sha1 hex string',
31
+ );
32
+ }
33
+ const enc = encodeURIComponent;
34
+ const parts = [`sha=${sha}`, `key=${enc(key ?? '')}`];
35
+ if (typeof label === 'string' && label.length > 0) {
36
+ parts.push(`label=${enc(label)}`);
37
+ }
38
+ parts.push(`files=${(files ?? []).map(enc).join(',')}`);
39
+ return `<!-- ${RECORD_MARKER} ${parts.join(' ')} -->`;
40
+ }
41
+
42
+ /**
43
+ * @param {string} raw
44
+ * @returns {string|null} null when the value is not valid URI encoding.
45
+ */
46
+ function decodeRecordValue(raw) {
47
+ try {
48
+ return decodeURIComponent(raw);
49
+ } catch {
50
+ return null;
51
+ }
52
+ }
53
+
54
+ /**
55
+ * @param {string} inner — the record's `k=v k=v` payload.
56
+ * @returns {{ sha: string, key: string, label: string|null, files: string[] }|null}
57
+ */
58
+ function parseRecordPayload(inner) {
59
+ const fields = new Map();
60
+ for (const token of inner.trim().split(/\s+/)) {
61
+ const eq = token.indexOf('=');
62
+ if (eq > 0) fields.set(token.slice(0, eq), token.slice(eq + 1));
63
+ }
64
+ const sha = fields.get('sha') ?? '';
65
+ if (!SHA1_RE.test(sha)) return null;
66
+ const files = (fields.get('files') ?? '')
67
+ .split(',')
68
+ .filter((f) => f.length > 0)
69
+ .map(decodeRecordValue);
70
+ const key = decodeRecordValue(fields.get('key') ?? '');
71
+ const label = fields.has('label')
72
+ ? decodeRecordValue(fields.get('label'))
73
+ : '';
74
+ if (key === null || label === null || files.includes(null)) return null;
75
+ return { sha, key, label: label || null, files };
76
+ }
77
+
78
+ /**
79
+ * Every well-formed `audit-finding` record in `text`, first-seen per sha.
80
+ *
81
+ * @param {unknown} text
82
+ * @returns {Array<{ sha: string, key: string, label: string|null, files: string[] }>}
83
+ */
84
+ export function parseAuditFindingRecords(text) {
85
+ if (typeof text !== 'string') return [];
86
+ const out = [];
87
+ const seen = new Set();
88
+ for (const match of text.matchAll(/<!--\s*audit-finding:([^>]*?)-->/g)) {
89
+ const record = parseRecordPayload(match[1]);
90
+ if (!record || seen.has(record.sha)) continue;
91
+ seen.add(record.sha);
92
+ out.push(record);
93
+ }
94
+ return out;
95
+ }
@@ -192,8 +192,9 @@ function parseAllFooterValues(text, pattern, isValid) {
192
192
 
193
193
  /**
194
194
  * Every provenance footer in `text`, verbatim, one per line — the whole of
195
- * what `carryProvenanceFooters` and `parseAuditLabelFooter` read from a seed,
196
- * small enough to survive a seed that is cut for size.
195
+ * what `carryProvenanceFooters`, `parseAuditLabelFooter` and
196
+ * `parseAuditFindingRecords` (`audit-finding-record.js`) read from a seed, small enough to survive a seed
197
+ * that is cut for size.
197
198
  *
198
199
  * @param {unknown} text
199
200
  * @returns {string}
@@ -201,7 +202,7 @@ function parseAllFooterValues(text, pattern, isValid) {
201
202
  export function extractProvenanceFooters(text) {
202
203
  if (typeof text !== 'string') return '';
203
204
  const pattern =
204
- /<!--\s*audit-(?:fingerprints|semantic-keys|labels):[^>]*-->/g;
205
+ /<!--\s*audit-(?:fingerprints|semantic-keys|labels|finding):[^>]*-->/g;
205
206
  return [...text.matchAll(pattern)].map((m) => m[0]).join('\n');
206
207
  }
207
208