@bounded-systems/conformance-kit 0.2.0

package/gates/conformance-report.mjs

@@ -0,0 +1,128 @@
+// gates/conformance-report.mjs
+//
+// The generic conformance-projection helper. Two site-agnostic pieces:
+//
+//   buildConformanceReport({ loneFindings, evidence })
+//       Gather the standard evidence — lone's DOM findings + an external-evidence
+//       envelope whose fields are INJECTED by the consumer (SHACL conforms, SBOM
+//       present/valid/complete/signed, Repr-Digest headers present, in-toto
+//       attestation present/signed/verified, …) — call lone's `conformance()`
+//       model, and return the typed report. Anything the consumer does NOT supply
+//       (manual WCAG audit, axe scan, OWASP ASVS, field Core Web Vitals, Baseline,
+//       …) is reported `not-assessed`, never silently `met` — so automation can
+//       never print "WCAG 2.2 AA" or "ASVS conformant" on its own.
+//
+//   renderConformanceReport(report, { evidenceHref, headingLevel, idPrefix })
+//       Render a report to semantic, class-based HTML (per-area summaries, each
+//       criterion's status + an evidence link, the honest headline claim). NO
+//       hardcoded site values, brand tokens, or inline styles — the consumer wraps
+//       this fragment in its own template/stylesheet and supplies `evidenceHref`.
+//
+// Nothing here hardcodes a site URL, account, or brand. The conformance MODEL lives
+// in ./conformance/ (a zero-dep Node port of lone@0.4); this file is the reusable
+// glue + presenter on top of it.
+
+import { conformance } from "./conformance/conformance.mjs";
+import { COMPACT_CLAIM, CRITERIA, STANDARD_NAME, STANDARD_VERSION } from "./conformance/web-build.mjs";
+
+export { conformance, COMPACT_CLAIM, CRITERIA, STANDARD_NAME, STANDARD_VERSION };
+
+// lone's own sentinel for "could not read the subtree". Used when the consumer ran
+// the report in a context where lone did NOT bless a DOM (e.g. a pure, headless
+// build that has no document): the lone-measurable criteria come back `not-assessed`
+// rather than being called `met` on an absence of findings (which would be overclaim).
+const DOM_NOT_ASSESSED_FINDINGS = [{
+  code: "LONE_ENGINE_INVALID_SUBJECT",
+  severity: "error",
+  path: "",
+  message: "no DOM subject was blessed by lone in this build context",
+}];
+
+/**
+ * Gather evidence + compute the conformance report.
+ *
+ * @param {object} [opts]
+ * @param {Array<{code:string,severity:string}>|null} [opts.loneFindings] lone's DOM
+ *   findings (from the semantic gate). Pass `null`/omit when no DOM was blessed in
+ *   this context → the lone criteria report `not-assessed`. Pass `[]` only when lone
+ *   actually ran and found nothing.
+ * @param {object} [opts.evidence] The external-evidence envelope (lone's shape).
+ *   Fields with value `undefined`/`null` are pruned so they read as `not-assessed`.
+ * @returns {ConformanceReport}
+ */
+export function buildConformanceReport({ loneFindings = null, evidence = {} } = {}) {
+  const findings = Array.isArray(loneFindings) ? loneFindings : DOM_NOT_ASSESSED_FINDINGS;
+  // Prune absent fields so "not supplied" reads as not-assessed (lone's contract).
+  const ev = {};
+  for (const [k, v] of Object.entries(evidence ?? {})) {
+    if (v !== undefined && v !== null) ev[k] = v;
+  }
+  return conformance({ findings }, ev);
+}
+
+// ── HTML renderer ────────────────────────────────────────────────────────────
+
+const ESC = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" };
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ESC[c]);
+
+const STATUS_LABEL = { met: "met", unmet: "unmet", "not-assessed": "not assessed" };
+
+/**
+ * Render a conformance report to a semantic HTML fragment (class-based, no inline
+ * styles, no brand). The consumer styles `.ck-conformance`, `.ck-area`,
+ * `.ck-criterion`, and the `.ck-status--{met,unmet,not-assessed}` modifiers, and
+ * wraps the fragment in its own page template.
+ *
+ * @param {ConformanceReport} report
+ * @param {object} [opts]
+ * @param {(criterion:object)=>(string|undefined)} [opts.evidenceHref] Maps a
+ *   criterion-result to the URL of its evidence; omit/return falsy → no link.
+ * @param {number} [opts.headingLevel] Heading level for the `ck-conformance`
+ *   section title (default 2). Per-area titles render one level below it.
+ * @param {string} [opts.idPrefix] Prefix for per-criterion element ids (default "ck").
+ * @returns {string} HTML fragment
+ */
+export function renderConformanceReport(report, opts = {}) {
+  const { evidenceHref, headingLevel = 2, idPrefix = "ck" } = opts;
+  // The `ck-conformance` section heading sits at `headingLevel`; per-area
+  // sub-sections nest one level below it (a valid document outline, and it gives
+  // the outer <section> the heading vnu's `--Werror` requires).
+  const hSection = Math.min(Math.max(headingLevel | 0, 2), 6);
+  const hArea = Math.min(hSection + 1, 6);
+  const s = report.summary;
+
+  const areaBlocks = report.areaSummaries.map((a) => {
+    const inArea = report.results.filter((r) => r.area === a.area);
+    const items = inArea.map((r) => renderCriterion(r, { evidenceHref, idPrefix })).join("\n");
+    return `      <section class="ck-area" data-area="${esc(a.area)}">
+        <h${hArea} class="ck-area__title">${esc(a.area)} <span class="ck-area__count">${a.met}/${a.total} met</span></h${hArea}>
+        <p class="ck-area__summary">${esc(a.summary)}</p>
+        <ul class="ck-criteria">
+${items}
+        </ul>
+      </section>`;
+  }).join("\n");
+
+  return `<section class="ck-conformance" data-conformant="${report.conformant ? "true" : "false"}">
+      <h${hSection} class="ck-conformance__heading">Conformance</h${hSection}>
+      <p class="ck-conformance__claim" data-conformant="${report.conformant ? "true" : "false"}">${esc(report.claim)}</p>
+      <p class="ck-conformance__summary">${s.met}/${s.total} criteria met &middot; ${s.unmet} unmet &middot; ${s.notAssessed} not assessed &middot; <span class="ck-conformance__standard">${esc(report.standard)} v${esc(report.version)}</span></p>
+      <div class="ck-conformance__areas">
+${areaBlocks}
+      </div>
+    </section>`;
+}
+
+function renderCriterion(r, { evidenceHref, idPrefix }) {
+  const href = typeof evidenceHref === "function" ? evidenceHref(r) : undefined;
+  const evidenceLink = href
+    ? ` <a class="ck-criterion__evidence" href="${esc(href)}">evidence &#8599;</a>`
+    : "";
+  const tier = r.tier ?? 1;
+  return `          <li class="ck-criterion" id="${esc(idPrefix)}-${esc(r.id)}" data-status="${esc(r.status)}" data-area="${esc(r.area)}" data-tier="${esc(String(tier))}">
+            <span class="ck-criterion__status ck-status--${esc(r.status)}">${esc(STATUS_LABEL[r.status] ?? r.status)}</span>
+            <span class="ck-criterion__label">${esc(r.label)}</span>
+            <span class="ck-criterion__standard">${esc(r.standard)} &middot; ${esc(r.level)}</span>
+            <span class="ck-criterion__detail">${esc(r.detail)}</span>${evidenceLink}
+          </li>`;
+}

package/gates/html-validator-gate.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// HTML-validity gate — turns "the Nu HTML Checker passed once" into a
+// CONTINUOUSLY-ENFORCED member of the conformance contract. It runs vnu (the Nu
+// Html Checker, the reference HTML conformance checker, as a self-contained Java
+// jar — headless, no browser, no network) over a project's BUILT pages and FAILS
+// CLOSED (exit 1) when the error count exceeds a configurable threshold (default 0).
+// The machine-readable result is exactly the shape lone's conformance() model
+// consumes for `html.validator-clean` (`{ errors }`), so a clean run lets a site
+// honestly assert that criterion — and a regression turns CI red.
+//
+//   node gates/html-validator-gate.mjs [distDir]   # build gate (exit 1 over threshold)
+//
+// Everything is config-driven; NOTHING about any one site is hard-coded:
+//   argv[2] / $HTML_DIST       built output dir                     (default: "dist")
+//   $HTML_PAGES               comma list of page paths under dist   (default: every *.html)
+//   $HTML_THRESHOLD           highest tolerated error count         (default: 0)
+//   $HTML_REPORT              path to write the JSON report         (default: none)
+//
+// Requires a JRE on PATH (CI: actions/setup-java; the jar ships with `vnu-jar`).
+// The pure parse/evaluation functions are exported for unit testing without Java.
+import { writeFile, access, readdir } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { createRequire } from "node:module";
+import { spawnSync } from "node:child_process";
+
+// ── Pure core (Java-free; unit-testable) ─────────────────────────────────────
+
+/** Extract error-type messages from a vnu `--format json` payload (string or object). */
+export function parseVnu(payload) {
+  const json = typeof payload === "string" ? JSON.parse(payload || '{"messages":[]}') : (payload || {});
+  const messages = Array.isArray(json.messages) ? json.messages : [];
+  return messages.filter((m) => m && m.type === "error");
+}
+
+/** Evaluate parsed errors against the threshold. Pure: (errors[], threshold) → report. */
+export function evaluateHtml(errors, threshold = 0) {
+  const count = errors.length;
+  return {
+    passed: count <= threshold,
+    threshold,
+    errors: count,
+    // The envelope lone's conformance() consumes for `html.validator-clean`.
+    htmlValidator: { errors: count },
+    detail: errors.slice(0, 20).map((e) => ({
+      page: (e.url || "").replace(/^file:/, ""),
+      line: e.lastLine,
+      message: e.message,
+    })),
+  };
+}
+
+// ── Impure runner ────────────────────────────────────────────────────────────
+
+const require = createRequire(import.meta.url);
+
+async function walkHtml(dir, base = dir) {
+  const out = [];
+  for (const e of await readdir(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...await walkHtml(p, base));
+    else if (e.name.endsWith(".html")) out.push(p);
+  }
+  return out;
+}
+
+/** Run vnu over the given files; returns the error-type messages. vnu writes its
+ *  JSON report to stderr and exits non-zero when errors exist, so we read stderr
+ *  regardless of exit code. */
+export function runVnu(files) {
+  const jar = String(require("vnu-jar"));
+  const res = spawnSync("java", ["-jar", jar, "--errors-only", "--format", "json", ...files], {
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (res.error) throw new Error(`cannot run vnu (${res.error.message}). Is a JRE on PATH?`);
+  return parseVnu(res.stderr || '{"messages":[]}');
+}
+
+/** Walk → vnu → evaluate → report. Exposed for programmatic use and the kit's test. */
+export async function runHtmlGate({ dist, pages, threshold = 0 }) {
+  const files = pages && pages.length
+    ? pages.map((p) => resolve(dist, p))
+    : (await walkHtml(resolve(dist))).sort();
+  const report = evaluateHtml(runVnu(files), threshold);
+  report.pages = files.length;
+  return report;
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const dist = resolve(process.argv[2] && !process.argv[2].startsWith("--") ? process.argv[2] : process.env.HTML_DIST || "dist");
+  const exists = async (p) => { try { await access(p); return true; } catch { return false; } };
+  if (!(await exists(dist))) { console.error(`✗ html-validator-gate: ${dist} not found — build first.`); process.exit(2); }
+
+  const threshold = Number.parseInt(process.env.HTML_THRESHOLD ?? "0", 10);
+  if (!Number.isInteger(threshold) || threshold < 0) {
+    console.error(`✗ html-validator-gate: $HTML_THRESHOLD must be an integer ≥ 0 (got "${process.env.HTML_THRESHOLD}")`);
+    process.exit(2);
+  }
+  const pages = (process.env.HTML_PAGES || "").split(",").map((s) => s.trim().replace(/^\//, "")).filter(Boolean);
+
+  const report = await runHtmlGate({ dist, pages, threshold });
+  if (process.env.HTML_REPORT) {
+    await writeFile(resolve(process.env.HTML_REPORT), JSON.stringify(report, null, 2) + "\n");
+  }
+
+  const line = `html-validator-gate: ${report.errors} Nu HTML Checker error(s) over ${report.pages} built page(s) · threshold ${threshold}`;
+  if (!report.passed) {
+    console.error(`✗ ${line}`);
+    for (const d of report.detail) console.error(`  ${d.page} L${d.line}: ${d.message}`);
+    process.exit(1);
+  }
+  console.log(`✓ ${line}`);
+}
+
+// Only run the CLI when invoked directly (not when imported by a test).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => { console.error("✗ html-validator-gate: error —", e.stack || e.message); process.exit(1); });
+}

package/gates/readability-gate.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// Readability SIGNAL gate — a zero-dep readability report over a corpus of prose.
+//
+//   node gates/readability-gate.mjs <corpus.json>            # report (WARN-only, exit 0)
+//   node gates/readability-gate.mjs <corpus.json> --strict   # escalate WARNs (exit 1)
+//
+// HONEST FRAMING: this is a READABILITY SIGNAL, not a "cognitive-load score".
+// Flesch-Kincaid / Gunning Fog estimate a US reading grade from surface features
+// (sentence length, syllables-per-word). They do NOT measure how hard an idea is to
+// think about. The gate is WARN-by-default: it reports the signal and flags long
+// sentences, long paragraphs, passive voice, and unexplained acronyms — but it only
+// fails the build on EGREGIOUS thresholds, or when run with --strict.
+//
+// The CORPUS IS AN INPUT (each site curates its own copy): supply a JSON file that
+// is EITHER an array of { "id": "...", "text": "..." } OR an object map { id: text }.
+// Markup/HTML in text is stripped; atoms under the word floor are skipped — a
+// reading-grade formula is meaningless on a two-word button.
+//
+// Site-agnostic injection (all optional, neutral defaults):
+//   argv[2] / $READABILITY_CORPUS  path to the corpus JSON (required).
+//   $READABILITY_THRESHOLDS        JSON {gradeWarn,gradeBlock,sentWarn,sentBlock,paraWarn}.
+//   $READABILITY_MIN_WORDS         per-atom word floor (default 6).
+//   $READABILITY_KNOWN_ACRONYMS    comma list of acronyms NOT to warn on.
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const corpusPath = process.argv[2] || process.env.READABILITY_CORPUS;
+const strict = process.argv.includes("--strict");
+if (!corpusPath) { console.error("usage: readability-gate <corpus.json> [--strict]"); process.exit(2); }
+
+// Thresholds (documented, deliberately generous for terse technical copy):
+//   reading grade   WARN > 14 (college) · EGREGIOUS (block) > 22
+//   sentence length WARN > 30 words      · EGREGIOUS (block) > 60 words
+//   paragraph length WARN > 90 words
+const T = {
+  gradeWarn: 14, gradeBlock: 22, sentWarn: 30, sentBlock: 60, paraWarn: 90,
+  ...(process.env.READABILITY_THRESHOLDS ? JSON.parse(process.env.READABILITY_THRESHOLDS) : {}),
+};
+const MIN_WORDS = Number(process.env.READABILITY_MIN_WORDS || 6);
+
+// A small default of common/explained acronyms; the consumer extends via env.
+const KNOWN_ACRONYMS = new Set([
+  "AI", "CLI", "PR", "PRS", "CI", "AWS", "DOM", "HTML", "CSS", "JSON", "RDF", "URL", "RSS",
+  "SLSA", "PDF", "US", "OCI", "GHCR", "OIDC", "API", "SBOM", "CID", "IPFS",
+  "SPDX", "DNS", "MCP", "VC", "TS", "SHA", "TDD", "SHACL", "RFC", "SEO", "ID",
+  ...(process.env.READABILITY_KNOWN_ACRONYMS || "").split(",").map((s) => s.trim().toUpperCase()).filter(Boolean),
+]);
+
+// ---- text utilities (zero-dep) --------------------------------------------------
+const stripMarkup = (s) =>
+  String(s)
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&middot;|&nbsp;/g, " ")
+    .replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">")
+    .replace(/\s+/g, " ")
+    .trim();
+
+const words = (s) => (s.match(/[A-Za-z][A-Za-z'’-]*/g) || []);
+const sentences = (s) => s.split(/(?<=[.!?])\s+(?=[A-Z(])/).map((x) => x.trim()).filter(Boolean);
+
+const syllables = (w) => {
+  w = w.toLowerCase().replace(/[^a-z]/g, "");
+  if (!w) return 0;
+  let groups = (w.match(/[aeiouy]+/g) || []).length;
+  if (/e$/.test(w) && !/[aeiouy]e$/.test(w) && groups > 1) groups--; // silent final e
+  return Math.max(1, groups);
+};
+const complex = (w) => syllables(w) >= 3; // Gunning Fog "complex word"
+
+// ---- load + normalise the corpus -------------------------------------------------
+const raw = JSON.parse(await readFile(resolve(corpusPath), "utf8"));
+const entries = Array.isArray(raw)
+  ? raw.map((e) => [e.id, e.text])
+  : Object.entries(raw).filter(([id, v]) => !id.startsWith("_") && typeof v === "string");
+
+const corpus = []; // { id, text }
+for (const [id, text] of entries) {
+  const t = stripMarkup(text);
+  if (t && words(t).length >= MIN_WORDS) corpus.push({ id, text: t });
+}
+if (corpus.length === 0) { console.error(`✗ readability-gate: no prose atoms (≥ ${MIN_WORDS} words) in ${corpusPath}`); process.exit(2); }
+
+// ---- score ----------------------------------------------------------------------
+let warns = 0, blocks = 0;
+const warn = (m) => { console.log(`  ⚠ ${m}`); warns++; };
+const block = (m) => { console.error(`  ✗ ${m}`); blocks++; };
+
+const PASSIVE = /\b(?:is|are|was|were|be|been|being|am)\b\s+(?:[a-z]+ly\s+)?(?:[a-z]+ed|written|built|made|done|shown|given|held|kept|driven|known|seen|taken|drawn|met|run|set|read|put|sent|brought|caught)\b/gi;
+
+let totW = 0, totS = 0, totSyl = 0, totComplex = 0;
+for (const { id, text } of corpus) {
+  const ws = words(text);
+  const ss = sentences(text);
+  const syl = ws.reduce((a, w) => a + syllables(w), 0);
+  const cx = ws.filter(complex).length;
+  totW += ws.length; totS += ss.length; totSyl += syl; totComplex += cx;
+
+  for (const s of ss) {
+    const n = words(s).length;
+    if (n > T.sentBlock) block(`${id}: sentence of ${n} words exceeds egregious cap (${T.sentBlock}) — "${s.slice(0, 70)}…"`);
+    else if (n > T.sentWarn) warn(`${id}: long sentence (${n} words) — "${s.slice(0, 70)}…"`);
+  }
+  if (ws.length > T.paraWarn) warn(`${id}: long paragraph (${ws.length} words)`);
+  for (const m of text.match(PASSIVE) || []) warn(`${id}: possible passive voice — "${m.trim()}"`);
+  for (const tok of text.match(/\b[A-Z][A-Z0-9]{1,6}s?\b/g) || []) {
+    const base = tok.replace(/s$/, "").toUpperCase();
+    if (!KNOWN_ACRONYMS.has(tok.toUpperCase()) && !KNOWN_ACRONYMS.has(base)) warn(`${id}: unexplained acronym "${tok}"`);
+  }
+}
+
+const fk = 0.39 * (totW / totS) + 11.8 * (totSyl / totW) - 15.59;
+const fog = 0.4 * ((totW / totS) + 100 * (totComplex / totW));
+const grade = (fk + fog) / 2;
+const g = (x) => x.toFixed(1);
+
+console.log("");
+console.log(`readability signal (${corpus.length} prose atoms, ${totW} words, ${totS} sentences):`);
+console.log(`  Flesch-Kincaid grade ${g(fk)} · Gunning Fog ${g(fog)} · mean ${g(grade)}`);
+console.log(`  (a US reading-grade SIGNAL from sentence length + syllables — NOT a cognitive-load score)`);
+console.log("");
+
+if (grade > T.gradeBlock) block(`mean reading grade ${g(grade)} exceeds egregious cap (${T.gradeBlock})`);
+else if (grade > T.gradeWarn) warn(`mean reading grade ${g(grade)} above college level (${T.gradeWarn})`);
+
+console.log("");
+if (blocks) {
+  console.error(`✗ readability-gate: ${blocks} egregious finding(s), ${warns} warning(s).`);
+  process.exit(1);
+}
+if (strict && warns) {
+  console.error(`✗ readability-gate (--strict): ${warns} warning(s) escalated to errors.`);
+  process.exit(1);
+}
+console.log(`✓ readability-gate: signal reported — ${warns} warning(s), 0 egregious. (WARN-only; pass --strict to block on warnings.)`);

package/gates/sbom/check-sbom.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// check-sbom — the fail-closed completeness gate tying the SPDX SBOM to the
+// flake.lock pinned set (+ an optional in-toto/SLSA statement). A violation refuses
+// the build (process.exit(1)) rather than shipping an incomplete bill.
+//
+// It enforces three things over $DIST/sbom.spdx.json (+ flake.lock, + an optional
+// $DIST/attestation.intoto.json), all decidable / order-free:
+//   1. SPDX 2.3 well-formedness — the document + every package carry their required
+//      fields (spdxVersion SPDX-2.3, SPDXID, dataLicense, namespace, creationInfo;
+//      per package: name, SPDXID, downloadLocation).
+//   2. Pinned-set ⊆ SBOM — every Nix flake input pinned in flake.lock appears as an
+//      SPDX package at the SAME rev, and any package-reference (pkg:…) the
+//      attestation enumerates as a resolvedDependency appears in the SBOM at the
+//      SAME rev. (File-path materials are content inputs, not redistributable
+//      packages, so they are intentionally out of SBOM scope.)
+//   3. SBOM ⊆ pinned-set (vice-versa) — every Nix-sourced SPDX package (pkg:github)
+//      traces back to a real flake.lock rev: no orphan Nix entries the build can't pin.
+//
+// Site-agnostic injection (all optional, neutral defaults):
+//   $ROOT  repo root with flake.lock (default: cwd).
+//   $DIST  dir holding the SBOM + optional attestation (default: $ROOT/dist).
+//   $SBOM_OUT  SBOM filename under $DIST (default: "sbom.spdx.json").
+import { readFile, access } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+// $ROOT / $DIST may be absolute or relative-to-cwd (resolve handles both).
+const root = resolve(process.cwd(), process.env.ROOT || ".");
+const dist = process.env.DIST ? resolve(process.cwd(), process.env.DIST) : join(root, "dist");
+const outName = process.env.SBOM_OUT || "sbom.spdx.json";
+
+const exists = async (p) => { try { await access(p); return true; } catch { return false; } };
+const readJson = async (p) => JSON.parse(await readFile(p, "utf8"));
+
+const errors = [];
+const fail = (msg) => errors.push(msg);
+
+const sbomPath = join(dist, outName);
+const attPath = join(dist, "attestation.intoto.json");
+if (!(await exists(sbomPath))) { console.error(`✗ check:sbom: ${outName} missing — run gen-sbom.mjs first`); process.exit(1); }
+
+const sbom = await readJson(sbomPath);
+const flakeLock = (await exists(join(root, "flake.lock"))) ? await readJson(join(root, "flake.lock")) : { nodes: {} };
+
+// ---- 1. SPDX 2.3 well-formedness --------------------------------------------
+if (sbom.spdxVersion !== "SPDX-2.3") fail(`spdxVersion is "${sbom.spdxVersion}", expected "SPDX-2.3"`);
+if (sbom.SPDXID !== "SPDXRef-DOCUMENT") fail(`document SPDXID is "${sbom.SPDXID}", expected "SPDXRef-DOCUMENT"`);
+if (!sbom.dataLicense) fail("document missing dataLicense");
+if (!sbom.name) fail("document missing name");
+if (!sbom.documentNamespace) fail("document missing documentNamespace");
+if (!sbom.creationInfo?.created) fail("document missing creationInfo.created");
+if (!Array.isArray(sbom.creationInfo?.creators) || sbom.creationInfo.creators.length === 0) fail("document missing creationInfo.creators");
+if (!Array.isArray(sbom.packages) || sbom.packages.length === 0) fail("document has no packages");
+const seenIds = new Set();
+for (const p of sbom.packages || []) {
+  const tag = p.name || p.SPDXID || "(unnamed)";
+  if (!p.name) fail(`package ${tag} missing name`);
+  if (!p.SPDXID) fail(`package ${tag} missing SPDXID`);
+  if (!/^SPDXRef-[a-zA-Z0-9.-]+$/.test(p.SPDXID || "")) fail(`package ${tag} has malformed SPDXID "${p.SPDXID}"`);
+  if (p.SPDXID && seenIds.has(p.SPDXID)) fail(`duplicate SPDXID ${p.SPDXID}`);
+  seenIds.add(p.SPDXID);
+  if (!p.downloadLocation) fail(`package ${tag} missing downloadLocation`);
+}
+
+// rev → package index (Nix packages record the locked commit as versionInfo)
+const revToPkg = new Map();
+const nixPkgs = [];
+for (const p of sbom.packages || []) {
+  const purl = (p.externalRefs || []).find((r) => r.referenceType === "purl")?.referenceLocator || "";
+  if (purl.startsWith("pkg:github/")) {
+    nixPkgs.push({ pkg: p, purl });
+    if (p.versionInfo) revToPkg.set(p.versionInfo, p);
+  }
+}
+
+// ---- 2. Pinned-set ⊆ SBOM ----------------------------------------------------
+// 2a. every flake.lock input is in the SBOM at its locked rev
+const flakeRevs = new Set();
+for (const [nodeName, node] of Object.entries(flakeLock.nodes || {})) {
+  if (nodeName === "root") continue;
+  const rev = node.locked?.rev;
+  if (!rev) continue;
+  flakeRevs.add(rev);
+  if (!revToPkg.has(rev)) fail(`flake.lock input "${nodeName}" (rev ${rev.slice(0, 12)}…) is not an SPDX package`);
+}
+
+// 2b. every package-reference material in the attestation is in the SBOM
+if (await exists(attPath)) {
+  const att = await readJson(attPath);
+  const deps = att.predicate?.buildDefinition?.resolvedDependencies || [];
+  for (const d of deps) {
+    const isPkgRef = (typeof d.uri === "string" && d.uri.startsWith("pkg:")) || d.digest?.gitCommit;
+    if (!isPkgRef) continue; // file-path / source materials are out of SBOM scope
+    const rev = d.digest?.gitCommit;
+    if (rev && !revToPkg.has(rev)) fail(`attestation material "${d.uri}" (gitCommit ${rev.slice(0, 12)}…) is not an SPDX package`);
+    if (!rev) fail(`attestation package-ref "${d.uri}" has no gitCommit to reconcile against the SBOM`);
+  }
+} else {
+  console.warn("… check:sbom: attestation.intoto.json not present — skipping attestation cross-check (run the full build to enforce it)");
+}
+
+// ---- 3. SBOM ⊆ pinned-set (vice-versa) --------------------------------------
+for (const { pkg, purl } of nixPkgs) {
+  if (!pkg.versionInfo || !flakeRevs.has(pkg.versionInfo))
+    fail(`Nix-sourced SPDX package "${pkg.name}" (${purl}) has no matching flake.lock rev — orphan entry`);
+}
+
+if (errors.length) {
+  console.error(`✗ check:sbom: ${errors.length} completeness violation(s) — refusing to ship an incomplete SBOM:`);
+  for (const e of errors) console.error(`    ${e}`);
+  process.exit(1);
+}
+console.log(`✓ check:sbom: SPDX-2.3 well-formed · ${sbom.packages.length} packages · pinned set (${flakeRevs.size} flake inputs) ⊆ SBOM ⊆ pinned set.`);

package/gates/sbom/gen-sbom.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// gen-sbom — emit a deterministic SPDX 2.3 SBOM for the WHOLE supply chain a build
+// pulls from: the npm lockfiles + (optionally) the Nix flake.lock inputs.
+//
+// It reads the committed lockfiles (the single source of truth) and emits one
+// SPDX-2.3 JSON. Each package carries a versionInfo, a downloadLocation, and a
+// checksum + purl externalRef:
+//   • npm packages  — from package-lock.json (+ any extra lockfiles); integrity hash
+//                     (base64 SRI) decoded to a hex SPDX checksum, downloadLocation =
+//                     the resolved registry tarball.
+//   • Nix inputs    — from flake.lock (if present); narHash (sha256 SRI) decoded to a
+//                     hex SPDX SHA256 checksum, rev pinned via a pkg:github purl + a
+//                     git+https downloadLocation.
+//
+// Pure + deterministic: a function of the lockfiles only (no network, no clock — the
+// creation timestamp is derived from flake.lock's newest lastModified when present,
+// else epoch 0; output is sorted; the namespace is content-derived). Zero deps.
+//
+// Site-agnostic injection (all optional, neutral defaults):
+//   $ROOT                 repo root containing the lockfiles (default: cwd).
+//   $DIST                 output dir (default: $ROOT/dist).
+//   $SBOM_LOCKFILES       comma list of npm lockfile paths, relative to $ROOT
+//                         (default: "package-lock.json").
+//   $SBOM_NAME            SPDX document name (default: "<basename(ROOT)>-sbom").
+//   $SBOM_NAMESPACE_BASE  documentNamespace prefix; the content fingerprint is
+//                         appended (default: "https://spdx.invalid/sbom").
+//   $SBOM_CREATORS        comma list of SPDX creators
+//                         (default: "Tool: gen-sbom.mjs").
+//   $SBOM_OUT             output filename under $DIST (default: "sbom.spdx.json").
+import { readFile, writeFile, access } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join, basename, resolve } from "node:path";
+
+// $ROOT / $DIST may be absolute or relative-to-cwd (resolve handles both).
+const root = resolve(process.cwd(), process.env.ROOT || ".");
+const dist = process.env.DIST ? resolve(process.cwd(), process.env.DIST) : join(root, "dist");
+const lockfiles = (process.env.SBOM_LOCKFILES || "package-lock.json").split(",").map((s) => s.trim()).filter(Boolean);
+const docName = process.env.SBOM_NAME || `${basename(root)}-sbom`;
+const nsBase = (process.env.SBOM_NAMESPACE_BASE || "https://spdx.invalid/sbom").replace(/\/$/, "");
+const creators = (process.env.SBOM_CREATORS || "Tool: gen-sbom.mjs").split(",").map((s) => s.trim()).filter(Boolean);
+const outName = process.env.SBOM_OUT || "sbom.spdx.json";
+
+const exists = async (p) => { try { await access(p); return true; } catch { return false; } };
+const readJson = async (p) => JSON.parse(await readFile(p, "utf8"));
+
+// SPDXID must be [a-zA-Z0-9.-]; map everything else to '-' so @scope/name@1.2.3
+// becomes a legal, collision-resistant element id.
+const spdxId = (s) => "SPDXRef-Package-" + s.replace(/[^a-zA-Z0-9.-]/g, "-");
+const SRI_ALG = { sha512: "SHA512", sha384: "SHA384", sha256: "SHA256", sha1: "SHA1" };
+// Decode an SRI hash (alg-<base64>) → { algorithm, checksumValue } in lowercase hex,
+// the only checksum form SPDX accepts. Returns null for anything unrecognised.
+const sriToChecksum = (sri) => {
+  if (typeof sri !== "string" || !sri.includes("-")) return null;
+  const [alg, b64] = [sri.slice(0, sri.indexOf("-")), sri.slice(sri.indexOf("-") + 1)];
+  const algorithm = SRI_ALG[alg];
+  if (!algorithm || !b64) return null;
+  return { algorithm, checksumValue: Buffer.from(b64, "base64").toString("hex") };
+};
+
+// Collect every resolved npm package across the given lockfiles, keyed name@version
+// (deduped). lockfileVersion 3: packages[<path>] with version/resolved/integrity.
+async function collectNpm(lockPaths) {
+  const pkgs = new Map();
+  for (const lp of lockPaths) {
+    if (!(await exists(join(root, lp)))) continue;
+    const lock = await readJson(join(root, lp));
+    for (const [key, p] of Object.entries(lock.packages || {})) {
+      if (!key.startsWith("node_modules/")) continue;   // skip the project root ("")
+      if (!p.version || !p.resolved) continue;          // skip links/workspaces
+      const name = key.slice(key.lastIndexOf("node_modules/") + "node_modules/".length);
+      const id = `${name}@${p.version}`;
+      if (pkgs.has(id)) continue;
+      pkgs.set(id, {
+        kind: "npm",
+        name,
+        versionInfo: p.version,
+        downloadLocation: p.resolved,
+        purl: `pkg:npm/${name}@${p.version}`,
+        checksum: sriToChecksum(p.integrity),
+        license: typeof p.license === "string" ? p.license : null,
+      });
+    }
+  }
+  return [...pkgs.values()];
+}
+
+// Collect the Nix flake inputs. Each is pinned by a commit rev + narHash; narHash is
+// an sha256 SRI we decode to a hex SPDX checksum.
+function collectNix(flakeLock) {
+  const out = [];
+  for (const [nodeName, node] of Object.entries(flakeLock.nodes || {})) {
+    if (nodeName === "root") continue;
+    const lk = node.locked;
+    if (!lk || !lk.rev) continue;
+    const name = lk.repo ? `${lk.owner}/${lk.repo}` : nodeName;
+    const downloadLocation = lk.type === "github"
+      ? `git+https://github.com/${lk.owner}/${lk.repo}@${lk.rev}`
+      : `git+https://${lk.owner || ""}/${lk.repo || nodeName}@${lk.rev}`;
+    out.push({
+      kind: "nix",
+      node: nodeName,
+      name,
+      versionInfo: lk.rev,
+      downloadLocation,
+      purl: `pkg:github/${lk.owner}/${lk.repo}@${lk.rev}`,
+      checksum: sriToChecksum(lk.narHash),
+      rev: lk.rev,
+      lastModified: lk.lastModified || 0,
+      license: null,
+    });
+  }
+  return out;
+}
+
+const flakeLock = (await exists(join(root, "flake.lock"))) ? await readJson(join(root, "flake.lock")) : { nodes: {} };
+const npm = await collectNpm(lockfiles);
+const nix = collectNix(flakeLock);
+
+// Deterministic order: kind (nix before npm) then name then version.
+const all = [...nix, ...npm].sort((a, b) =>
+  (a.kind === b.kind ? 0 : a.kind === "nix" ? -1 : 1) ||
+  a.name.localeCompare(b.name) || a.versionInfo.localeCompare(b.versionInfo));
+
+const packages = all.map((p) => {
+  const externalRefs = [{ referenceCategory: "PACKAGE-MANAGER", referenceType: "purl", referenceLocator: p.purl }];
+  return {
+    name: p.name,
+    SPDXID: spdxId(`${p.name}@${p.versionInfo}`),
+    versionInfo: p.versionInfo,
+    downloadLocation: p.downloadLocation,
+    filesAnalyzed: false,
+    licenseConcluded: "NOASSERTION",
+    licenseDeclared: p.license || "NOASSERTION",
+    copyrightText: "NOASSERTION",
+    ...(p.checksum ? { checksums: [p.checksum] } : {}),
+    externalRefs,
+  };
+});
+
+// Deterministic, content-derived bits: no wall clock. The creation date is the
+// newest flake.lock lastModified (a pure function of the pinned inputs; epoch 0 when
+// no flake); the namespace is a digest of the package set so identical lockfiles →
+// identical document, byte-for-byte.
+const newest = Math.max(0, ...nix.map((p) => p.lastModified));
+const created = new Date(newest * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+const fingerprint = createHash("sha256").update(JSON.stringify(packages)).digest("hex");
+
+const doc = {
+  spdxVersion: "SPDX-2.3",
+  dataLicense: "CC0-1.0",
+  SPDXID: "SPDXRef-DOCUMENT",
+  name: docName,
+  documentNamespace: `${nsBase}/${fingerprint}`,
+  creationInfo: {
+    created,
+    creators,
+  },
+  packages,
+  relationships: packages.map((p) => ({
+    spdxElementId: "SPDXRef-DOCUMENT",
+    relationshipType: "DESCRIBES",
+    relatedSpdxElement: p.SPDXID,
+  })),
+};
+
+await writeFile(join(dist, outName), JSON.stringify(doc, null, 2) + "\n");
+console.log(`✓ SBOM: ${packages.length} packages (${nix.length} Nix + ${npm.length} npm) → ${process.env.DIST || "dist"}/${outName} (SPDX-2.3)`);