stylegallery 0.1.0

package/scripts/finalize-component-state-evidence.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { artifactMetadata } from "./artifact-metadata.mjs";
+import {
+  canonicalIntended,
+  readCaptureSession,
+  sameJson,
+  sourceManifestMatches,
+} from "./capture-session-contract.mjs";
+import { compileSchemas, validateEvidenceArtifacts } from "./component-state-contract.mjs";
+import { resolveProfileRecords } from "./profile-record-contract.mjs";
+import { parseStrictJson } from "./strict-json.mjs";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const options = {
+  artifactRoot: undefined,
+  json: false,
+  output: undefined,
+  profileRoot: path.join(repositoryRoot, "design-engineering/reference-profiles/governed-local"),
+  sessionReceipt: undefined,
+  writeCanonical: false,
+};
+const failures = [];
+
+for (let index = 2; index < process.argv.length; index += 1) {
+  const argument = process.argv[index];
+  if (argument === "--json") options.json = true;
+  else if (argument === "--write-canonical") options.writeCanonical = true;
+  else if (["--artifact-root", "--output", "--root", "--session-receipt"].includes(argument)) {
+    const value = process.argv[index + 1];
+    if (!value) failures.push({ code: "argument_value_required", message: `${argument} requires a value`, path: "<cli>" });
+    else {
+      if (argument === "--artifact-root") options.artifactRoot = path.resolve(value);
+      if (argument === "--output") options.output = path.resolve(value);
+      if (argument === "--root") options.profileRoot = path.resolve(value);
+      if (argument === "--session-receipt") options.sessionReceipt = path.resolve(value);
+      index += 1;
+    }
+  } else failures.push({ code: "argument_unknown", message: `unsupported argument ${argument}`, path: "<cli>" });
+}
+
+if (!options.artifactRoot) failures.push({ code: "argument_value_required", message: "--artifact-root is required", path: "<cli>" });
+const output = options.output ?? (options.artifactRoot ? path.join(options.artifactRoot, "runtime-manifest.json") : undefined);
+if (output && fs.existsSync(output)) failures.push({ code: "capture_session_replay", message: "completed session manifest already exists and cannot be overwritten", path: output });
+const receiptFile = options.sessionReceipt ?? (options.artifactRoot ? path.join(options.artifactRoot, "capture-session.json") : "");
+if (options.artifactRoot && receiptFile !== path.join(options.artifactRoot, "capture-session.json")) failures.push({ code: "capture_session_path_invalid", message: "session receipt must be the artifact-root capture-session.json", path: receiptFile });
+const schemas = compileSchemas(path.join(repositoryRoot, "consumer-reference/schema"));
+const capture = receiptFile ? readCaptureSession(receiptFile, schemas.capture, failures) : undefined;
+const intended = canonicalIntended(options.profileRoot, failures);
+if (capture && !sameJson(capture.receipt.intended, intended)) failures.push({ code: "capture_session_intent_mismatch", message: "receipt intent differs from canonical profile scenarios", path: receiptFile });
+if (capture && !capture.receipt.source) failures.push({ code: "capture_source_missing", message: "capture receipt must include its canonical source manifest", path: receiptFile });
+else if (capture && !sourceManifestMatches(capture.receipt.source, repositoryRoot, options.profileRoot)) failures.push({ code: "capture_source_drift", message: "capture sources differ from the receipt source manifest", path: receiptFile });
+
+const completedAt = new Date().toISOString();
+const completedSession = capture ? {
+  attempt: capture.receipt.attempt,
+  branch: capture.receipt.branch,
+  completed_at: completedAt,
+  environment: capture.receipt.environment,
+  intended: capture.receipt.intended,
+  nonce: capture.receipt.nonce,
+  receipt: capture.artifact,
+  receipt_sha256: capture.digest,
+  repository: capture.receipt.repository,
+  revision: capture.receipt.revision,
+  session_id: capture.receipt.session_id,
+  source: capture.receipt.source,
+  started_at: capture.receipt.started_at,
+} : undefined;
+const run = capture ? {
+  attempt: capture.receipt.attempt,
+  id: capture.receipt.session_id,
+  repository: capture.receipt.repository,
+  revision: capture.receipt.revision,
+  source: process.env.GITHUB_ACTIONS === "true" ? "github_actions" : "local",
+} : undefined;
+const channelFiles = Object.freeze({ ax: "ax.json", dom: "dom.json", visual: "png" });
+const records = [];
+const expectedFiles = new Set();
+const canonicalWrites = [];
+
+for (const profileIntent of intended) {
+  const profileRoot = path.join(options.profileRoot, profileIntent.profile_name);
+  const profileFailures = [];
+  const resolved = resolveProfileRecords(profileRoot, profileFailures);
+  failures.push(...profileFailures);
+  const fixture = resolved?.records.fixture[0]?.value;
+  const states = resolved?.records.states[0]?.value;
+  if (!resolved || !fixture || !states || !capture || !run || !completedSession) continue;
+  const stateById = new Map(states.scenarios.map((scenario) => [scenario.id, scenario]));
+  const passes = [];
+  for (const scenario of fixture.scenarios) {
+    const canonical = stateById.get(scenario.id);
+    const documents = {};
+    for (const channel of ["dom", "ax", "visual"]) {
+      const file = path.join(options.artifactRoot, "runtime", `${profileIntent.profile_name}-${scenario.id}.${channel}.json`);
+      try { documents[channel] = parseStrictJson(fs.readFileSync(file, "utf8")); }
+      catch (error) { failures.push({ code: "evidence_json_invalid", message: error instanceof Error ? error.message : String(error), path: file }); }
+      if (channel === "visual") expectedFiles.add(path.basename(file));
+    }
+    const capturedTimes = new Set(Object.values(documents).map((document) => document?.captured_at).filter(Boolean));
+    if (capturedTimes.size !== 1) failures.push({ code: "capture_session_time_mismatch", message: `${scenario.id} visual, DOM, and AX must share one captured_at`, path: profileRoot });
+    const recordedAt = [...capturedTimes][0] ?? "";
+    for (const channel of scenario.required_channels) {
+      const suffix = channelFiles[channel];
+      const artifactPath = `runtime/${profileIntent.profile_name}-${scenario.id}.${suffix}`;
+      expectedFiles.add(path.basename(artifactPath));
+      const absolute = path.join(options.artifactRoot, artifactPath);
+      if (!fs.existsSync(absolute) || !fs.lstatSync(absolute).isFile() || fs.lstatSync(absolute).isSymbolicLink()) {
+        failures.push({ code: "runtime_artifact_missing", message: `${artifactPath} is missing or not a regular file`, path: absolute });
+        continue;
+      }
+      const mediaType = channel === "visual" ? "image/png" : "application/json";
+      passes.push({
+        artifact: { path: artifactPath, ...artifactMetadata(fs.readFileSync(absolute), mediaType) },
+        channel,
+        environment: capture.receipt.environment,
+        id: `${scenario.id}-${channel}`,
+        recorded_at: recordedAt,
+        result: { observed: `Recorded ${channel} evidence for ${scenario.id}; this is not certification.`, status: "passed" },
+        run,
+        scenario_id: scenario.id,
+        session: capture.link,
+        scope: { component: "button", semantic_mode: scenario.semantic_mode, state_set: canonical.states },
+      });
+    }
+  }
+  const evidence = {
+    claim_boundary: "Scenario artifacts are evidence, not visual regression baselines or accessibility certification.",
+    component_id: "button",
+    passes,
+    profile_id: resolved.profile.id,
+    schema_version: "1.0",
+  };
+  failures.push(...validateEvidenceArtifacts(profileRoot, options.artifactRoot, evidence, schemas, completedSession));
+  records.push(evidence);
+  if (resolved.records.evidence[0]) canonicalWrites.push([resolved.records.evidence[0].path, evidence]);
+}
+
+const runtimeRoot = options.artifactRoot ? path.join(options.artifactRoot, "runtime") : "";
+if (runtimeRoot && fs.existsSync(runtimeRoot)) {
+  for (const entry of fs.readdirSync(runtimeRoot, { withFileTypes: true })) if (!entry.isFile() || !expectedFiles.has(entry.name)) failures.push({ code: "runtime_artifact_unmanifested", message: `${entry.name} is not part of the closed artifact set`, path: path.join(runtimeRoot, entry.name) });
+}
+
+const manifest = {
+  claim_boundary: "Scenario artifacts are evidence, not visual regression baselines or accessibility certification.",
+  environment: capture?.receipt.environment,
+  recorded_at: completedAt,
+  record_kind: "component_state_runtime_manifest",
+  records,
+  run,
+  schema_version: "1.0",
+  session: completedSession,
+};
+if (!schemas.runtime(manifest)) for (const error of schemas.runtime.errors ?? []) failures.push({ code: "runtime_manifest_schema_invalid", message: `${error.instancePath || "/"} ${error.message}`, path: options.output ?? "<manifest>" });
+if (failures.length === 0 && options.writeCanonical) for (const [file, evidence] of canonicalWrites) fs.writeFileSync(file, `${JSON.stringify(evidence, null, 2)}\n`);
+if (failures.length === 0 && output) fs.writeFileSync(output, `${JSON.stringify(manifest, null, 2)}\n`);
+const result = { artifactCount: expectedFiles.size, failures, manifest: output, ok: failures.length === 0, profileCount: records.length, sessionId: capture?.receipt.session_id };
+if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+else if (result.ok) process.stdout.write(`finalized ${result.artifactCount} component state artifacts\n`);
+else process.stderr.write(`${failures.map((failure) => `${failure.code}: ${failure.path}: ${failure.message}`).join("\n")}\n`);
+if (!result.ok) process.exitCode = 1;

package/scripts/finalize-page-evidence.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  addSchemaFindings,
+  canonicalSourceManifest,
+  compilePageEvidenceSchemas,
+  dirtyRelevantSources,
+  finding,
+  gitIdentity,
+  listArtifactFiles,
+  metadata,
+  normalizeReference,
+  PAGE_EVIDENCE_CLAIM,
+  PAGE_EVIDENCE_MANIFEST,
+  PAGE_EVIDENCE_RECEIPT,
+  readJsonFile,
+  readContainedBytes,
+  readReceipt,
+  resolveContained,
+  sameJson,
+  sameStringSet,
+  withinSession,
+} from "./page-evidence-contract.mjs";
+
+const styleGalleryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const options = { artifactRoot: undefined, json: false, priorManifest: undefined, reviewBy: undefined, root: undefined, runnerResults: [] };
+const failures = [];
+
+for (let index = 2; index < process.argv.length; index += 1) {
+  const argument = process.argv[index];
+  if (argument === "--json") options.json = true;
+  else if (["--artifact-root", "--prior-manifest", "--review-by", "--root", "--runner-result"].includes(argument)) {
+    const value = process.argv[index + 1];
+    if (!value || value.startsWith("--")) failures.push(finding("argument_value_required", `${argument} requires a value`, "<cli>"));
+    else {
+      if (argument === "--artifact-root") options.artifactRoot = path.resolve(process.cwd(), value);
+      if (argument === "--prior-manifest") options.priorManifest = value;
+      if (argument === "--review-by") options.reviewBy = value;
+      if (argument === "--root") options.root = path.resolve(process.cwd(), value);
+      if (argument === "--runner-result") options.runnerResults.push(value);
+      index += 1;
+    }
+  } else failures.push(finding("argument_unknown", `unsupported argument ${argument}`, "<cli>"));
+}
+for (const [name, value] of [["--root", options.root], ["--artifact-root", options.artifactRoot], ["--review-by", options.reviewBy]]) {
+  if (!value) failures.push(finding("argument_value_required", `${name} is required`, "<cli>"));
+}
+if (options.runnerResults.length === 0) failures.push(finding("argument_value_required", "at least one --runner-result is required", "<cli>"));
+
+let schemas;
+try { schemas = compilePageEvidenceSchemas(path.join(styleGalleryRoot, "consumer-reference/schema")); }
+catch (error) { failures.push(finding("page_evidence_schema_invalid", error instanceof Error ? error.message : String(error), "consumer-reference/schema")); }
+
+let artifactReference;
+let artifactFiles = [];
+if (options.root && options.artifactRoot) {
+  artifactReference = normalizeReference(options.root, options.artifactRoot);
+  if (!artifactReference) failures.push(finding("page_evidence_artifact_escape", "artifact root must be inside the consumer repository", options.artifactRoot));
+  else if (fs.existsSync(options.artifactRoot) && fs.lstatSync(options.artifactRoot).isSymbolicLink()) failures.push(finding("page_evidence_artifact_redirect", "artifact root must not be a filesystem redirect", artifactReference));
+  else {
+    const resolved = resolveContained({ expectedType: "directory", prefix: "page_evidence_artifact", reference: artifactReference, root: options.root }, failures);
+    if (resolved) artifactFiles = listArtifactFiles(options.artifactRoot, failures);
+  }
+}
+const packetWithinLimits = !failures.some((entry) => entry.code === "page_evidence_artifact_limit");
+const manifestFile = options.artifactRoot ? path.join(options.artifactRoot, PAGE_EVIDENCE_MANIFEST) : undefined;
+if (manifestFile && fs.existsSync(manifestFile)) failures.push(finding("page_evidence_session_replay", "completed manifest already exists and cannot be overwritten", PAGE_EVIDENCE_MANIFEST));
+const receiptRecord = options.artifactRoot && schemas && packetWithinLimits ? readReceipt(options.artifactRoot, schemas, failures) : undefined;
+const receipt = receiptRecord?.valid ? receiptRecord : undefined;
+
+const git = options.root ? gitIdentity(options.root, failures) : undefined;
+if (receipt && git) {
+  if (git.revision !== receipt.value.revision) failures.push(finding("page_evidence_revision_mismatch", "checked-out revision differs from the start receipt", PAGE_EVIDENCE_RECEIPT));
+  if (git.repository && git.repository !== receipt.value.repository) failures.push(finding("page_evidence_repository_mismatch", "Git remote identity differs from the start receipt", PAGE_EVIDENCE_RECEIPT));
+}
+
+if (receipt && options.root) {
+  const sourcePaths = receipt.value.source.files.map((entry) => entry.path);
+  const currentSource = canonicalSourceManifest(options.root, sourcePaths, failures);
+  if (currentSource && !sameJson(currentSource, receipt.value.source)) failures.push(finding("page_evidence_source_drift", "relevant source bytes differ from the start receipt", PAGE_EVIDENCE_RECEIPT));
+  if (dirtyRelevantSources(options.root, sourcePaths).length > 0) failures.push(finding("page_evidence_source_drift", "relevant sources became dirty after session start", PAGE_EVIDENCE_RECEIPT));
+  const conformance = readJsonFile({ prefix: "page_evidence_conformance", reference: receipt.value.conformance_record.path, root: options.root }, failures);
+  if (conformance && !sameJson(metadata(conformance.bytes, "application/json", conformance.reference), receipt.value.conformance_record)) failures.push(finding("page_evidence_conformance_drift", "conformance record differs from the start receipt", conformance.reference));
+}
+
+let prior;
+if (options.priorManifest && options.root && schemas) {
+  const reference = normalizeReference(options.root, options.priorManifest);
+  if (!reference) failures.push(finding("page_evidence_reuse_manifest_escape", "prior manifest must be inside the consumer repository", options.priorManifest));
+  else {
+    prior = readJsonFile({ prefix: "page_evidence_reuse_manifest", reference, root: options.root }, failures);
+    if (prior) {
+      prior.sha256 = metadata(prior.bytes, "application/json", reference).sha256;
+      prior.valid = addSchemaFindings(schemas.manifest, prior.value, reference, "page_evidence_reuse_manifest_invalid", failures);
+    }
+  }
+}
+
+const runnerReferences = options.artifactRoot ? options.runnerResults.map((candidate) => normalizeReference(options.artifactRoot, candidate)) : [];
+if (runnerReferences.some((reference) => !reference) || new Set(runnerReferences).size !== runnerReferences.length) failures.push(finding("page_evidence_runner_path_invalid", "runner results must be unique normalized paths inside artifact root", "<cli>"));
+const completedAt = new Date().toISOString();
+const scenarios = [];
+const controlFiles = new Set([PAGE_EVIDENCE_MANIFEST, PAGE_EVIDENCE_RECEIPT, ...runnerReferences.filter(Boolean)]);
+const expectedFiles = new Set([...controlFiles].filter((reference) => reference !== PAGE_EVIDENCE_MANIFEST));
+const artifactOwners = new Map();
+let canonicalRun;
+
+for (const reference of packetWithinLimits ? runnerReferences.filter(Boolean) : []) {
+  const runner = readJsonFile({ prefix: "page_evidence_runner", reference, root: options.artifactRoot }, failures);
+  if (!runner || !schemas) continue;
+  if (!addSchemaFindings(schemas.runner, runner.value, reference, "page_evidence_runner_schema_invalid", failures)) continue;
+  const value = runner.value;
+  if (value.status !== "passed") failures.push(finding("page_evidence_runner_failed", `${value.scenario_id ?? reference} runner did not pass`, reference));
+  if (receipt) {
+    if (value.session_id !== receipt.value.session_id || value.nonce !== receipt.value.nonce || value.receipt_sha256 !== receipt.digest) failures.push(finding("page_evidence_session_mismatch", `${value.scenario_id ?? reference} runner session differs from the receipt`, reference));
+    if (value.revision !== receipt.value.revision || value.run?.revision !== receipt.value.revision) failures.push(finding("page_evidence_revision_mismatch", `${value.scenario_id ?? reference} runner revision differs from the receipt`, reference));
+    if (value.repository !== receipt.value.repository || value.run?.repository !== receipt.value.repository) failures.push(finding("page_evidence_repository_mismatch", `${value.scenario_id ?? reference} runner repository differs from the receipt`, reference));
+    if (value.source_sha256 !== receipt.value.source.sha256) failures.push(finding("page_evidence_source_mismatch", `${value.scenario_id ?? reference} runner source differs from the receipt`, reference));
+    if (value.run?.id !== receipt.value.run_id || value.run?.attempt !== receipt.value.attempt) failures.push(finding("page_evidence_run_mismatch", `${value.scenario_id ?? reference} runner identity differs from the receipt`, reference));
+    if (!receipt.value.intended_scenario_ids.includes(value.scenario_id)) failures.push(finding("page_evidence_scenario_unintended", `${value.scenario_id ?? reference} was not declared at session start`, reference));
+    if (!withinSession(value.recorded_at, receipt.value.started_at, completedAt)) failures.push(finding("page_evidence_capture_outside_session", `${value.scenario_id ?? reference} was recorded outside the session interval`, reference));
+  }
+  const run = value.run ? { ...value.run, status: "passed" } : undefined;
+  if (canonicalRun && !sameJson(canonicalRun, run)) failures.push(finding("page_evidence_run_mismatch", "runner results mix run identities", reference));
+  else if (!canonicalRun) canonicalRun = run;
+  let evidence;
+  if (value.evidence?.kind === "captured") {
+    const artifacts = [];
+    for (const declaration of value.evidence.artifacts ?? []) {
+      if (controlFiles.has(declaration.path)) {
+        failures.push(finding("page_evidence_artifact_control_collision", "captured artifacts must be disjoint from manifest, receipt, and runner-result controls", declaration.path));
+        continue;
+      }
+      const owner = artifactOwners.get(declaration.path);
+      if (owner) failures.push(finding("page_evidence_artifact_reused", `${declaration.path} is shared by ${owner} and ${value.scenario_id}`, reference));
+      else artifactOwners.set(declaration.path, value.scenario_id);
+      const resolved = readContainedBytes({ prefix: "page_evidence_artifact", reference: declaration.path, root: options.artifactRoot }, failures);
+      if (!resolved) continue;
+      expectedFiles.add(declaration.path);
+      const artifact = metadata(resolved.bytes, declaration.media_type, declaration.path);
+      if (declaration.media_type === "image/png" && (!artifact.width || !artifact.height)) failures.push(finding("page_evidence_png_invalid", "captured PNG must contain a valid IHDR/IDAT/IEND chunk stream", declaration.path));
+      artifacts.push(artifact);
+    }
+    evidence = { artifacts, kind: "captured" };
+  } else if (value.evidence?.kind === "reused") {
+    evidence = value.evidence;
+    if (!prior?.valid) failures.push(finding("page_evidence_reuse_manifest_required", "reused evidence requires a valid --prior-manifest", reference));
+    else {
+      const priorScenario = prior.value.scenarios?.find((scenario) => scenario.id === value.evidence.prior_scenario_id);
+      if (value.evidence.prior_manifest_sha256 !== prior.sha256) failures.push(finding("page_evidence_reuse_manifest_mismatch", "prior manifest digest does not match", reference));
+      if (value.evidence.prior_session_id !== prior.value.session?.session_id || value.evidence.prior_run_id !== prior.value.run?.id) failures.push(finding("page_evidence_reuse_identity_mismatch", "prior session or run identity does not match", reference));
+      if (!priorScenario || value.evidence.prior_scenario_id !== value.scenario_id || priorScenario.evidence?.kind !== "captured") failures.push(finding("page_evidence_reuse_scenario_mismatch", "reuse must select the same captured scenario", reference));
+      if (receipt && !sameJson(prior.value.session?.source, receipt.value.source)) failures.push(finding("page_evidence_reuse_source_mismatch", "reuse requires byte-identical relevant sources", reference));
+      if (priorScenario && !sameJson(priorScenario.semantic_environment, value.semantic_environment)) failures.push(finding("page_evidence_reuse_environment_mismatch", "reuse requires the same semantic environment", reference));
+    }
+  }
+  scenarios.push({ evidence, id: value.scenario_id, recorded_at: value.recorded_at, runner_result: metadata(runner.bytes, "application/json", reference), semantic_environment: value.semantic_environment });
+}
+
+if (receipt) {
+  const passedIds = scenarios.map((scenario) => scenario.id);
+  if (!sameStringSet(passedIds, receipt.value.intended_scenario_ids)) failures.push(finding("page_evidence_pass_membership_invalid", "PASS scenarios must exactly match the start intent", PAGE_EVIDENCE_MANIFEST));
+}
+if (packetWithinLimits && options.artifactRoot && fs.existsSync(options.artifactRoot)) {
+  for (const reference of artifactFiles) if (!expectedFiles.has(reference)) failures.push(finding("page_evidence_artifact_unmanifested", "artifact root contains a file outside the closed manifest", reference));
+}
+
+const completedSession = receipt ? {
+  ...receipt.value,
+  completed_at: completedAt,
+  receipt: receipt.artifact,
+  receipt_sha256: receipt.digest,
+} : undefined;
+delete completedSession?.record_kind;
+delete completedSession?.schema_version;
+const manifest = receipt && canonicalRun ? {
+  claim_boundary: PAGE_EVIDENCE_CLAIM,
+  completed_at: completedAt,
+  record_kind: "page_evidence_manifest",
+  repository: receipt.value.repository,
+  review_by: options.reviewBy,
+  revision: receipt.value.revision,
+  run: canonicalRun,
+  scenarios,
+  schema_version: "1.0",
+  session: completedSession,
+} : undefined;
+if (manifest && schemas) addSchemaFindings(schemas.manifest, manifest, PAGE_EVIDENCE_MANIFEST, "page_evidence_manifest_schema_invalid", failures);
+if (failures.length === 0 && manifestFile) fs.writeFileSync(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" });
+const result = { artifactCount: artifactOwners.size, failures, manifest: manifestFile, ok: failures.length === 0, scenarioCount: scenarios.length, sessionId: receipt?.value.session_id };
+if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+else if (result.ok) process.stdout.write(`finalized ${result.scenarioCount} page evidence scenarios\n`);
+else process.stderr.write(`${failures.map((issue) => `${issue.code}: ${issue.path}: ${issue.message}`).join("\n")}\n`);
+if (!result.ok) process.exitCode = 1;

package/scripts/generate-consumer-reference-evidence.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveProfileRecords } from "./profile-record-contract.mjs";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const options = { check: false, json: false, root: path.join(repositoryRoot, "design-engineering/reference-profiles/governed-local") };
+const failures = [];
+for (let index = 2; index < process.argv.length; index += 1) {
+  const argument = process.argv[index];
+  if (argument === "--json") options.json = true;
+  else if (argument === "--check") options.check = true;
+  else if (argument === "--root") {
+    const value = process.argv[index + 1];
+    if (!value) failures.push({ code: "argument_value_required", message: "--root requires a directory", path: "<cli>" });
+    else { options.root = path.resolve(value); index += 1; }
+  } else failures.push({ code: "argument_unknown", message: `unsupported argument ${argument}`, path: "<cli>" });
+}
+
+function compare(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function isSorted(values) {
+  return values.every((value, index) => index === 0 || compare(values[index - 1], value) <= 0);
+}
+
+function duplicateValues(values) {
+  const seen = new Set();
+  return [...new Set(values.filter((value) => seen.has(value) || !seen.add(value)))];
+}
+
+function escapeMarkdown(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll("|", "&#124;")
+    .replaceAll("`", "&#96;")
+    .replace(/\r\n?|\n/g, "<br>");
+}
+
+function codeCell(value) {
+  return `<code>${escapeMarkdown(value)}</code>`;
+}
+
+function markdownTable(headers, rows) {
+  return [`| ${headers.map(escapeMarkdown).join(" | ")} |`, `| ${headers.map(() => "---").join(" | ")} |`, ...rows.map((row) => `| ${row.join(" | ")} |`)].join("\n");
+}
+
+function frontmatter(title, description) {
+  return `---\ntype: Generated Evidence\ntitle: ${JSON.stringify(String(title))}\ndescription: ${JSON.stringify(String(description))}\n---\n\n<!-- Generated from canonical JSON. Do not edit. -->`;
+}
+
+function navigation(parentLabel, parentPath, nextLabel, nextPath) {
+  return `## IA Navigation\n\nParent: [${parentLabel}](${parentPath}).\nNext: [${nextLabel}](${nextPath}).`;
+}
+
+function renderStateMatrix(profile, states) {
+  const rows = [...states.scenarios].sort((a, b) => compare(a.id, b.id)).map((scenario) => [
+    codeCell(scenario.id),
+    escapeMarkdown(scenario.semantic_mode),
+    [...scenario.states].sort(compare).map(codeCell).join(", "),
+    Object.entries(scenario.aria).sort(([left], [right]) => compare(left, right)).map(([name, value]) => codeCell(`aria-${name}=${value}`)).join("<br>") || "none",
+    scenario.expected.visual.map(codeCell).join(", "),
+    escapeMarkdown(scenario.expected.activation),
+  ]);
+  return `${frontmatter(`${profile} button state matrix`, "Compound state sets and channel expectations derived from canonical JSON.")}\n# ${escapeMarkdown(profile)} button state matrix\n\n${markdownTable(["Scenario", "Mode", "State set", "ARIA", "Visual", "Activation"], rows)}\n\n${navigation("Governed Local Profiles", "../../index.md", "Keyboard Matrix", "keyboard-matrix.md")}\n`;
+}
+
+function renderKeyboardMatrix(profile, component, fixture) {
+  const fixtureByMode = new Map(fixture.scenarios.map((scenario) => [scenario.semantic_mode, scenario.id]));
+  const rows = [...component.semantic_modes].sort((a, b) => compare(a.id, b.id)).map((mode) => [
+    codeCell(mode.id), escapeMarkdown(mode.element), escapeMarkdown(mode.role), [...mode.keys].sort(compare).map(codeCell).join(", "), codeCell(mode.activation), fixtureByMode.has(mode.id) ? codeCell(fixtureByMode.get(mode.id)) : "not exercised",
+  ]);
+  return `${frontmatter(`${profile} button keyboard matrix`, "Keyboard behavior and live fixture coverage derived from canonical JSON.")}\n# ${escapeMarkdown(profile)} button keyboard matrix\n\n${markdownTable(["Mode", "Element", "Role", "Keys", "Behavior", "Runtime scenario"], rows)}\n\n${navigation("State Matrix", "state-matrix.md", "Evidence Coverage", "evidence-coverage.md")}\n`;
+}
+
+function renderEvidenceCoverage(profile, fixture, evidence) {
+  const rows = [...fixture.scenarios].sort((a, b) => compare(a.id, b.id)).map((scenario) => {
+    const passes = evidence.passes.filter((pass) => pass.scenario_id === scenario.id).sort((a, b) => compare(a.channel, b.channel));
+    return [
+      codeCell(scenario.id),
+      scenario.required_channels.map(codeCell).join(", "),
+      passes.map((pass) => codeCell(pass.channel)).join(", "),
+      String(passes.length),
+      passes.map((pass) => codeCell(pass.artifact.path)).join("<br>"),
+    ];
+  });
+  return `${frontmatter(`${profile} button evidence coverage`, "Claim-scoped evidence channels and artifacts derived from canonical JSON.")}\n# ${escapeMarkdown(profile)} button evidence coverage\n\nClaim boundary: ${escapeMarkdown(evidence.claim_boundary)}\n\n${markdownTable(["Scenario", "Required channels", "Recorded channels", "Pass records", "Artifacts"], rows)}\n\n${navigation("Keyboard Matrix", "keyboard-matrix.md", "Reference Profiles", "../../../index.md")}\n`;
+}
+
+function generatedRowIds(content) {
+  return content.split("\n").map((line) => /^\| <code>([^<]+)<\/code> \|/.exec(line)?.[1]).filter(Boolean);
+}
+
+function classifyDrift(file, expectedIds, expected, actual) {
+  const ids = generatedRowIds(actual);
+  for (const id of duplicateValues(ids)) failures.push({ code: "generated_duplicate_row", message: `${id} is duplicated`, path: file });
+  if (!isSorted(ids)) failures.push({ code: "generated_unsorted", message: "generated rows must be sorted", path: file });
+  const missing = expectedIds.filter((id) => !ids.includes(id));
+  for (const id of missing) failures.push({ code: "generated_missing_row", message: `${id} is missing`, path: file });
+  if (ids.length !== expectedIds.length) failures.push({ code: "generated_source_count_mismatch", message: `expected ${expectedIds.length} rows, found ${ids.length}`, path: file });
+  if (actual !== expected) failures.push({ code: "generated_stale", message: "generated table differs from canonical JSON", path: file });
+}
+
+function writeOrCheck(file, expectedIds, content) {
+  if (options.check) {
+    if (!fs.existsSync(file)) failures.push({ code: "generated_missing", message: "generated table is missing", path: file });
+    else classifyDrift(file, expectedIds, content, fs.readFileSync(file, "utf8"));
+    return;
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+}
+
+const profiles = fs.existsSync(options.root)
+  ? fs.readdirSync(options.root, { withFileTypes: true }).filter((entry) => entry.isDirectory() && fs.existsSync(path.join(options.root, entry.name, "profile.json"))).map((entry) => entry.name).sort(compare)
+  : [];
+let generated = 0;
+for (const profile of profiles) {
+  const profileRoot = path.join(options.root, profile);
+  const resolved = resolveProfileRecords(profileRoot, failures);
+  if (!resolved) continue;
+  const component = resolved.records.component[0]?.value;
+  const fixture = resolved.records.fixture[0]?.value;
+  const states = resolved.records.states[0]?.value;
+  const evidence = resolved.records.evidence[0]?.value;
+  if (!component || !fixture || !states || !evidence) continue;
+  const scenarioIds = states.scenarios.map((scenario) => scenario.id);
+  for (const id of duplicateValues(scenarioIds)) failures.push({ code: "scenario_duplicate", message: `${id} is duplicated`, path: profileRoot });
+  if (!isSorted(scenarioIds)) failures.push({ code: "source_unsorted", message: "canonical scenario IDs must be sorted", path: profileRoot });
+  const fixtureIds = fixture.scenarios.map((scenario) => scenario.id);
+  for (const id of fixtureIds.filter((id) => !scenarioIds.includes(id))) failures.push({ code: "fixture_scenario_missing", message: `${id} has no canonical scenario`, path: profileRoot });
+  const outputs = new Map([
+    ["state-matrix.md", [[...scenarioIds].sort(compare), renderStateMatrix(profile, states)]],
+    ["keyboard-matrix.md", [component.semantic_modes.map((mode) => mode.id).sort(compare), renderKeyboardMatrix(profile, component, fixture)]],
+    ["evidence-coverage.md", [[...fixtureIds].sort(compare), renderEvidenceCoverage(profile, fixture, evidence)]],
+  ]);
+  for (const record of resolved.records.generated) {
+    const output = outputs.get(path.basename(record.path));
+    if (!output) { failures.push({ code: "generated_reference_unknown", message: `${record.reference} has no renderer`, path: resolved.profileFile }); continue; }
+    writeOrCheck(record.path, output[0], output[1]);
+    generated += 1;
+  }
+}
+const uniqueFailures = [...new Map(failures.map((failure) => [`${failure.code}:${failure.path}:${failure.message}`, failure])).values()];
+const result = { checkedProfiles: profiles.length, failures: uniqueFailures, generated, mode: options.check ? "check" : "write", ok: uniqueFailures.length === 0, warnings: [] };
+if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+else if (result.ok) process.stdout.write(`${options.check ? "checked" : "generated"} ${generated} consumer reference evidence tables\n`);
+else process.stderr.write(`${result.failures.map((failure) => `${failure.code}: ${failure.path}: ${failure.message}`).join("\n")}\n`);
+if (!result.ok) process.exitCode = 1;