@terpjs/eslint-boundaries 0.1.0

package/src/index.test.js

@@ -0,0 +1,318 @@
+import path from "node:path";
+
+import { ESLint } from "eslint";
+import { describe, expect, it } from "vitest";
+
+import terpBoundaries from "./index.js";
+
+// The frontend analog of the arch harness's meta-tests: prove each boundary rule actually fires on
+// a violating fixture (and stays quiet on clean, out-of-module code), so "enforced" is real.
+// File paths are resolved under the cwd so ESLint's `files` globs match (the parser then applies).
+
+const MODULE_FILE = path.resolve("src/modules/widgets/Widget.tsx");
+const OUTSIDE_FILE = path.resolve("src/main.tsx");
+
+async function lint(code, filePath = MODULE_FILE) {
+  const eslint = new ESLint({ overrideConfigFile: true, overrideConfig: terpBoundaries });
+  const [result] = await eslint.lintText(code, { filePath });
+  return result.messages.map((message) => message.ruleId);
+}
+
+describe("terpBoundaries", () => {
+  it("passes clean module code (react-core components + generated client)", async () => {
+    const code = [
+      'import { Button, Select, Textarea, useTerpClient } from "@terpjs/react-core";',
+      "export function Widget() {",
+      "  const client = useTerpClient();",
+      "  void client;",
+      "  return <><Button>ok</Button><Select /><Textarea /></>;",
+      "}",
+    ].join("\n");
+    expect(await lint(code)).toEqual([]);
+  });
+
+  it("flags an import of a sibling module", async () => {
+    const code = 'import { x } from "../other/thing";\nexport const W = () => null;';
+    expect(await lint(code)).toContain("terp/no-cross-module-imports");
+  });
+
+  it("flags a dynamic import() of a sibling module (no spelling escape)", async () => {
+    const code = 'export const load = () => import("../other/thing");';
+    expect(await lint(code)).toContain("terp/no-cross-module-imports");
+  });
+
+  it("flags a raw <button> (use the token-styled component)", async () => {
+    expect(await lint("export const W = () => <button>x</button>;")).toContain("no-restricted-syntax");
+  });
+
+  it("flags raw form controls that have react-core primitives", async () => {
+    expect(await lint("export const W = () => <select />;")).toContain("no-restricted-syntax");
+    expect(await lint("export const W = () => <textarea />;")).toContain("no-restricted-syntax");
+  });
+
+  it("flags raw layout-bearing elements that have react-core components", async () => {
+    expect(await lint("export const W = () => <table />;")).toContain("no-restricted-syntax");
+    expect(await lint("export const W = () => <dialog />;")).toContain("no-restricted-syntax");
+    expect(await lint("export const W = () => <form />;")).toContain("no-restricted-syntax");
+  });
+
+  it("flags an in-app anchor (router Link, not a full-reload <a>)", async () => {
+    expect(await lint('export const W = () => <a href="/notes">go</a>;')).toContain(
+      "no-restricted-syntax",
+    );
+    expect(await lint('export const W = () => <a href={"/notes"}>go</a>;')).toContain(
+      "no-restricted-syntax",
+    );
+    expect(await lint("export const W = () => <a href={`/notes`}>go</a>;")).toContain(
+      "no-restricted-syntax",
+    );
+  });
+
+  it("allows an external anchor", async () => {
+    expect(await lint('export const W = () => <a href="https://example.com">docs</a>;')).toEqual([]);
+  });
+
+  it("flags className (no side channel into hand-authored CSS)", async () => {
+    expect(await lint('export const W = () => <div className="x">y</div>;')).toContain(
+      "no-restricted-syntax",
+    );
+  });
+
+  it("flags a module-authored stylesheet import (theming flows from the tokens)", async () => {
+    const code = 'import "./widget.css";\nexport const W = () => null;';
+    expect(await lint(code)).toContain("no-restricted-imports");
+    expect(await lint('import "./widget.css?inline";\nexport const W = () => null;')).toContain(
+      "no-restricted-imports",
+    );
+    expect(await lint('import "./widget.less";\nexport const W = () => null;')).toContain(
+      "no-restricted-imports",
+    );
+  });
+
+  it("flags a hardcoded colour (design tokens only)", async () => {
+    expect(await lint('export const s = { color: "#ff0000" };')).toContain("no-restricted-syntax");
+  });
+
+  it("flags an inline style attribute (layout via react-core, styling via tokens)", async () => {
+    expect(await lint("export const W = () => <div style={{ margin: 0 }}>x</div>;")).toContain(
+      "no-restricted-syntax",
+    );
+  });
+
+  it("flags raw fetch (generated client only)", async () => {
+    expect(await lint('export const load = () => fetch("/api/x");')).toContain("no-restricted-globals");
+    expect(await lint('export const load = () => window.fetch("/api/x");')).toContain(
+      "no-restricted-syntax",
+    );
+    expect(await lint('export const load = () => globalThis.fetch("/api/x");')).toContain(
+      "no-restricted-syntax",
+    );
+    expect(await lint('export const load = () => window["fetch"]("/api/x");')).toContain(
+      "no-restricted-syntax",
+    );
+    expect(await lint("export const load = () => new XMLHttpRequest();")).toContain(
+      "no-restricted-syntax",
+    );
+    expect(await lint('export const load = () => new globalThis["XMLHttpRequest"]();')).toContain(
+      "no-restricted-syntax",
+    );
+  });
+
+  it("flags raw browser streaming/beacon request primitives (generated client only)", async () => {
+    expect(await lint('export const open = () => new WebSocket("wss://example.com");')).toContain(
+      "no-restricted-globals",
+    );
+    expect(await lint('export const open = () => new window.EventSource("/events");')).toContain(
+      "no-restricted-syntax",
+    );
+    expect(await lint('export const send = () => navigator.sendBeacon("/api/x", "x");')).toContain(
+      "no-restricted-syntax",
+    );
+    expect(
+      await lint('export const send = () => window.navigator.sendBeacon("/api/x", "x");'),
+    ).toContain("no-restricted-syntax");
+    expect(
+      await lint('export const send = () => globalThis["navigator"]["sendBeacon"]("/api/x", "x");'),
+    ).toContain("no-restricted-syntax");
+  });
+
+  it("flags target=_blank without rel=noopener", async () => {
+    expect(
+      await lint('export const W = () => <a href="https://example.com" target="_blank">docs</a>;'),
+    ).toContain("terp/no-unsafe-target-blank");
+    expect(
+      await lint(
+        'export const W = () => <a href="https://example.com" target={"_blank"} rel="noreferrer">docs</a>;',
+      ),
+    ).toContain("terp/no-unsafe-target-blank");
+    expect(
+      await lint(
+        'export const W = () => <a href="https://example.com" target={`_blank`} rel="noopener noreferrer">docs</a>;',
+      ),
+    ).toEqual([]);
+  });
+
+  it("flags static javascript href/src values without rejecting dynamic URLs", async () => {
+    expect(await lint('export const W = () => <a href=" javascript:alert(1)">bad</a>;')).toContain(
+      "terp/no-unsafe-href",
+    );
+    expect(await lint('export const W = () => <img src={"JaVaScRiPt:alert(1)"} />;')).toContain(
+      "terp/no-unsafe-href",
+    );
+    expect(await lint('export const W = () => <a href={`javascript:${danger}`}>bad</a>;')).toContain(
+      "terp/no-unsafe-href",
+    );
+    expect(await lint('export const W = ({ href }) => <a href={href}>ok</a>;')).toEqual([]);
+  });
+
+  it("flags DOM HTML injection sinks", async () => {
+    expect(await lint('export const write = (el, html) => { el.innerHTML = html; };')).toContain(
+      "terp/no-dom-html-injection",
+    );
+    expect(
+      await lint('export const write = (el, html) => el.insertAdjacentHTML("beforeend", html);'),
+    ).toContain("terp/no-dom-html-injection");
+    expect(await lint('export const write = (html) => document.write(html);')).toContain(
+      "terp/no-dom-html-injection",
+    );
+    expect(await lint('export const W = ({ html }) => <iframe srcDoc={html} />;')).toContain(
+      "terp/no-dom-html-injection",
+    );
+  });
+
+  it("flags eval and Function constructors", async () => {
+    expect(await lint('export const run = (code) => eval(code);')).toContain("terp/no-eval");
+    expect(await lint('export const run = (code) => new Function(code);')).toContain("terp/no-eval");
+    expect(await lint('export const run = (code) => window.eval(code);')).toContain("terp/no-eval");
+  });
+
+  it("flags a deep import into a package's internals", async () => {
+    const code = 'import x from "@terp/react-core/src/secret";\nexport const W = () => null;';
+    expect(await lint(code)).toContain("no-restricted-imports");
+  });
+
+  it("does not apply the module rules outside src/modules/", async () => {
+    // A non-module file matches no config block, so the boundary rules never fire on it.
+    const rules = await lint("export const W = () => <button>x</button>;", OUTSIDE_FILE);
+    expect(rules).not.toContain("no-restricted-syntax");
+    expect(rules).not.toContain("terp/no-cross-module-imports");
+  });
+
+  it("suppresses a violation with a justified terp-allow marker on the line above", async () => {
+    const code = [
+      "// terp-allow-token-styled-elements: native button needed for a browser extension host",
+      "export const W = () => <button>x</button>;",
+    ].join("\n");
+    expect(await lint(code)).toEqual([]);
+  });
+
+  it("suppresses a violation with a justified terp-allow marker on the same line", async () => {
+    const code =
+      "export const W = () => <textarea />; // terp-allow-token-styled-elements: measured host quirk";
+    expect(await lint(code)).toEqual([]);
+  });
+
+  it("suppresses a custom terp rule with the reported rule id suffix", async () => {
+    const code = [
+      "// terp-allow-no-unsafe-target-blank: external vendor requires opener for a handshake",
+      'export const W = () => <a href="https://example.com" target="_blank">docs</a>;',
+    ].join("\n");
+    expect(await lint(code)).toEqual([]);
+  });
+
+  it("refuses the retired pre-0.6.0 core-id spelling", async () => {
+    // The one-release transitional aliases (LEGACY_MARKER_ALIASES) are gone with the
+    // 0.6.0 pin: a core-id spelling names no catalog rule, so it waives nothing and
+    // is itself reported as an ungoverned marker.
+    const code = [
+      "// terp-allow-no-restricted-syntax: pre-0.6.0 spelling (migrate to the catalog rule)",
+      "export const W = () => <button>x</button>;",
+    ].join("\n");
+    const rules = await lint(code);
+    expect(rules).toContain("no-restricted-syntax"); // not suppressed
+    expect(rules).toContain("terp/escape-hatch"); // the stale spelling is itself reported
+  });
+
+  it("reports a marker that names no governed rule instead of honouring it", async () => {
+    const code = [
+      "// terp-allow-made-up-rule: stale name",
+      "export const W = () => <button>x</button>;",
+    ].join("\n");
+    const rules = await lint(code);
+    expect(rules).toContain("no-restricted-syntax"); // not suppressed
+    expect(rules).toContain("terp/escape-hatch"); // the unknown name is itself reported
+  });
+
+  it("ignores marker-shaped text inside a string or template literal", async () => {
+    // Markers live in real comments only — a marker-shaped string neither
+    // suppresses the next line nor its own line.
+    const viaString = [
+      'const doc = "// terp-allow-no-eval: not a comment";',
+      "export const run = (code) => eval(code); export { doc };",
+    ].join("\n");
+    expect(await lint(viaString)).toContain("terp/no-eval");
+    const viaTemplate = [
+      "const doc = `// terp-allow-no-eval: not a comment`;",
+      "export const run = (code) => eval(code); export { doc };",
+    ].join("\n");
+    expect(await lint(viaTemplate)).toContain("terp/no-eval");
+  });
+
+  it("one catalog marker covers every detection path of its rule (egress family)", async () => {
+    // Bare fetch reports via no-restricted-globals; window.fetch via no-restricted-syntax.
+    // Both are frontend/generated-client-only, so ONE marker name waives either path.
+    const viaGlobals = [
+      "// terp-allow-generated-client-only: sanctioned health probe",
+      'export const ping = () => fetch("/healthz");',
+    ].join("\n");
+    expect(await lint(viaGlobals)).toEqual([]);
+    const viaSyntax = [
+      "// terp-allow-generated-client-only: sanctioned health probe",
+      'export const ping = () => window.fetch("/healthz");',
+    ].join("\n");
+    expect(await lint(viaSyntax)).toEqual([]);
+  });
+
+  it("reports an unjustified terp-allow marker instead of honouring it", async () => {
+    const code = [
+      "// terp-allow-token-styled-elements",
+      "export const W = () => <button>x</button>;",
+    ].join("\n");
+    const rules = await lint(code);
+    expect(rules).toContain("no-restricted-syntax"); // not suppressed
+    expect(rules).toContain("terp/escape-hatch"); // the bare marker is itself reported
+  });
+
+  it("does not let a marker for one rule suppress another rule", async () => {
+    const code = [
+      "// terp-allow-no-cross-module-imports: wrong rule name",
+      "export const W = () => <button>x</button>;",
+    ].join("\n");
+    expect(await lint(code)).toContain("no-restricted-syntax");
+  });
+
+  it("does not let a sibling catalog rule's marker cross a shared core rule id", async () => {
+    // token-styled-elements and no-inline-styling both report as no-restricted-syntax;
+    // a marker for one must never waive the other.
+    const code = [
+      "// terp-allow-token-styled-elements: wrong sibling",
+      'export const W = () => <div style={{ color: "red" }}>x</div>;',
+    ].join("\n");
+    expect(await lint(code)).toContain("no-restricted-syntax");
+  });
+
+  it("ignores inline eslint-disable directives (the budgeted marker is the only opt-out)", async () => {
+    // Without noInlineConfig, a plain `eslint-disable` would skip the gate with zero budget
+    // accounting — the exact drift ADR 0059 refuses. The directive must be inert.
+    const code = [
+      "// eslint-disable-next-line no-restricted-syntax",
+      "export const W = () => <button>x</button>;",
+    ].join("\n");
+    expect(await lint(code)).toContain("no-restricted-syntax");
+  });
+
+  it("ignores a file-wide eslint-disable block comment", async () => {
+    const code = ["/* eslint-disable */", "export const W = () => <button>x</button>;"].join("\n");
+    expect(await lint(code)).toContain("no-restricted-syntax");
+  });
+});

package/src/layouts.js

@@ -0,0 +1,85 @@
+/**
+ * Slot-typed layout contracts, declared **as data** (ADR 0079) — the layout analog of
+ * ./spec.js. A contract names, per governed page archetype ("slot owner"), the react-core
+ * components its body slot accepts; everything else is refused by BOTH halves of the
+ * two-layer control:
+ *
+ *   - build time — the `terp/layout-contract` ESLint rule (./index.js) checks the static
+ *     JSX children of each slot owner against the contract, and
+ *   - runtime    — react-core's archetypes verify the rendered DOM children (each
+ *     sanctioned component stamps a `data-terp` marker) and refuse the view, fail closed.
+ *
+ * Both halves phrase the SAME agent-directive message (see {@link slotViolationMessage}),
+ * so a failing check *tells the author how to build the screen*, wherever it fires.
+ *
+ * Contracts are opt-in and backwards compatible: no checked-in `layout-contract.json`
+ * (and no `layoutContract` option at runtime) means today's behavior. The react-core
+ * runtime carries a TypeScript mirror of this table (src/layoutContract.ts); a parity
+ * test in react-core keeps the two byte-equal, so the data cannot drift.
+ */
+
+/** The checked-in config file that activates a contract for an app (lint side). */
+export const LAYOUT_CONTRACT_FILE = "layout-contract.json";
+
+/**
+ * Every layout contract, keyed by id. Per slot owner (a page archetype), `components`
+ * maps each allowed react-core component name to the `data-terp` marker it stamps on
+ * its root element — the lint checks the names, the runtime checks the markers.
+ */
+export const LAYOUT_CONTRACTS = {
+  standard: {
+    description:
+      "The standard three-level shape: hub bodies are card grids (HubCard only), " +
+      "overview bodies are data collections (DataView / ResourceList + framework " +
+      "states), detail bodies are record sections (DetailList / Stack / Tabs + " +
+      "framework states). A bespoke screen composes the plain Page, which the " +
+      "contract deliberately leaves unconstrained.",
+    slots: {
+      HubPage: {
+        components: { HubCard: "hubcard" },
+      },
+      OverviewPage: {
+        components: {
+          DataView: "dataview",
+          ResourceList: "resource-list",
+          ModuleNav: "module-nav",
+          Stack: "stack",
+          EmptyState: "empty-state",
+          ErrorState: "error-state",
+          LoadingState: "loading-state",
+          Alert: "alert",
+          ConfirmDialog: "dialog",
+        },
+      },
+      DetailPage: {
+        components: {
+          DetailList: "detail-list",
+          Stack: "stack",
+          Tabs: "tabs",
+          ModuleNav: "module-nav",
+          DataView: "dataview",
+          EmptyState: "empty-state",
+          ErrorState: "error-state",
+          LoadingState: "loading-state",
+          Alert: "alert",
+          ConfirmDialog: "dialog",
+        },
+      },
+    },
+  },
+};
+
+/**
+ * The one agent-directive violation message both enforcement halves phrase: the
+ * contract, the slot, what was found, what is allowed, and the concrete fix.
+ */
+export function slotViolationMessage(contractId, slotOwner, found) {
+  const allowed = Object.keys(LAYOUT_CONTRACTS[contractId].slots[slotOwner].components);
+  return (
+    `Layout contract "${contractId}": the ${slotOwner} body slot accepts only ` +
+    `${allowed.join(" / ")}; found ${found}. Compose the body from those react-core ` +
+    "components (recipe: terp guide layouts), move bespoke content to a plain Page, " +
+    "or opt out on this line with a justified // terp-allow-layout-contract: <reason> " +
+    "marker (counted by the escape-hatch budget)."
+  );
+}

package/src/layouts.test.js

@@ -0,0 +1,106 @@
+import path from "node:path";
+
+import { ESLint } from "eslint";
+import { describe, expect, it } from "vitest";
+
+import terpBoundaries from "./index.js";
+import { LAYOUT_CONTRACTS, slotViolationMessage } from "./layouts.js";
+
+// The build-time half of the slot-typed layout contract control (ADR 0079): prove the
+// `terp/layout-contract` rule fires on a non-conforming slot child, stays quiet on
+// conforming screens, and stays fully inert when the app has not opted into a contract.
+// The rule option stands in for the checked-in layout-contract.json here (the file
+// lookup is exercised by consumers; tests must not depend on the repo's cwd).
+
+const MODULE_FILE = path.resolve("src/modules/widgets/Widget.tsx");
+
+function configWithContract(contract) {
+  return terpBoundaries.map((entry) =>
+    entry.rules?.["terp/layout-contract"]
+      ? {
+          ...entry,
+          rules: { ...entry.rules, "terp/layout-contract": ["error", { contract }] },
+        }
+      : entry,
+  );
+}
+
+async function lint(code, config = terpBoundaries) {
+  const eslint = new ESLint({ overrideConfigFile: true, overrideConfig: config });
+  const [result] = await eslint.lintText(code, { filePath: MODULE_FILE });
+  return result.messages;
+}
+
+describe("terp/layout-contract", () => {
+  it("is inert without an opted-in contract (backwards compatible)", async () => {
+    const code =
+      'import { HubPage } from "@terpjs/react-core";\n' +
+      "export const W = () => <HubPage title='x'><div /></HubPage>;";
+    expect((await lint(code)).map((m) => m.ruleId)).toEqual([]);
+  });
+
+  it("refuses a non-conforming child in a HubPage body, with the directive message", async () => {
+    const code =
+      'import { HubPage, Stack } from "@terpjs/react-core";\n' +
+      "export const W = () => <HubPage title='x'><Stack /></HubPage>;";
+    const messages = await lint(code, configWithContract("standard"));
+    expect(messages.map((m) => m.ruleId)).toContain("terp/layout-contract");
+    expect(messages[0].message).toBe(slotViolationMessage("standard", "HubPage", "<Stack>"));
+  });
+
+  it("passes a conforming hub / overview / detail composition", async () => {
+    const code = [
+      'import { DataView, DetailList, HubCard, HubPage, OverviewPage, DetailPage, Stack } from "@terpjs/react-core";',
+      "export const H = () => <HubPage title='x'><HubCard to='/a' title='a' /></HubPage>;",
+      "export const O = () => <OverviewPage title='x'><DataView /></OverviewPage>;",
+      "export const D = () => <DetailPage title='x' parents={[]}><Stack><DetailList items={[]} /></Stack></DetailPage>;",
+    ].join("\n");
+    expect((await lint(code, configWithContract("standard"))).map((m) => m.ruleId)).toEqual([]);
+  });
+
+  it("refuses raw text and recurses through fragments; dynamic children are left to the runtime half", async () => {
+    const text =
+      'import { OverviewPage } from "@terpjs/react-core";\n' +
+      "export const W = () => <OverviewPage title='x'>loose text</OverviewPage>;";
+    expect((await lint(text, configWithContract("standard"))).map((m) => m.ruleId)).toContain(
+      "terp/layout-contract",
+    );
+    const fragment =
+      'import { HubPage } from "@terpjs/react-core";\n' +
+      "export const W = () => <HubPage title='x'><><span /></></HubPage>;";
+    expect((await lint(fragment, configWithContract("standard"))).map((m) => m.ruleId)).toContain(
+      "terp/layout-contract",
+    );
+    const dynamic =
+      'import { HubPage } from "@terpjs/react-core";\n' +
+      "export const W = ({items}) => <HubPage title='x'>{items}</HubPage>;";
+    expect((await lint(dynamic, configWithContract("standard"))).map((m) => m.ruleId)).toEqual([]);
+  });
+
+  it("reports an unknown contract id, fail closed", async () => {
+    const messages = await lint("export const W = () => null;", configWithContract("ghost"));
+    expect(messages.map((m) => m.ruleId)).toContain("terp/layout-contract");
+    expect(messages[0].message).toContain('Unknown layout contract "ghost"');
+  });
+
+  it("honours a justified escape-hatch marker (and only a justified one)", async () => {
+    const code =
+      'import { HubPage } from "@terpjs/react-core";\n' +
+      "export const W = () => <HubPage title='x'>\n" +
+      "  {/* terp-allow-layout-contract: legacy widget pending HubCard port */}\n" +
+      "  <div />\n" +
+      "</HubPage>;";
+    expect((await lint(code, configWithContract("standard"))).map((m) => m.ruleId)).toEqual([]);
+  });
+
+  it("declares a marker-named runtime marker for every allowed component (data sanity)", () => {
+    for (const contract of Object.values(LAYOUT_CONTRACTS)) {
+      for (const slot of Object.values(contract.slots)) {
+        for (const [name, marker] of Object.entries(slot.components)) {
+          expect(name).toMatch(/^[A-Z]/);
+          expect(marker).toMatch(/^[a-z][a-z-]*$/);
+        }
+      }
+    }
+  });
+});

package/src/scorecard.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * Emit the Terp Standard conformance scorecard for `@terp/eslint-boundaries`
+ * (the frontend checker).
+ *
+ * The scorecard (`scorecard.schema.json` in the spec) turns "certified against
+ * spec X.Y.Z" into a verifiable artifact: one entry per frontend catalog rule
+ * with its pass/fail verdict over the violation corpus, plus the detector
+ * residuals the adapter relies on (held to a subset of the spec's recorded
+ * `corpus/RESIDUALS.json`). A consumer re-runs the corpus and reproduces it.
+ *
+ * A certification-context tool, not an app tool: it needs `@terp/spec` (a dev
+ * dependency of the platform repo) and runs the SAME harness the corpus test
+ * uses (./corpus-harness.js), so the scorecard can never disagree with the
+ * suite. Self-validates and refuses to write an invalid or failing scorecard
+ * (exit 1).
+ *
+ *   node packages/frontend/eslint-boundaries/src/scorecard.js --out scorecard.json
+ */
+
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+
+import { lintCaseFindings } from "./corpus-harness.js";
+
+const require = createRequire(import.meta.url);
+
+const RULE_ID_RE = /^(backend\/[a-z0-9_]+|frontend\/[a-z0-9-]+)$/;
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+
+/** The @terp/spec root — resolved lazily so importing this module never requires it. */
+function specRoot() {
+  return path.dirname(require.resolve("@terp/spec/package.json"));
+}
+
+/** Build the @terp/eslint-boundaries scorecard over the frontend corpus. */
+export async function buildScorecard() {
+  const root = specRoot();
+  const catalogDir = path.join(root, "catalog", "frontend");
+  const corpusDir = path.join(root, "corpus", "frontend");
+  const residuals = JSON.parse(
+    fs.readFileSync(path.join(root, "corpus", "RESIDUALS.json"), "utf8"),
+  ).residuals;
+  const packageVersion = JSON.parse(
+    fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+  ).version;
+
+  const rules = [];
+  const entries = fs
+    .readdirSync(catalogDir)
+    .filter((name) => name.endsWith(".json"))
+    .map((name) => JSON.parse(fs.readFileSync(path.join(catalogDir, name), "utf8")))
+    .filter((entry) => entry.corpus);
+  for (const entry of entries) {
+    const ruleDir = path.join(corpusDir, entry.id.split("/")[1]);
+    let pass = true;
+    for (const caseName of fs.readdirSync(ruleDir).sort()) {
+      const caseDir = path.join(ruleDir, caseName);
+      if (!fs.statSync(caseDir).isDirectory()) continue;
+      const fired = (await lintCaseFindings(caseDir)).map((finding) => finding.rule);
+      if (caseName.startsWith("violation-") && !fired.includes(entry.id)) pass = false;
+      if (caseName.startsWith("compliant-") && fired.length > 0) pass = false;
+    }
+    const claim = { rule: entry.id, pass };
+    if (residuals[entry.id]?.length) claim.residuals_claimed = [...residuals[entry.id]];
+    rules.push(claim);
+  }
+  return {
+    spec_version: fs.readFileSync(path.join(root, "VERSION"), "utf8").trim(),
+    checker: { tool: "@terp/eslint-boundaries", version: packageVersion },
+    rules,
+  };
+}
+
+/** Hold the scorecard to its published contract; returns the problems. */
+export function validateScorecard(scorecard) {
+  const problems = [];
+  if (!SEMVER_RE.test(String(scorecard.spec_version ?? ""))) {
+    problems.push("spec_version is not a semver string");
+  }
+  if (!scorecard.checker?.tool || !scorecard.checker?.version) {
+    problems.push("checker must carry tool and version");
+  }
+  const root = specRoot();
+  const residuals = JSON.parse(
+    fs.readFileSync(path.join(root, "corpus", "RESIDUALS.json"), "utf8"),
+  ).residuals;
+  const catalogued = fs
+    .readdirSync(path.join(root, "catalog", "frontend"))
+    .filter((name) => name.endsWith(".json"))
+    .map((name) =>
+      JSON.parse(fs.readFileSync(path.join(root, "catalog", "frontend", name), "utf8")),
+    )
+    .filter((entry) => entry.corpus)
+    .map((entry) => entry.id);
+  const rules = scorecard.rules ?? [];
+  if (rules.length === 0) problems.push("a scorecard without rule claims certifies nothing");
+  const claimed = new Set();
+  for (const claim of rules) {
+    claimed.add(claim.rule);
+    if (!RULE_ID_RE.test(String(claim.rule ?? ""))) {
+      problems.push(`bad rule id: ${claim.rule}`);
+    }
+    if (typeof claim.pass !== "boolean") {
+      problems.push(`${claim.rule}: pass must be a boolean`);
+    } else if (!claim.pass) {
+      problems.push(`${claim.rule}: the reference adapter must pass its own corpus`);
+    }
+    for (const residual of claim.residuals_claimed ?? []) {
+      if (!(residuals[claim.rule] ?? []).includes(residual)) {
+        problems.push(`${claim.rule}: claims an unrecorded residual: ${residual}`);
+      }
+    }
+  }
+  const missing = catalogued.filter((id) => !claimed.has(id));
+  if (missing.length > 0) {
+    problems.push(`corpus-covered rules missing a claim: ${missing.join(", ")}`);
+  }
+  return problems;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const outIndex = args.indexOf("--out");
+  const out = outIndex !== -1 ? args[outIndex + 1] : "";
+  const scorecard = await buildScorecard();
+  const problems = validateScorecard(scorecard);
+  if (problems.length > 0) {
+    for (const problem of problems) process.stderr.write(`scorecard: ${problem}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const rendered = `${JSON.stringify(scorecard, null, 2)}\n`;
+  if (out) {
+    fs.writeFileSync(out, rendered);
+    process.stderr.write(
+      `wrote ${out} (${scorecard.rules.length} rule claims, spec ${scorecard.spec_version})\n`,
+    );
+  } else {
+    process.stdout.write(rendered);
+  }
+}
+
+// Run main() only when invoked as a CLI, not on import (the findings.js pattern).
+const entry = process.argv[1] ? pathToFileURL(fs.realpathSync(process.argv[1])).href : "";
+if (entry === import.meta.url) {
+  main().catch((error) => {
+    console.error(String(error));
+    process.exitCode = 2;
+  });
+}