@terpjs/eslint-boundaries 0.1.0

package/src/scorecard.test.js

@@ -0,0 +1,61 @@
+/**
+ * The scorecard emitter is held to the published certification contract
+ * (spec/scorecard.schema.json): the adapter's scorecard validates, claims the
+ * whole corpus-covered frontend catalog, passes it, and only relies on the
+ * residuals the spec records. The emitter reuses the corpus test's own harness
+ * (./corpus-harness.js), so a scorecard can never disagree with the suite.
+ */
+
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { buildScorecard, validateScorecard } from "./scorecard.js";
+
+const SPEC_ROOT = path.dirname(
+  createRequire(import.meta.url).resolve("@terp/spec/package.json"),
+);
+
+describe("the @terp/eslint-boundaries scorecard", () => {
+  it("claims the whole corpus-covered catalog, green, schema-shaped", async () => {
+    const scorecard = await buildScorecard();
+    expect(validateScorecard(scorecard)).toEqual([]);
+
+    // Schema shape, field by field (the spec suite's minimal-validator discipline).
+    const schema = JSON.parse(
+      fs.readFileSync(path.join(SPEC_ROOT, "scorecard.schema.json"), "utf8"),
+    );
+    for (const field of schema.required) expect(scorecard).toHaveProperty(field);
+    for (const field of Object.keys(scorecard)) {
+      expect(Object.keys(schema.properties)).toContain(field);
+    }
+    expect(scorecard.spec_version).toBe(
+      fs.readFileSync(path.join(SPEC_ROOT, "VERSION"), "utf8").trim(),
+    );
+    expect(scorecard.checker.tool).toBe("@terp/eslint-boundaries");
+    const itemProperties = Object.keys(schema.properties.rules.items.properties);
+    for (const claim of scorecard.rules) {
+      expect(claim.pass).toBe(true);
+      for (const field of Object.keys(claim)) expect(itemProperties).toContain(field);
+    }
+  }, 120_000);
+
+  it("rejects a scorecard claiming an unrecorded residual or a failing rule", async () => {
+    const scorecard = await buildScorecard();
+    const failing = {
+      ...scorecard,
+      rules: [{ ...scorecard.rules[0], pass: false }, ...scorecard.rules.slice(1)],
+    };
+    expect(validateScorecard(failing).join("\n")).toMatch(/must pass its own corpus/);
+    const overclaiming = {
+      ...scorecard,
+      rules: [
+        { ...scorecard.rules[0], residuals_claimed: ["a residual the spec never recorded"] },
+        ...scorecard.rules.slice(1),
+      ],
+    };
+    expect(validateScorecard(overclaiming).join("\n")).toMatch(/unrecorded residual/);
+  }, 120_000);
+});

package/src/spec.js

@@ -0,0 +1,84 @@
+/**
+ * The Terp frontend boundary rules, declared **as data** (design §7.1.5). The ESLint adapter in
+ * ./index.js realises them for the React stack; a future stack (e.g. Svelte) can realise the same
+ * spec with its own adapter. The *rules* are shared; only the *enforcement adapter* is per-stack.
+ *
+ * They apply to the **app-authored surface** (`src/modules/**`) — the code agents and users write —
+ * not the framework packages, which legitimately define the very primitives the rules point back to.
+ */
+/**
+ * The Terp Standard version this adapter is certified against — the `spec_version` a
+ * check report (`app-check-report.schema.json`) carries. A constant rather than a runtime
+ * `@terp/spec` read: the spec data package is a dev/certification dependency of the platform
+ * repo, not of a generated app, and the version is a property of the toolchain build. Held
+ * equal to the pinned spec release by the framework gate (test_check_json.py — deliberately
+ * NOT by this package's own suite, which certification runs against candidate spec releases
+ * whose version is allowed to be newer).
+ */
+export const SPEC_VERSION = "0.12.0";
+
+export const BOUNDARY_SPEC = {
+  /** App module files the boundary + frontend security defaults apply to. */
+  moduleFiles: ["**/modules/**/*.{ts,tsx}"],
+  /**
+   * Raw HTML elements an app module must not author directly, mapped to the token-styled
+   * `@terpjs/react-core` replacement (accessible + theme-consistent by construction).
+   */
+  restrictedElements: {
+    button: "Button",
+    input: "Input",
+    select: "Select",
+    textarea: "Textarea",
+    table: "DataView",
+    dialog: "ConfirmDialog",
+    form: 'Stack as="form"',
+  },
+  /**
+   * JSX attributes an app module must not author — styling lives in the design tokens and the
+   * react-core components (`Stack` for layout), never ad-hoc per screen. `className` would be
+   * a side channel into hand-authored CSS, so it is refused alongside `style`.
+   */
+  restrictedAttributes: ["style", "className"],
+  /**
+   * Raw in-app anchors (`<a href="/...">`) bypass the router (full reload, no role-aware
+   * guard); modules use the stack's `Link`. External `https://...` anchors stay allowed.
+   */
+  restrictInAppAnchors: true,
+  /** Package internals an app module must not deep-import (import from the package root). */
+  internalImportPatterns: ["@terp/*/src/*", "@terp/*/dist/*"],
+  /** Module-authored stylesheets are refused — theming flows from the app's token source. */
+  styleImportPatterns: [
+    "*.css",
+    "**/*.css",
+    "*.css?*",
+    "**/*.css?*",
+    "*.scss",
+    "**/*.scss",
+    "*.scss?*",
+    "**/*.scss?*",
+    "*.sass",
+    "**/*.sass",
+    "*.sass?*",
+    "**/*.sass?*",
+    "*.less",
+    "**/*.less",
+    "*.less?*",
+    "**/*.less?*",
+    "*.styl",
+    "**/*.styl",
+    "*.styl?*",
+    "**/*.styl?*",
+  ],
+  /** Browser request/stream globals that would skip the audited, typed client. */
+  restrictedGlobals: ["fetch", "XMLHttpRequest", "WebSocket", "EventSource"],
+  /**
+   * The governed escape hatch (the frontend analog of the backend's `# arch-allow-*`): a
+   * justified `// terp-allow-<rule>: <reason>` comment on (or immediately above) a violating
+   * line suppresses that rule there. `<rule>` is the Terp Standard CATALOG rule name (the
+   * `opt_out` spelling in `spec/catalog/frontend/<rule>.json`), never a tool-internal ESLint
+   * id — one marker covers every detection path of its rule and can never waive a sibling
+   * rule sharing a core lint id. An unjustified marker is itself reported. Marker counts
+   * must exactly match the app's checked-in `escape-hatch-budget.json` (the ratchet).
+   */
+  allowMarkerPrefix: "terp-allow-",
+};

package/src/surface.test.js

@@ -0,0 +1,192 @@
+/**
+ * The reference adapter is held to the spec's declared refused surface (`spec/restricted-surface.json`).
+ *
+ * The refused raw frontend surface is spec **data**, not adapter code: the stack-neutral,
+ * normative part of the portable prohibition rules is the list of raw primitives an app module
+ * must not author; which sanctioned component answers each primitive is per-stack configuration
+ * (the catalog entries' non-normative `reference` field). This test locks the two together:
+ *
+ * - structurally: `BOUNDARY_SPEC` realises exactly the declared surface (no drift in either
+ *   direction — an element/attribute/global added to one side must be added to the other);
+ * - behaviourally: authoring each declared primitive in an app module produces a finding
+ *   attributed to the expected catalog id (through the published {@link catalogRuleId} mapping,
+ *   exactly as the corpus contract states).
+ */
+
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import { ESLint } from "eslint";
+import { describe, expect, it } from "vitest";
+
+import terpBoundaries, { BOUNDARY_SPEC, catalogRuleId } from "./index.js";
+
+// The spec is a declared dependency (@terp/spec, ADR 0082), never a repo-relative path.
+const SPEC_ROOT = path.dirname(
+  createRequire(import.meta.url).resolve("@terp/spec/package.json"),
+);
+const SURFACE = JSON.parse(
+  fs.readFileSync(path.join(SPEC_ROOT, "restricted-surface.json"), "utf8"),
+);
+
+async function lintModuleSource(source) {
+  const eslint = new ESLint({ overrideConfigFile: true, overrideConfig: terpBoundaries });
+  const filePath = path.resolve("src/modules/widgets/Widget.tsx");
+  const [result] = await eslint.lintText(source, { filePath });
+  return result.messages.map((message) => catalogRuleId(message));
+}
+
+describe("structural parity: BOUNDARY_SPEC realises exactly the declared surface", () => {
+  it("restricted elements match", () => {
+    expect(Object.keys(BOUNDARY_SPEC.restrictedElements).sort()).toEqual(
+      [...SURFACE.restrictedElements].sort(),
+    );
+  });
+
+  it("restricted attributes match", () => {
+    expect([...BOUNDARY_SPEC.restrictedAttributes].sort()).toEqual(
+      [...SURFACE.restrictedAttributes].sort(),
+    );
+  });
+
+  it("restricted globals match", () => {
+    expect([...BOUNDARY_SPEC.restrictedGlobals].sort()).toEqual(
+      [...SURFACE.restrictedGlobals].sort(),
+    );
+  });
+
+  it("every declared stylesheet extension is refused by the import patterns", () => {
+    for (const extension of SURFACE.styleImportExtensions) {
+      expect(BOUNDARY_SPEC.styleImportPatterns).toContain(`**/*${extension}`);
+    }
+    // ...and no pattern refuses an undeclared extension.
+    const declared = new Set(SURFACE.styleImportExtensions);
+    for (const pattern of BOUNDARY_SPEC.styleImportPatterns) {
+      const extension = pattern.replace(/\?\*$/, "").match(/\.[a-z]+$/)?.[0];
+      expect(declared.has(extension), `undeclared extension in pattern ${pattern}`).toBe(true);
+    }
+  });
+
+  it("every declared deep-import segment is refused by the import patterns", () => {
+    for (const segment of SURFACE.deepImportPathSegments) {
+      expect(BOUNDARY_SPEC.internalImportPatterns).toContain(`@terp/*/${segment}/*`);
+    }
+    expect(BOUNDARY_SPEC.internalImportPatterns).toHaveLength(
+      SURFACE.deepImportPathSegments.length,
+    );
+  });
+});
+
+describe("behavioural parity: each declared primitive is refused with the right catalog id", () => {
+  for (const element of SURFACE.restrictedElements) {
+    it(`raw <${element}> -> frontend/token-styled-elements`, async () => {
+      expect(await lintModuleSource(`export const W = () => <${element} />;\n`)).toContain(
+        "frontend/token-styled-elements",
+      );
+    });
+  }
+
+  for (const attribute of SURFACE.restrictedAttributes) {
+    it(`${attribute} attribute -> frontend/no-inline-styling`, async () => {
+      const value = attribute === "style" ? "{{}}" : '"x"';
+      expect(await lintModuleSource(`export const W = () => <div ${attribute}=${value} />;\n`)).toContain(
+        "frontend/no-inline-styling",
+      );
+    });
+  }
+
+  for (const globalName of SURFACE.restrictedGlobals) {
+    it(`${globalName} -> frontend/generated-client-only`, async () => {
+      expect(await lintModuleSource(`export const value = ${globalName};\n`)).toContain(
+        "frontend/generated-client-only",
+      );
+    });
+  }
+
+  for (const memberCall of SURFACE.restrictedMemberCalls) {
+    it(`${memberCall}() -> frontend/generated-client-only`, async () => {
+      expect(await lintModuleSource(`export const send = () => ${memberCall}("/x", "");\n`)).toContain(
+        "frontend/generated-client-only",
+      );
+    });
+  }
+
+  for (const extension of SURFACE.styleImportExtensions) {
+    it(`import of *${extension} -> frontend/no-style-imports`, async () => {
+      expect(await lintModuleSource(`import "./widget${extension}";\n`)).toContain(
+        "frontend/no-style-imports",
+      );
+    });
+  }
+
+  for (const segment of SURFACE.deepImportPathSegments) {
+    it(`deep import via /${segment}/ -> frontend/no-deep-imports`, async () => {
+      expect(
+        await lintModuleSource(`import { x } from "@terp/react-core/${segment}/internal";\n`),
+      ).toContain("frontend/no-deep-imports");
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// opt-out parity: the catalog's declared marker spelling is the one that works.
+// A violating line per rule; the spec's own `opt_out` (a justified marker naming
+// the CATALOG rule) must suppress exactly that rule — and the escape-hatch
+// governance rule declares no opt_out at all (waiving governance is refused).
+// The pinned spec (>= 0.6.0) states this contract.
+// ---------------------------------------------------------------------------
+const CATALOG_DIR = path.join(SPEC_ROOT, "catalog", "frontend");
+const CATALOG_ENTRIES = fs
+  .readdirSync(CATALOG_DIR)
+  .filter((name) => name.endsWith(".json"))
+  .map((name) => JSON.parse(fs.readFileSync(path.join(CATALOG_DIR, name), "utf8")));
+
+/** A minimal violating line per frontend catalog rule (the marker goes on the line above). */
+const VIOLATION_SNIPPETS = {
+  "frontend/token-styled-elements": "export const W = () => <button>x</button>;",
+  "frontend/no-inline-styling": 'export const W = () => <div className="x" />;',
+  "frontend/router-links": 'export const W = () => <a href="/notes">go</a>;',
+  "frontend/generated-client-only": 'export const ping = () => fetch("/healthz");',
+  "frontend/no-deep-imports": 'import { x } from "@terp/react-core/src/internal";',
+  "frontend/no-style-imports": 'import "./widget.css";',
+  "frontend/no-cross-module-imports": 'import { x } from "../other/thing";',
+  "frontend/no-dom-html-injection": "export const W = (el, html) => { el.innerHTML = html; };",
+  "frontend/no-eval": "export const run = (code) => eval(code);",
+  "frontend/no-unsafe-href": 'export const W = () => <a href="javascript:alert(1)">x</a>;',
+  "frontend/no-unsafe-target-blank":
+    'export const W = () => <a href="https://example.com" target="_blank">x</a>;',
+};
+
+describe(
+  "opt-out parity: every catalog opt_out spelling suppresses its own rule",
+  () => {
+    for (const entry of CATALOG_ENTRIES) {
+      const optOut = entry.opt_out;
+      if (entry.id === "frontend/escape-hatch") {
+        it("frontend/escape-hatch declares no opt_out (governance is unwaivable)", () => {
+          expect(optOut).toBeUndefined();
+        });
+        continue;
+      }
+      it(`${entry.id} declares its catalog-derived marker`, () => {
+        const name = entry.id.slice("frontend/".length);
+        expect(optOut).toBe(`// terp-allow-${name}: <reason>`);
+      });
+      const snippet = VIOLATION_SNIPPETS[entry.id];
+      if (snippet === undefined) {
+        // frontend/layout-contract needs the opt-in contract config; its marker
+        // behaviour is covered by layouts.test.js with the same spelling.
+        continue;
+      }
+      it(`${entry.id}'s declared marker suppresses its violation`, async () => {
+        const marker = optOut.replace("<reason>", "recorded parity exception");
+        // These snippets violate exactly one rule, so the suppressed result is
+        // COMPLETELY clean — the marker waived its rule and nothing else remains.
+        expect(await lintModuleSource(`${marker}\n${snippet}\n`)).toEqual([]);
+        // ...and the same line without the marker does violate (the fixture is live).
+        expect(await lintModuleSource(`${snippet}\n`)).toContain(entry.id);
+      });
+    }
+  },
+);