stylegallery 0.1.0 → 0.1.1

package/scripts/validate-component-state.mjs

@@ -1,141 +0,0 @@
-#!/usr/bin/env node
-
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import {
-  canonicalSourceManifest,
-  canonicalIntended,
-  readCaptureSession,
-  sameJson,
-  sourceManifestMatches,
-  withinSession,
-} from "./capture-session-contract.mjs";
-import { compileSchemas, readRecord, validateEvidenceArtifacts, validateProfile } from "./component-state-contract.mjs";
-import { resolveProfileRecords } from "./profile-record-contract.mjs";
-import { visualExpectationFor } from "./visual-expectation-contract.mjs";
-
-const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const options = { artifactRoot: undefined, json: false, root: path.join(repositoryRoot, "design-engineering/reference-profiles/governed-local"), runtimeManifest: undefined };
-const failures = [];
-
-function validateCommittedVisualExpectations(resolved) {
-  const evidenceRecord = resolved.records.evidence[0];
-  const statesRecord = resolved.records.states[0];
-  if (!evidenceRecord || !statesRecord) return;
-  const scenarios = new Map((statesRecord.value.scenarios ?? []).map((scenario) => [scenario.id, scenario]));
-  for (const pass of (evidenceRecord.value.passes ?? []).filter((candidate) => candidate.channel === "visual")) {
-    const scenario = scenarios.get(pass.scenario_id);
-    if (!scenario) continue;
-    try {
-      const expected = visualExpectationFor(scenario, pass.environment, statesRecord.value.visual_environments ?? []);
-      const actual = pass.artifact ?? {};
-      if (actual.sha256 !== expected.sha256 || actual.width !== expected.width || actual.height !== expected.height) {
-        failures.push({ code: "evidence_visual_expectation_mismatch", message: `${pass.id} committed visual metadata differs from its canonical environment expectation`, path: evidenceRecord.path });
-      }
-    } catch (error) {
-      failures.push({ code: "evidence_visual_expectation_invalid", message: error instanceof Error ? error.message : String(error), path: evidenceRecord.path });
-    }
-  }
-}
-
-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", "--runtime-manifest", "--root"].includes(argument)) {
-    const value = process.argv[index + 1];
-    if (!value) failures.push({ code: "argument_value_required", message: `${argument} requires a path`, path: "<cli>" });
-    else {
-      if (argument === "--artifact-root") options.artifactRoot = path.resolve(value);
-      if (argument === "--runtime-manifest") options.runtimeManifest = path.resolve(value);
-      if (argument === "--root") options.root = path.resolve(value);
-      index += 1;
-    }
-  } else failures.push({ code: "argument_unknown", message: `unsupported argument ${argument}`, path: "<cli>" });
-}
-
-const schemas = compileSchemas(path.join(repositoryRoot, "consumer-reference/schema"));
-let runtimeManifest;
-let capture;
-let canonicalSource;
-if (!options.runtimeManifest) {
-  try { canonicalSource = canonicalSourceManifest(repositoryRoot, options.root); }
-  catch (error) { failures.push({ code: "capture_source_unreadable", message: error instanceof Error ? error.message : String(error), path: options.root }); }
-}
-if (options.runtimeManifest) {
-  runtimeManifest = readRecord(options.runtimeManifest, failures);
-  if (!options.artifactRoot) failures.push({ code: "runtime_manifest_artifact_root_required", message: "--runtime-manifest requires --artifact-root", path: "<cli>" });
-  if (runtimeManifest && !schemas.runtime(runtimeManifest)) for (const error of schemas.runtime.errors ?? []) failures.push({ code: "runtime_manifest_schema_invalid", message: `${error.instancePath || "/"} ${error.message}`, path: options.runtimeManifest });
-  if (options.artifactRoot) capture = readCaptureSession(path.join(options.artifactRoot, "capture-session.json"), schemas.capture, failures);
-  if (capture && runtimeManifest) {
-    const session = runtimeManifest.session;
-    if (!session || !sameJson(session.receipt, capture.artifact) || session.receipt_sha256 !== capture.digest) failures.push({ code: "capture_session_receipt_mismatch", message: "manifest receipt metadata does not match capture-session.json", path: options.runtimeManifest });
-    const expectedLink = capture.link;
-    for (const key of ["session_id", "nonce", "started_at", "revision", "branch", "attempt", "environment", "source"]) if (!sameJson(session?.[key], expectedLink[key])) failures.push({ code: "capture_session_mismatch", message: `manifest ${key} differs from receipt`, path: options.runtimeManifest });
-    for (const key of ["repository", "intended"]) if (!sameJson(session?.[key], capture.receipt[key])) failures.push({ code: "capture_session_mismatch", message: `manifest ${key} differs from receipt`, path: options.runtimeManifest });
-    if (runtimeManifest.recorded_at !== session?.completed_at) failures.push({ code: "evidence_recorded_at_mismatch", message: "manifest recorded_at must equal session completed_at", path: options.runtimeManifest });
-    if (!withinSession(session?.completed_at, capture.receipt.started_at, session?.completed_at)) failures.push({ code: "capture_session_time_outside", message: "completed_at precedes session start", path: options.runtimeManifest });
-    const canonical = canonicalIntended(options.root, failures);
-    if (!sameJson(capture.receipt.intended, canonical)) failures.push({ code: "capture_session_intent_mismatch", message: "receipt intent differs from current canonical records", path: options.runtimeManifest });
-    if (!capture.receipt.source) failures.push({ code: "capture_source_missing", message: "capture receipt must include its canonical source manifest", path: options.runtimeManifest });
-    else if (!sourceManifestMatches(capture.receipt.source, repositoryRoot, options.root)) failures.push({ code: "capture_source_drift", message: "current capture sources differ from the receipt source manifest", path: options.runtimeManifest });
-    const run = runtimeManifest.run;
-    if (run?.id !== capture.receipt.session_id || run?.repository !== capture.receipt.repository || run?.revision !== capture.receipt.revision || run?.attempt !== capture.receipt.attempt) failures.push({ code: "capture_session_mismatch", message: "manifest run differs from receipt", path: options.runtimeManifest });
-    for (const record of runtimeManifest.records ?? []) {
-      for (const pass of record.passes ?? []) {
-        if (!sameJson(pass.environment, runtimeManifest.environment) || !sameJson(pass.run, run)) failures.push({ code: "runtime_manifest_identity_mismatch", message: `${pass.id} does not match the closed manifest identity`, path: options.runtimeManifest });
-        if (!sameJson(pass.session, capture.link) || !sameJson(pass.environment, capture.receipt.environment) || !sameJson(pass.run, run)) failures.push({ code: "capture_session_mismatch", message: `${pass.id} pass identity differs from receipt`, path: options.runtimeManifest });
-      }
-    }
-  }
-} else if (options.artifactRoot) failures.push({ code: "runtime_manifest_required", message: "artifact validation requires --runtime-manifest", path: "<cli>" });
-
-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()
-  : [];
-if (profiles.length === 0) failures.push({ code: "profile_root_empty", message: "governed-local root must contain profiles", path: options.root });
-for (const profile of profiles) {
-  const profileRoot = path.join(options.root, profile);
-  failures.push(...validateProfile(profileRoot, schemas));
-  if (!runtimeManifest) {
-    const resolved = resolveProfileRecords(profileRoot, failures);
-    if (resolved) validateCommittedVisualExpectations(resolved);
-    const evidenceRecord = resolved?.records.evidence[0];
-    if (canonicalSource) {
-      for (const pass of evidenceRecord?.value.passes ?? []) {
-        if (!pass.session?.source) failures.push({ code: "capture_source_missing", message: `${pass.id} committed evidence must include its canonical source manifest`, path: evidenceRecord.path });
-        else if (!sameJson(pass.session.source, canonicalSource)) failures.push({ code: "capture_source_drift", message: `${pass.id} committed evidence source differs from current canonical capture sources`, path: evidenceRecord.path });
-      }
-    }
-  }
-  const profileId = JSON.parse(fs.readFileSync(path.join(profileRoot, "profile.json"), "utf8")).id;
-  const matching = runtimeManifest?.records?.filter((record) => record.profile_id === profileId) ?? [];
-  if (runtimeManifest && matching.length !== 1) failures.push({ code: "runtime_manifest_profile_count", message: `${profileId} requires exactly one runtime evidence record`, path: options.runtimeManifest });
-  if (options.artifactRoot && runtimeManifest) failures.push(...validateEvidenceArtifacts(profileRoot, options.artifactRoot, matching[0], schemas, runtimeManifest.session));
-}
-if (runtimeManifest) {
-  const known = new Set(profiles.map((profile) => JSON.parse(fs.readFileSync(path.join(options.root, profile, "profile.json"), "utf8")).id));
-  for (const record of runtimeManifest.records ?? []) if (!known.has(record.profile_id)) failures.push({ code: "runtime_manifest_profile_unknown", message: `${record.profile_id} is not a governed profile`, path: options.runtimeManifest });
-}
-if (runtimeManifest && options.artifactRoot) {
-  const passes = (runtimeManifest.records ?? []).flatMap((record) => record.passes ?? []);
-  const passArtifacts = new Set(passes.map((pass) => pass.artifact?.path).filter(Boolean));
-  if (passArtifacts.size !== 30) failures.push({ code: "runtime_channel_count_mismatch", message: `manifest requires exactly 30 unique channel artifacts, found ${passArtifacts.size}`, path: options.runtimeManifest });
-  const expected = new Set(passArtifacts);
-  for (const pass of passes) if (pass.channel === "visual" && pass.artifact?.path?.endsWith(".png")) expected.add(pass.artifact.path.replace(/\.png$/, ".visual.json"));
-  if (expected.size !== 40) failures.push({ code: "runtime_artifact_count_mismatch", message: `manifest requires exactly 40 runtime files, found ${expected.size}`, path: options.runtimeManifest });
-  const runtimeRoot = path.join(options.artifactRoot, "runtime");
-  const actual = fs.existsSync(runtimeRoot) ? fs.readdirSync(runtimeRoot, { withFileTypes: true }) : [];
-  for (const entry of actual) {
-    const reference = `runtime/${entry.name}`;
-    if (!entry.isFile() || !expected.has(reference)) failures.push({ code: "runtime_artifact_unmanifested", message: `${reference} is not a declared regular session artifact`, path: runtimeRoot });
-  }
-  for (const reference of expected) if (!fs.existsSync(path.join(options.artifactRoot, reference))) failures.push({ code: "runtime_artifact_missing", message: `${reference} is missing`, path: runtimeRoot });
-}
-
-const uniqueFailures = [...new Map(failures.map((failure) => [`${failure.code}:${failure.path}:${failure.message}`, failure])).values()];
-const result = { checkedProfiles: profiles.length, failures: uniqueFailures, ok: uniqueFailures.length === 0, warnings: [] };
-if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-else if (result.ok) process.stdout.write(`ok: ${profiles.length} governed-local component profiles\n`);
-else process.stderr.write(`${result.failures.map((failure) => `${failure.code}: ${failure.path}: ${failure.message}`).join("\n")}\n`);
-if (!result.ok) process.exitCode = 1;

package/scripts/validate-consumer-conformance.mjs

@@ -1,477 +0,0 @@
-#!/usr/bin/env node
-
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-import { isDeepStrictEqual } from "node:util";
-import { fileURLToPath } from "node:url";
-import Ajv2020 from "ajv/dist/2020.js";
-import {
-  MIGRATION_DIMENSIONS,
-  consumerConformanceSchemaFindings,
-  isNormalizedRepositoryPath,
-  validateConsumerConformanceSemantics,
-  validateConsumerPageEvidenceSemantics,
-  validateConsumerPageIntentSemantics,
-} from "./consumer-conformance-contract.mjs";
-import { parseStrictJson } from "./strict-json.mjs";
-import { addDateTimeFormat } from "./json-schema-formats.mjs";
-import {
-  addSchemaFindings,
-  compilePageEvidenceSchemas,
-  digest,
-  gitIdentity,
-  normalizeReference,
-  PAGE_EVIDENCE_MANIFEST,
-  readJsonFile,
-  resolveContained,
-} from "./page-evidence-contract.mjs";
-import { MAX_ARTIFACT_FILE_BYTES } from "./page-artifact-metadata.mjs";
-
-const styleGalleryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const schemaPath = path.join(styleGalleryRoot, "consumer-reference", "schema", "consumer-conformance-record.schema.json");
-const pageSchemaRoot = path.join(styleGalleryRoot, "consumer-reference", "schema");
-const pageValidator = path.join(styleGalleryRoot, "scripts", "validate-page-evidence.mjs");
-const runtimeTimeout = Math.min(120_000, Math.max(100, Number.parseInt(process.env.STYLEGALLERY_RUNTIME_TIMEOUT_MS ?? "120000", 10) || 120_000));
-
-function finding(code, message, recordPath) {
-  return { code, message, path: recordPath };
-}
-
-function parseArguments(argv) {
-  const options = { artifactRoot: undefined, json: false, priorManifest: undefined, record: undefined, root: process.cwd() };
-  const failures = [];
-  for (let index = 2; index < argv.length; index += 1) {
-    const argument = argv[index];
-    if (argument === "--json") options.json = true;
-    else if (["--artifact-root", "--prior-manifest", "--record", "--root"].includes(argument)) {
-      const value = 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 = value;
-        if (argument === "--prior-manifest") options.priorManifest = value;
-        if (argument === "--record") options.record = value;
-        if (argument === "--root") options.root = value;
-        index += 1;
-      }
-    } else failures.push(finding("argument_unknown", `unsupported argument ${argument}`, "<cli>"));
-  }
-  if (!options.record) failures.push(finding("argument_value_required", "--record requires a normalized JSON path", "<cli>"));
-  return { failures, options };
-}
-
-function containedRecord(rootArgument, recordArgument, failures) {
-  const root = path.resolve(process.cwd(), rootArgument);
-  if (!fs.existsSync(root) || !fs.lstatSync(root).isDirectory() || fs.realpathSync(root) !== root) {
-    failures.push(finding("consumer_conformance_root_invalid", "consumer root must be a real directory without filesystem redirects", rootArgument));
-    return undefined;
-  }
-  if (!isNormalizedRepositoryPath(recordArgument, { jsonOnly: true })) {
-    failures.push(finding("consumer_conformance_record_path_invalid", "--record must be a normalized repository-relative JSON path", recordArgument));
-    return undefined;
-  }
-  const resolved = path.resolve(root, recordArgument);
-  const relative = path.relative(root, resolved);
-  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative) || !fs.existsSync(resolved)) {
-    failures.push(finding("consumer_conformance_record_path_invalid", "consumer conformance record must exist inside the consumer root", recordArgument));
-    return undefined;
-  }
-  let current = root;
-  for (const segment of relative.split(path.sep).filter(Boolean)) {
-    current = path.join(current, segment);
-    if (fs.lstatSync(current).isSymbolicLink()) {
-      failures.push(finding("consumer_conformance_record_path_invalid", "consumer conformance record must not traverse a symlink", recordArgument));
-      return undefined;
-    }
-  }
-  if (!fs.lstatSync(resolved).isFile() || fs.realpathSync(resolved) !== resolved) {
-    failures.push(finding("consumer_conformance_record_path_invalid", "consumer conformance record must be a contained regular file", recordArgument));
-    return undefined;
-  }
-  return { recordPath: relative.split(path.sep).join("/"), resolved, root };
-}
-
-function readStrictJson(file, code, displayPath, failures) {
-  try {
-    if (fs.lstatSync(file).size > MAX_ARTIFACT_FILE_BYTES) throw new Error(`file exceeds ${MAX_ARTIFACT_FILE_BYTES} bytes`);
-    return parseStrictJson(fs.readFileSync(file, "utf8"));
-  } catch (error) {
-    failures.push(finding(code, error instanceof Error ? error.message : String(error), displayPath));
-    return undefined;
-  }
-}
-
-function uniqueFindings(findings) {
-  return [...new Map(findings.map((entry) => [`${entry.code}:${entry.path}:${entry.message}`, entry])).values()];
-}
-
-function runGit(root, args, encoding = "utf8") {
-  return spawnSync("git", ["-c", `safe.directory=${path.resolve(root)}`, ...args], { cwd: root, encoding });
-}
-
-function firstFilesystemRedirect(root) {
-  const pending = [root];
-  while (pending.length > 0) {
-    const directory = pending.pop();
-    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-      const target = path.join(directory, entry.name);
-      const stat = fs.lstatSync(target);
-      if (stat.isSymbolicLink()) return path.relative(root, target).split(path.sep).join("/");
-      if (stat.isDirectory()) pending.push(target);
-    }
-  }
-  return undefined;
-}
-
-function executePinnedScenario(root, revision, scenario, expectedResult, failures) {
-  if (!Array.isArray(scenario?.argv) || scenario.argv.length === 0 || scenario.argv.some((argument) => typeof argument !== "string" || argument.length === 0)) return false;
-  const [executable, ...args] = scenario.argv;
-  if (executable !== "node") {
-    failures.push(finding("runtime_command_executable_invalid", `scenario ${scenario.id ?? "<unknown>"} must use the governed Node runtime`, scenario.id ?? "<scenario>"));
-    return undefined;
-  }
-  const entrypoint = args[0];
-  if (!isNormalizedRepositoryPath(entrypoint ?? "") || entrypoint.startsWith("-") || !/\.(?:c?js|mjs)$/.test(entrypoint)) {
-    failures.push(finding("runtime_command_argv_unsafe", `scenario ${scenario.id ?? "<unknown>"} may not override the governed Node permission boundary`, scenario.id ?? "<scenario>"));
-    return undefined;
-  }
-  const temporaryRoot = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "stylegallery-consumer-command-")));
-  const checkout = path.join(temporaryRoot, "checkout");
-  let worktreeAdded = false;
-  try {
-    const add = runGit(root, ["worktree", "add", "--detach", checkout, revision]);
-    if (add.status !== 0) {
-      failures.push(finding("runtime_command_checkout_failed", `scenario ${scenario.id ?? "<unknown>"} could not check out the pinned revision`, scenario.id ?? "<scenario>"));
-      return false;
-    }
-    worktreeAdded = true;
-    const redirect = firstFilesystemRedirect(checkout);
-    if (redirect) {
-      failures.push(finding("runtime_command_checkout_symlink", `scenario ${scenario.id ?? "<unknown>"} checkout contains filesystem redirect ${redirect}`, redirect));
-      return undefined;
-    }
-    const resultFile = path.resolve(checkout, scenario.result_artifact);
-    fs.rmSync(resultFile, { force: true });
-    const child = spawnSync(process.execPath, ["--permission", `--allow-fs-read=${checkout}`, `--allow-fs-write=${checkout}`, ...args], {
-      cwd: checkout,
-      env: {
-        CI: "1",
-        LANG: "C",
-        LC_ALL: "C",
-        PATH: process.env.PATH ?? "",
-        STYLEGALLERY_RESULT_ARTIFACT: scenario.result_artifact,
-        STYLEGALLERY_RUNTIME_CONTEXT: JSON.stringify(expectedResult),
-      },
-      killSignal: "SIGKILL",
-      shell: false,
-      stdio: "ignore",
-      timeout: runtimeTimeout,
-    });
-    if (child.error || child.status !== 0) {
-      const outcome = child.error?.code === "ETIMEDOUT" ? "timed out" : child.signal ? `received ${child.signal}` : `exited ${child.status ?? "without a status"}`;
-      failures.push(finding("runtime_command_failed", `scenario ${scenario.id ?? "<unknown>"} ${outcome} at the pinned revision`, scenario.id ?? "<scenario>"));
-      return undefined;
-    }
-    try {
-      const stat = fs.lstatSync(resultFile);
-      if (stat.size > MAX_ARTIFACT_FILE_BYTES) throw new Error(`result exceeds ${MAX_ARTIFACT_FILE_BYTES} bytes`);
-      if (!stat.isFile() || stat.isSymbolicLink() || !fs.realpathSync(resultFile).startsWith(`${fs.realpathSync(checkout)}${path.sep}`)) throw new Error("result is not a contained regular file");
-      return parseStrictJson(fs.readFileSync(resultFile, "utf8"));
-    } catch (error) {
-      failures.push(finding("runtime_command_result_missing", `scenario ${scenario.id ?? "<unknown>"} did not produce a valid result artifact: ${error instanceof Error ? error.message : String(error)}`, scenario.result_artifact));
-      return undefined;
-    }
-  } finally {
-    if (worktreeAdded) {
-      const removed = runGit(root, ["worktree", "remove", "--force", "--force", checkout]);
-      if (removed.status !== 0) {
-        try { fs.rmSync(checkout, { force: true, recursive: true }); } catch {}
-        runGit(root, ["worktree", "prune", "--expire", "now"]);
-        const registered = runGit(root, ["worktree", "list", "--porcelain"]);
-        if (registered.status !== 0 || registered.stdout.includes(checkout)) failures.push(finding("runtime_command_cleanup_failed", `scenario ${scenario.id ?? "<unknown>"} worktree cleanup failed`, scenario.id ?? "<scenario>"));
-      }
-    }
-    fs.rmSync(temporaryRoot, { force: true, recursive: true });
-  }
-}
-
-function remoteIdentity(remote) {
-  const cleaned = remote.trim().replace(/\.git$/, "");
-  const scp = cleaned.match(/^[^@]+@[^:]+:(.+)$/);
-  if (scp) return scp[1];
-  try { return new URL(cleaned).pathname.replace(/^\//, ""); }
-  catch { return undefined; }
-}
-
-function pinnedSourceManifest(root, revision, references, failures) {
-  if (!Array.isArray(references) || references.length === 0 || new Set(references).size !== references.length) return undefined;
-  const revisionCheck = runGit(root, ["cat-file", "-e", `${revision}^{commit}`]);
-  if (revisionCheck.status !== 0) {
-    failures.push(finding("consumer_revision_unknown", "consumer revision must resolve to a commit in the repository", revision));
-    return undefined;
-  }
-  const files = [];
-  for (const reference of [...references].sort()) {
-    if (!isNormalizedRepositoryPath(reference)) continue;
-    const tree = runGit(root, ["ls-tree", "-z", revision, "--", reference], "buffer");
-    const entry = tree.status === 0 ? tree.stdout.toString("utf8").split("\0").find((line) => line.endsWith(`\t${reference}`)) : undefined;
-    if (!entry) {
-      failures.push(finding("consumer_source_missing", "relevant source is missing from the pinned revision", reference));
-      continue;
-    }
-    const [metadata] = entry.split("\t", 1);
-    const [mode, type] = metadata.split(" ");
-    if (mode === "120000") {
-      failures.push(finding("consumer_source_symlink", "relevant source must not be a symbolic link", reference));
-      continue;
-    }
-    if (type !== "blob") {
-      failures.push(finding("consumer_source_type_invalid", "relevant source must be a regular file", reference));
-      continue;
-    }
-    const blob = runGit(root, ["show", `${revision}:${reference}`], "buffer");
-    if (blob.status !== 0) {
-      failures.push(finding("consumer_source_unreadable", "relevant source could not be read from the pinned revision", reference));
-      continue;
-    }
-    files.push({ byte_length: blob.stdout.length, path: reference, sha256: digest(blob.stdout) });
-  }
-  return files.length === references.length ? { files, sha256: digest(Buffer.from(JSON.stringify(files))) } : undefined;
-}
-
-function markdownAnchors(bytes) {
-  const occurrences = new Map();
-  return bytes.toString("utf8").split("\n").flatMap((line) => {
-    const heading = line.match(/^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$/)?.[1];
-    if (!heading) return [];
-    const base = heading
-      .replace(/`([^`]*)`/g, "$1")
-      .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
-      .toLowerCase()
-      .replace(/[^a-z0-9 _-]/g, "")
-      .trim()
-      .replace(/\s+/g, "-");
-    const occurrence = occurrences.get(base) ?? 0;
-    occurrences.set(base, occurrence + 1);
-    return [occurrence === 0 ? `#${base}` : `#${base}-${occurrence}`];
-  });
-}
-
-function validateStyleGallerySources(value, recordPath, failures) {
-  const mappings = Array.isArray(value?.adoption_mappings) ? value.adoption_mappings : [];
-  let checked = 0;
-  for (const [index, mapping] of mappings.entries()) {
-    const source = mapping?.stylegallery;
-    if (!source || !/^[a-f0-9]{40}$/.test(source.revision ?? "") || !isNormalizedRepositoryPath(source.path)) continue;
-    const revision = runGit(styleGalleryRoot, ["cat-file", "-e", `${source.revision}^{commit}`]);
-    if (revision.status !== 0) {
-      failures.push(finding("adoption_stylegallery_revision_unknown", `adoption mapping ${index} revision does not resolve in StyleGallery`, recordPath));
-      continue;
-    }
-    const tree = runGit(styleGalleryRoot, ["ls-tree", "-z", source.revision, "--", source.path], "buffer");
-    const entry = tree.status === 0 ? tree.stdout.toString("utf8").split("\0").find((line) => line.endsWith(`\t${source.path}`)) : undefined;
-    if (!entry) {
-      failures.push(finding("adoption_stylegallery_path_missing", `adoption mapping ${index} path is missing from its pinned StyleGallery revision`, source.path));
-      continue;
-    }
-    const [metadata] = entry.split("\t", 1);
-    const [mode, type] = metadata.split(" ");
-    if (mode === "120000" || type !== "blob") {
-      failures.push(finding("adoption_stylegallery_path_invalid", `adoption mapping ${index} path must be a regular StyleGallery file`, source.path));
-      continue;
-    }
-    const blob = runGit(styleGalleryRoot, ["show", `${source.revision}:${source.path}`], "buffer");
-    if (blob.status !== 0) {
-      failures.push(finding("adoption_stylegallery_path_unreadable", `adoption mapping ${index} path could not be read from StyleGallery`, source.path));
-      continue;
-    }
-    if (!markdownAnchors(blob.stdout).includes(source.anchor)) {
-      failures.push(finding("adoption_stylegallery_anchor_missing", `adoption mapping ${index} anchor is missing from its pinned StyleGallery file`, `${source.path}${source.anchor}`));
-      continue;
-    }
-    checked += 1;
-  }
-  return checked;
-}
-
-function validateRuntimeEvidence({ recordPath, root, validateResult, value }, failures) {
-  const consumer = value?.consumer;
-  const scenarios = Array.isArray(value?.scenarios) ? value.scenarios : [];
-  if (!consumer || typeof consumer.repository !== "string" || typeof consumer.revision !== "string" || !Array.isArray(consumer.relevant_sources)) return 0;
-
-  const gitFailures = [];
-  const identity = gitIdentity(root, gitFailures);
-  for (const issue of gitFailures) failures.push(finding("consumer_git_invalid", issue.message, issue.path));
-  if (identity) {
-    const remote = runGit(root, ["config", "--get", "remote.origin.url"]);
-    const repositories = new Set([identity.repository, remote.status === 0 ? remoteIdentity(remote.stdout) : undefined].filter(Boolean));
-    if (repositories.size === 0) failures.push(finding("consumer_repository_unverifiable", "consumer repository requires a verifiable Git remote identity", recordPath));
-    else if (!repositories.has(consumer.repository)) failures.push(finding("consumer_repository_mismatch", "consumer repository differs from the Git repository identity", recordPath));
-  }
-
-  const source = pinnedSourceManifest(root, consumer.revision, consumer.relevant_sources, failures);
-  if (source) {
-    for (const scenario of scenarios) {
-      if (scenario?.source_digest !== source.sha256) failures.push(finding("runtime_source_digest_mismatch", `scenario ${scenario?.id ?? "<unknown>"} source digest differs from the pinned relevant sources`, recordPath));
-    }
-  }
-
-  let checked = 0;
-  let executed = 0;
-  for (const scenario of scenarios) {
-    if (!isNormalizedRepositoryPath(scenario?.result_artifact, { jsonOnly: true })) continue;
-    const result = readJsonFile({ prefix: "runtime_result_artifact", reference: scenario.result_artifact, root }, failures);
-    if (!result) continue;
-    checked += 1;
-    if (scenario.evidence_method === "browser" && value.page_evidence?.status === "applicable") continue;
-    if (!validateResult(result.value)) {
-      for (const error of validateResult.errors ?? []) failures.push(finding("runtime_result_artifact_schema_invalid", `${error.instancePath || "/"} ${error.message}`, scenario.result_artifact));
-      continue;
-    }
-    const expected = {
-      argv: scenario.argv,
-      evidence_method: scenario.evidence_method,
-      exit_code: scenario.exit_code,
-      repository: consumer.repository,
-      revision: consumer.revision,
-      run_id: scenario.run_id,
-      scenario_id: scenario.id,
-      session_id: scenario.session_id,
-      source_digest: scenario.source_digest,
-    };
-    if (Object.entries(expected).some(([key, expectedValue]) => Array.isArray(expectedValue)
-      ? !Array.isArray(result.value[key]) || expectedValue.length !== result.value[key].length || expectedValue.some((entry, index) => result.value[key][index] !== entry)
-      : result.value[key] !== expectedValue)) {
-      failures.push(finding("runtime_result_artifact_mismatch", `scenario ${scenario.id ?? "<unknown>"} result artifact identity differs from the conformance record`, scenario.result_artifact));
-    }
-    const executedResult = identity && source ? executePinnedScenario(root, consumer.revision, scenario, expected, failures) : undefined;
-    if (executedResult !== undefined) {
-      executed += 1;
-      if (!validateResult(executedResult)) {
-        for (const error of validateResult.errors ?? []) failures.push(finding("runtime_command_result_invalid", `${error.instancePath || "/"} ${error.message}`, scenario.result_artifact));
-      } else if (!isDeepStrictEqual(executedResult, result.value)) {
-        failures.push(finding("runtime_result_artifact_execution_mismatch", `scenario ${scenario.id ?? "<unknown>"} stored result differs from the result produced at the pinned revision`, scenario.result_artifact));
-      }
-    }
-  }
-  return { checked, executed };
-}
-
-function runPageValidator({ artifactRoot, manifest, priorManifest, root }, failures) {
-  const args = [pageValidator, "--root", root, "--artifact-root", artifactRoot, "--manifest", manifest];
-  if (priorManifest) args.push("--prior-manifest", priorManifest);
-  args.push("--json");
-  const child = spawnSync(process.execPath, args, { cwd: styleGalleryRoot, encoding: "utf8" });
-  let report;
-  try {
-    report = parseStrictJson(child.stdout);
-  } catch (error) {
-    failures.push(finding("page_evidence_validator_output_invalid", error instanceof Error ? error.message : String(error), manifest));
-    return undefined;
-  }
-  if (Array.isArray(report?.failures)) failures.push(...report.failures);
-  if (child.status !== 0 && report?.failures?.length === 0) failures.push(finding("page_evidence_validator_failed", "page evidence validator exited without a finding", manifest));
-  return report;
-}
-
-function validatePageEvidence({ artifactRootArgument, priorManifestArgument, recordPath, root, value }, failures) {
-  if (value?.page_evidence?.status !== "applicable") return undefined;
-  const intentFindings = validateConsumerPageIntentSemantics(value, recordPath);
-  failures.push(...intentFindings);
-  if (intentFindings.some((entry) => entry.code === "page_evidence_runtime_scenario_required")) return undefined;
-  if (!artifactRootArgument) {
-    failures.push(finding("page_evidence_artifact_root_required", "applicable page evidence requires --artifact-root", value.page_evidence.manifest ?? "<page-evidence>"));
-    return undefined;
-  }
-  const artifactReference = normalizeReference(root, artifactRootArgument);
-  if (!artifactReference) {
-    failures.push(finding("page_evidence_artifact_escape", "artifact root must be a normalized path inside the consumer root", artifactRootArgument));
-    return undefined;
-  }
-  const artifact = resolveContained({ expectedType: "directory", prefix: "page_evidence_artifact", reference: artifactReference, root }, failures);
-  const expectedManifest = `${artifactReference}/${PAGE_EVIDENCE_MANIFEST}`;
-  if (value.page_evidence.manifest !== expectedManifest) {
-    failures.push(finding("page_evidence_manifest_path_mismatch", `page evidence manifest must equal ${expectedManifest}`, value.page_evidence.manifest));
-    return undefined;
-  }
-  const manifest = readJsonFile({ prefix: "page_evidence_manifest", reference: expectedManifest, root }, failures);
-  if (!artifact || !manifest) return undefined;
-  let schemas;
-  try {
-    schemas = compilePageEvidenceSchemas(pageSchemaRoot);
-  } catch (error) {
-    failures.push(finding("page_evidence_schema_invalid", error instanceof Error ? error.message : String(error), "consumer-reference/schema"));
-    return undefined;
-  }
-  if (!addSchemaFindings(schemas.manifest, manifest.value, manifest.reference, "page_evidence_manifest_schema_invalid", failures)) return undefined;
-  failures.push(...validateConsumerPageEvidenceSemantics(value, manifest.value, recordPath));
-
-  let priorManifest;
-  if (priorManifestArgument) {
-    const reference = normalizeReference(root, priorManifestArgument);
-    const prior = reference ? resolveContained({ expectedType: "file", prefix: "page_evidence_reuse_manifest", reference, root }, failures) : undefined;
-    if (!reference) failures.push(finding("page_evidence_reuse_manifest_escape", "prior manifest must be a normalized path inside the consumer root", priorManifestArgument));
-    priorManifest = prior?.file;
-  }
-  if (priorManifestArgument && !priorManifest) return undefined;
-  return runPageValidator({ artifactRoot: artifact.file, manifest: manifest.file, priorManifest, root }, failures);
-}
-
-const { failures: argumentFailures, options } = parseArguments(process.argv);
-const failures = [...argumentFailures];
-const record = options.record ? containedRecord(options.root, options.record, failures) : undefined;
-const schema = readStrictJson(schemaPath, "consumer_conformance_schema_invalid", "consumer-reference/schema/consumer-conformance-record.schema.json", failures);
-const value = record ? readStrictJson(record.resolved, "consumer_conformance_json_invalid", record.recordPath, failures) : undefined;
-let checkedRuntimeArtifacts = 0;
-let checkedRuntimeCommands = 0;
-let checkedStyleGallerySources = 0;
-let recordSchemaValid = false;
-
-if (schema && value !== undefined) {
-  try {
-    const ajv = new Ajv2020({ allErrors: true, strict: true });
-    addDateTimeFormat(ajv);
-    ajv.addSchema(schema);
-    const validate = ajv.getSchema(schema.$id);
-    const validateResult = ajv.compile({ $ref: `${schema.$id}#/$defs/runtimeResult` });
-    const schemaValid = validate(value);
-    recordSchemaValid = schemaValid;
-    if (!schemaValid) failures.push(...consumerConformanceSchemaFindings(validate.errors, record.recordPath));
-    else {
-      failures.push(...validateConsumerConformanceSemantics(value, record.recordPath));
-      checkedStyleGallerySources = validateStyleGallerySources(value, record.recordPath, failures);
-      const runtimeEvidence = validateRuntimeEvidence({ recordPath: record.recordPath, root: record.root, validateResult, value }, failures);
-      checkedRuntimeArtifacts = runtimeEvidence.checked;
-      checkedRuntimeCommands = runtimeEvidence.executed;
-    }
-  } catch (error) {
-    failures.push(finding("consumer_conformance_schema_invalid", error instanceof Error ? error.message : String(error), "consumer-reference/schema/consumer-conformance-record.schema.json"));
-  }
-}
-
-const pageReport = record && value !== undefined && recordSchemaValid
-  ? validatePageEvidence({ artifactRootArgument: options.artifactRoot, priorManifestArgument: options.priorManifest, recordPath: record.recordPath, root: record.root, value }, failures)
-  : undefined;
-
-const uniqueFailures = uniqueFindings(failures);
-const result = {
-  checkedDimensions: value && typeof value.migration_dimensions === "object" && value.migration_dimensions !== null
-    ? MIGRATION_DIMENSIONS.filter((name) => Object.hasOwn(value.migration_dimensions, name)).length
-    : 0,
-  checkedMappings: Array.isArray(value?.adoption_mappings) ? value.adoption_mappings.length : 0,
-  checkedRuntimeArtifacts,
-  checkedRuntimeCommands,
-  checkedScenarios: Array.isArray(value?.scenarios) ? value.scenarios.length : 0,
-  checkedStyleGallerySources,
-  checkedPageArtifacts: pageReport?.artifactCount ?? 0,
-  checkedPageScenarios: pageReport?.scenarioCount ?? 0,
-  failures: uniqueFailures,
-  ok: uniqueFailures.length === 0,
-  pageSessionId: pageReport?.sessionId ?? null,
-  record: record?.recordPath ?? options.record ?? null,
-};
-if (options.json) console.log(JSON.stringify(result, null, 2));
-else if (result.ok) console.log(`ok: ${result.checkedDimensions} migration dimensions, ${result.checkedMappings} adoption mappings`);
-else console.error(result.failures.map((entry) => `${entry.code}: ${entry.path}: ${entry.message}`).join("\n"));
-process.exitCode = result.ok ? 0 : 1;