@intentius/tsad-conformance 1.4.0

package/src/fixture.ts

@@ -0,0 +1,117 @@
+/**
+ * Fixture format (#7, extended for projects by #24). A directory per fixture
+ * under spec/fixtures/<Rule>/<name>/. Two kinds, told apart by what the
+ * directory contains.
+ *
+ * An *expression* fixture judges one export of one file:
+ *   input.ts     — the module under test
+ *   expect.json  — { "rules": ["S-Template", "F-Eval-Template"],  // identifiers this fixture exercises (#8 gate)
+ *                    "export": "x",                               // which export is judged
+ *                    "shape": "accept" | "reject",                // S-* verdict
+ *                    "fold":  "fold"   | "run",                   // F-* verdict
+ *                    "value": <json> | "$undefined",              // required when fold = "fold"; the sentinel, at the top or nested, means the fold yields undefined there, which JSON cannot write (#82)
+ *                    "rejectAt": { "line": n, "column": n },      // optional, when fold = "run": where the rejection must point
+ *                    "note": "why this fixture exists" }
+ *
+ * A *project* fixture judges every file of a small build, which is what J3
+ * needs: a taint edge cannot be seen in one file.
+ *   project/     — the build's source, one or more .ts files, nested allowed
+ *   expect.json  — { "rules": ["F-Seed", "F-Succ"],
+ *                    "project": true,
+ *                    "verdicts":  { "app.ts": "run", "config.ts": "run" },       // final, after J3
+ *                    "tentative": { "config.ts": "fold" },                        // optional, J2 before J3 disposed
+ *                    "taintedBy": { "config.ts": "app.ts" },                      // optional, the file whose taint reached it
+ *                    "exports":   { "config.ts": { "port": 8080 } },              // optional, for files that finally fold
+ *                    "rejectRule": { "app.ts": "F-Eval-CallLocal" },              // optional, the rule a run verdict must name; checked when the adapter reports one
+ *                    "host":      "shapes",                                       // optional, a named host from host.ts; required if the sources import one
+ *                    "profiles":  ["full"],                                       // optional; see profilesOf for the default
+ *                    "note": "why this fixture exists" }
+ * `tentative` and `taintedBy` are what separate "folds because nothing
+ * reached it" from "would have folded, and an edge killed it" — without them
+ * a project fixture cannot tell F-Seed from F-Taint.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+export interface ExpressionFixture {
+  kind: "expression";
+  profiles: Profile[];
+  id: string; dir: string; input: string;
+  rules: string[]; exportName: string;
+  shape: "accept" | "reject"; fold: "fold" | "run";
+  value?: unknown; rejectAt?: { line: number; column: number }; note?: string;
+}
+export interface ProjectFixture {
+  kind: "project";
+  profiles: Profile[];
+  id: string; dir: string; rules: string[];
+  /** Path relative to project/, to source. Paths use "/" on every platform. */
+  files: Map<string, string>;
+  verdicts: Record<string, "fold" | "run">;
+  tentative?: Record<string, "fold" | "run">;
+  taintedBy?: Record<string, string>;
+  exports?: Record<string, Record<string, unknown>>;
+  /** The rule a `run` verdict must name, per file. An adapter that reports no rule is not held to it. */
+  rejectRule?: Record<string, string>;
+  /** A named host from host.ts. Required for any fixture whose sources import one. */
+  host?: string;
+  note?: string;
+}
+export type Fixture = ExpressionFixture | ProjectFixture;
+
+export type Profile = "full" | "data-host";
+
+/**
+ * The profiles a fixture is judged in (F-Profile, #78). Explicit
+ * `"profiles"` wins. Otherwise: a fixture that names a host, asserts J3's
+ * tentative verdicts or taint edges, or constructs with `new` needs the
+ * runtime, so it is `full` only; anything else is data and belongs to both.
+ */
+export function profilesOf(f: Fixture, explicit?: string[]): Profile[] {
+  if (explicit) return explicit as Profile[];
+  const sources = f.kind === "expression" ? [f.input] : [...f.files.values()];
+  const usesNew = sources.some((s) => /\bnew\s+[A-Za-z_$]/.test(s));
+  if (f.kind === "project" && (f.host || f.tentative || f.taintedBy)) return ["full"];
+  return usesNew ? ["full"] : ["full", "data-host"];
+}
+
+/** Kept as the name the expression-only callers import; `kind` narrows. */
+export const expressionFixtures = (all: Fixture[]): ExpressionFixture[] => all.filter((f): f is ExpressionFixture => f.kind === "expression");
+export const projectFixtures = (all: Fixture[]): ProjectFixture[] => all.filter((f): f is ProjectFixture => f.kind === "project");
+
+function readProject(dir: string): Map<string, string> {
+  const files = new Map<string, string>();
+  const walk = (d: string) => {
+    for (const name of readdirSync(d)) {
+      const p = join(d, name);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (name.endsWith(".ts")) files.set(relative(dir, p).split(/[\\/]/).join("/"), readFileSync(p, "utf8"));
+    }
+  };
+  walk(dir);
+  return files;
+}
+
+export function loadFixtures(root: string): Fixture[] {
+  const out: Fixture[] = [];
+  for (const rule of readdirSync(root)) {
+    const rd = join(root, rule); if (!statSync(rd).isDirectory()) continue;
+    for (const name of readdirSync(rd)) {
+      const d = join(rd, name); if (!statSync(d).isDirectory()) continue;
+      const e = JSON.parse(readFileSync(join(d, "expect.json"), "utf8"));
+      const id = `${rule}/${name}`;
+      if (e.project) {
+        const fx: ProjectFixture = { kind: "project", id, dir: d, rules: e.rules, files: readProject(join(d, "project")), profiles: [],
+          verdicts: e.verdicts, tentative: e.tentative, taintedBy: e.taintedBy, exports: e.exports, rejectRule: e.rejectRule, host: e.host, note: e.note };
+        fx.profiles = profilesOf(fx, e.profiles);
+        out.push(fx);
+      } else {
+        const fx: ExpressionFixture = { kind: "expression", id, dir: d, input: readFileSync(join(d, "input.ts"), "utf8"), profiles: [],
+          rules: e.rules, exportName: e.export, shape: e.shape, fold: e.fold, value: e.value, rejectAt: e.rejectAt, note: e.note };
+        fx.profiles = profilesOf(fx, e.profiles);
+        out.push(fx);
+      }
+    }
+  }
+  return out;
+}

package/src/host.ts

@@ -0,0 +1,105 @@
+/**
+ * Named hosts a fixture may ask for (#61). A fixture is data — `.ts` sources
+ * and a JSON expectation — and F-Host-Interface item 1 requires real classes
+ * that revival can construct, so the classes live here, in code, and a fixture
+ * names the host it wants.
+ *
+ * Neutral by construction: nothing here imports an implementation. An adapter
+ * translates a `ConformanceHost` into whatever its own host interface is.
+ */
+
+/** An intrinsic registration, F-Host-Registry's shape. */
+export interface HostIntrinsic {
+  readonly name: string;
+  readonly isTag: boolean;
+  readonly foldsAsCall?: boolean;
+  readonly foldsEagerly?: boolean;
+  readonly outputKey?: string;
+}
+
+export interface ConformanceHost {
+  readonly name: string;
+  /** F-Host-Trust arm 1: the specifiers this host owns. */
+  readonly ownedSpecifierPrefixes: readonly string[];
+  readonly intrinsics: readonly HostIntrinsic[];
+  readonly helpers: readonly { name: string; module: string; note: string }[];
+  /** Specifier, then export name, to the real value. Revival calls these (F-Val-Fate). */
+  readonly values: ReadonlyMap<string, ReadonlyMap<string, unknown>>;
+}
+
+const DECLARABLE = Symbol.for("tsad.conformance.declarable");
+
+/** F-Host-Interface item 1's shape: `new (props, attributes?)`, carrying the markers an entity carries. */
+class Bucket {
+  readonly entityType = "Bucket";
+  readonly lexicon = "shapes";
+  readonly props: Record<string, unknown>;
+  readonly attributes: Record<string, unknown>;
+  constructor(props: Record<string, unknown> = {}, attributes: Record<string, unknown> = {}) {
+    this.props = props;
+    this.attributes = attributes;
+    Object.defineProperty(this, DECLARABLE, { value: true, enumerable: false });
+  }
+}
+
+/** Spread-`args` arity, the other arm of F-Val-Arity. */
+class Pair {
+  readonly entityType = "Pair";
+  readonly lexicon = "shapes";
+  constructor(readonly left: unknown, readonly right: unknown) {
+    Object.defineProperty(this, DECLARABLE, { value: true, enumerable: false });
+  }
+}
+
+/** A live object the host owns outright, for the F-CallLeak case: no construction involved. */
+const registry = new Map<string, string>([["one", "1"]]);
+
+/** An intrinsic in tag form: revival invokes it as `Name(strings, ...values)`. */
+const join = (strings: readonly string[], ...values: unknown[]): string =>
+  strings.reduce((acc, s, i) => acc + s + (i < values.length ? String(values[i]) : ""), "");
+
+/** An authoring helper: pure, deterministic, the same at fold time as at run time. */
+const upper = (s: string): string => s.toUpperCase();
+
+/** An intrinsic in call form (F-Host-Registry `foldsAsCall`): revival invokes it with the folded arguments. */
+const ref = (name: string): { Ref: string } => ({ Ref: name });
+
+/** An eager intrinsic (`foldsEagerly`): evaluated at fold time, and F-Host-Admission's third clause holds because it is a pure function of its arguments. */
+const count = (items: readonly unknown[]): number => items.length;
+
+/** A plain-data export (F-Host-DataExports): folds as a value through a named import. */
+const SIZES = { small: 1, large: 3 } as const;
+
+const SHAPES: ConformanceHost = {
+  name: "shapes",
+  ownedSpecifierPrefixes: ["@tsad/shapes"],
+  intrinsics: [
+    { name: "join", isTag: true },
+    { name: "ref", isTag: false, foldsAsCall: true },
+    { name: "count", isTag: false, foldsEagerly: true },
+  ],
+  helpers: [{ name: "upper", module: "@tsad/shapes", note: "pure string transform, no environment read" }],
+  values: new Map([
+    [
+      "@tsad/shapes",
+      new Map<string, unknown>([
+        ["Bucket", Bucket],
+        ["Pair", Pair],
+        ["join", join],
+        ["upper", upper],
+        ["ref", ref],
+        ["count", count],
+        ["SIZES", SIZES],
+        ["registry", registry],
+      ]),
+    ],
+  ]),
+};
+
+export const HOSTS: ReadonlyMap<string, ConformanceHost> = new Map([[SHAPES.name, SHAPES]]);
+
+export function requireHost(name: string): ConformanceHost {
+  const h = HOSTS.get(name);
+  if (!h) throw new Error(`no such conformance host: ${name}. Known: ${[...HOSTS.keys()].join(", ")}`);
+  return h;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./adapter.js";
+export * from "./fixture.js";
+export * from "./host.js";
+export * from "./runner.js";
+export * from "./bundled.js";
+export * from "./rules.js";

package/src/rules.test.ts

@@ -0,0 +1,50 @@
+/** #34 — the rule index, the citation check, and chant's docs against both when a checkout is at hand. */
+import { describe, test, expect } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { loadRules, checkCitations, describeFinding, bundledSpecDir } from "./index";
+import { chantAdapter } from "./adapters/chant";
+
+const index = loadRules(bundledSpecDir());
+
+describe("the rule index (#34)", () => {
+  test("indexes every rule the fixture gate knows, with text", () => {
+    expect(index.version).toMatch(/^\d+\.\d+$/);
+    expect(index.rules.size).toBeGreaterThanOrEqual(120);
+    for (const id of ["S-Ident", "F-Eval-Ident", "F-Prebuild", "F-Depth", "F-Val-Fate", "F-Div-Nullish", "F-Host-Trust"]) {
+      expect(index.rules.has(id), id).toBe(true);
+      expect(index.rules.get(id)!.text.length, `${id} has text`).toBeGreaterThan(20);
+    }
+  });
+});
+
+describe("the citation check (#34)", () => {
+  test("an identifier that is not a rule is reported with its line", () => {
+    const f = checkCitations("chant implements F-Eval-Ident.\nAnd also F-Made-Up here.\n", index);
+    expect(f.map(describeFinding)).toEqual(["line 2: F-Made-Up is not a rule of this specification"]);
+  });
+  test("a verbatim quote passes and a paraphrase does not", () => {
+    const depth = index.rules.get("F-Depth")!.text;
+    const words = depth.split(" ").slice(0, 8).join(" ");
+    expect(checkCitations(`{/* rule: F-Depth */}\n> ${words}\n`, index)).toEqual([]);
+    const f = checkCitations(`<!-- rule: F-Depth -->\n> The bounds are whatever an implementation likes.\n`, index);
+    expect(f.map((x) => x.kind)).toEqual(["quote-not-in-rule"]);
+  });
+  test("a marker with no quote, and a declared version that is not the index's", () => {
+    const f = checkCitations(`{/* rule: F-Depth */}\nprose instead of a quote\n`, index, "2.0");
+    expect(f.map((x) => x.kind).sort()).toEqual(["marker-without-quote", "version-mismatch"]);
+  });
+});
+
+const chant = process.env.TSAD_CHANT_REPO ? resolve(process.env.TSAD_CHANT_REPO) : undefined;
+const DOCS = ["docs/src/content/docs/concepts/typescript-as-data.mdx", "docs/src/content/docs/architecture/sandbox.mdx"];
+
+describe.skipIf(!chant || !DOCS.every((d) => existsSync(join(chant, d))))("chant's docs cite only rules that exist (#34)", () => {
+  for (const doc of DOCS) {
+    test(doc, () => {
+      const declared = chantAdapter.specVersion === "undeclared" ? undefined : chantAdapter.specVersion;
+      const findings = checkCitations(readFileSync(join(chant!, doc), "utf8"), index, declared);
+      expect(findings.map(describeFinding), findings.map(describeFinding).join("\n")).toEqual([]);
+    });
+  }
+});

package/src/rules.ts

@@ -0,0 +1,140 @@
+/**
+ * #34 — the rule index, and the check a downstream document runs against it.
+ *
+ * chant's documentation describes the mechanism this specification owns. A
+ * subset change that lands here can leave that prose describing the old
+ * subset, and chant#2306 was three such claims, one in a shape chant's own
+ * parity gate could not see because it only looked at fenced blocks under
+ * headings. This gate looks at rule identifiers instead: every `S-*` or
+ * `F-*` a document cites must exist at the specification version the
+ * document's implementation declares, and where the document quotes a rule,
+ * the quote must be the rule's own text.
+ *
+ * Two things a document can do, and what each is held to:
+ *
+ * - Mention an identifier in prose, `F-Depth`. It must be defined. Nothing
+ *   about the surrounding claim is checked; the identifier is a link, and a
+ *   link to nothing is the failure.
+ * - Quote a rule, as a blockquote directly under a marker line. The marker
+ *   is a comment on a line of its own whose content is `rule: F-Depth`, in
+ *   MDX's comment form or HTML's, and the blockquote follows it:
+ *
+ *       > The rule's text, or its opening, verbatim.
+ *
+ *   The quoted text must occur verbatim in the rule's normative text. A
+ *   paraphrase is a claim the gate cannot check, so it is not accepted where a
+ *   quote was promised.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** The five files that define rules, in reading order. The same list `spec/fixtures.test.ts` gates on. */
+export const RULE_FILES = ["grammar.md", "judgments.md", "values.md", "divergence.md", "hosts.md", "rules.md"] as const;
+
+export interface Rule {
+  readonly id: string;
+  readonly file: string;
+  /** The rule's normative text: from its definition to the next definition or heading, whitespace collapsed. */
+  readonly text: string;
+}
+
+const DEFINITION = [
+  /^#{1,6}\s+([SF]-[A-Za-z0-9-]+)\b/,
+  /^\*\*([SF]-[A-Za-z0-9-]+)[.\s(]/,
+  /^\|\s*([SF]-[A-Za-z0-9-]+)\s*\|/,
+  /^\s*([SF]-[A-Za-z0-9-]+)\s*::=/,
+];
+
+const collapse = (s: string) => s.replace(/\s+/g, " ").trim();
+
+/** Every rule the specification defines, with its text. `specDir` holds the rule files and `VERSION`. */
+export function loadRules(specDir: string): { version: string; rules: Map<string, Rule> } {
+  const version = readFileSync(join(specDir, "VERSION"), "utf8").trim();
+  const rules = new Map<string, Rule>();
+  for (const file of RULE_FILES) {
+    const lines = readFileSync(join(specDir, file), "utf8").split("\n");
+    let current: { id: string; body: string[] } | undefined;
+    const flush = () => {
+      if (!current) return;
+      const text = collapse(current.body.join("\n"));
+      // A rule may be defined in more than one place (a table row and a
+      // rationale paragraph). The first definition wins; later ones append.
+      const prior = rules.get(current.id);
+      rules.set(current.id, { id: current.id, file, text: prior ? `${prior.text} ${text}` : text });
+      current = undefined;
+    };
+    for (const line of lines) {
+      const id = DEFINITION.map((re) => re.exec(line)?.[1]).find(Boolean);
+      if (id) { flush(); current = { id, body: [line] }; continue; }
+      if (/^#{1,6}\s/.test(line) || /^---\s*$/.test(line)) { flush(); continue; }
+      current?.body.push(line);
+    }
+    flush();
+  }
+  return { version, rules };
+}
+
+export type CitationFinding =
+  | { kind: "unknown-identifier"; id: string; line: number }
+  | { kind: "quote-not-in-rule"; id: string; line: number; quote: string }
+  | { kind: "marker-without-quote"; id: string; line: number }
+  | { kind: "version-mismatch"; declared: string; spec: string };
+
+const IDENTIFIER = /\b([SF]-[A-Z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*)\b/g;
+const MARKER = /^\s*(?:\{\/\*|<!--)\s*rule:\s*([SF]-[A-Za-z0-9-]+)\s*(?:\*\/\}|-->)\s*$/;
+
+/**
+ * Check one document's citations against the rule index.
+ *
+ * @param declared the specification version the document's implementation
+ *   declares, compared against the index's; `undefined` skips the comparison
+ *   and is reported as nothing, since an undeclared version is #18's concern
+ *   and not this gate's.
+ */
+export function checkCitations(
+  document: string,
+  index: { version: string; rules: ReadonlyMap<string, Rule> },
+  declared?: string,
+): CitationFinding[] {
+  const findings: CitationFinding[] = [];
+  // Same major, minor not ahead of the index: the policy says an addition
+  // leaves an older minor's rules unchanged, so a document written against
+  // 1.0 is held to 1.1's index. A different major, or a declaration ahead of
+  // the index, is a mismatch.
+  if (declared !== undefined) {
+    const [dm, dn] = declared.split(".").map(Number);
+    const [im, in_] = index.version.split(".").map(Number);
+    if (!(dm === im && dn <= in_)) findings.push({ kind: "version-mismatch", declared, spec: index.version });
+  }
+  const lines = document.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const marker = MARKER.exec(line);
+    if (marker) {
+      const id = marker[1];
+      const rule = index.rules.get(id);
+      if (!rule) { findings.push({ kind: "unknown-identifier", id, line: i + 1 }); continue; }
+      const quoted: string[] = [];
+      let j = i + 1;
+      while (j < lines.length && /^\s*>/.test(lines[j])) quoted.push(lines[j].replace(/^\s*>\s?/, "")), j++;
+      if (quoted.length === 0) { findings.push({ kind: "marker-without-quote", id, line: i + 1 }); continue; }
+      const quote = collapse(quoted.join(" "));
+      if (!rule.text.includes(quote)) findings.push({ kind: "quote-not-in-rule", id, line: i + 1, quote });
+      continue;
+    }
+    for (const m of line.matchAll(IDENTIFIER)) {
+      if (!index.rules.has(m[1])) findings.push({ kind: "unknown-identifier", id: m[1], line: i + 1 });
+    }
+  }
+  return findings;
+}
+
+/** One line per finding, for a test's failure message. */
+export function describeFinding(f: CitationFinding): string {
+  switch (f.kind) {
+    case "unknown-identifier": return `line ${f.line}: ${f.id} is not a rule of this specification`;
+    case "quote-not-in-rule": return `line ${f.line}: the quote under ${f.id} is not the rule's text: "${f.quote}"`;
+    case "marker-without-quote": return `line ${f.line}: rule marker ${f.id} is not followed by a blockquote`;
+    case "version-mismatch": return `the document's implementation declares spec ${f.declared}, the rules are at ${f.spec}`;
+  }
+}

package/src/runner.test.ts

@@ -0,0 +1,46 @@
+import { describe, test, expect } from "vitest";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadFixtures, runFixtures, projectFixtures } from "./index";
+import { referenceAdapter, referenceDataHostAdapter } from "@intentius/tsad-reference";
+
+const fixturesDir = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "spec", "fixtures");
+
+describe("conformance runner (#7) over the reference implementation (#10)", () => {
+  const fixtures = loadFixtures(fixturesDir);
+  test("fixtures load", async () => { expect(fixtures.length).toBeGreaterThan(0); for (const f of fixtures) expect(f.rules.length).toBeGreaterThan(0); });
+  test("the reference implementation passes every fixture of the full profile", async () => {
+    const reports = await runFixtures(referenceAdapter, fixtures.filter((f) => f.profiles.includes("full")));
+    const failed = reports.filter((r) => !r.pass).map((r) => `${r.fixture}: ${r.failures.join("; ")}`);
+    expect(failed, failed.join("\n")).toEqual([]);
+  });
+  test("the data-host profile: the reference with an empty host passes every fixture tagged for it (#78)", async () => {
+    const tagged = fixtures.filter((f) => f.profiles.includes("data-host"));
+    expect(tagged.length).toBeGreaterThan(40);
+    expect(tagged.every((f) => f.kind === "expression" || !f.host)).toBe(true);
+    const failed = (await runFixtures(referenceDataHostAdapter, tagged)).filter((r) => !r.pass).map((r) => `${r.fixture}: ${r.failures.join("; ")}`);
+    expect(failed, failed.join("\n")).toEqual([]);
+  });
+  test("the project fixtures are actually exercised, not all skipped (#24)", async () => {
+    const reports = (await runFixtures(referenceAdapter, fixtures)).filter((r) => projectFixtures(fixtures).some((p) => p.id === r.fixture));
+    expect(reports.length).toBe(projectFixtures(fixtures).length);
+    expect(reports.filter((r) => r.skipped)).toEqual([]);
+  });
+  test("a stub adapter that runs every file fails the project fixtures that expect a fold", async () => {
+    // The control the fixtures themselves describe: falling back everywhere is
+    // sound and useless, and must not pass. Without this, F-Taint's "least set"
+    // would be untested.
+    const stub = {
+      name: "always-runs", specVersion: "1.1", shape: () => "unavailable" as const,
+      foldExport: () => ({ ok: false as const, line: 1, column: 1, message: "runs" }),
+      foldProject: (files: Map<string, string>) => ({ verdicts: Object.fromEntries([...files.keys()].map((p) => [p, { kind: "run" as const, reason: "runs" }])) }),
+    };
+    const failed = (await runFixtures(stub, fixtures)).filter((r) => !r.pass && projectFixtures(fixtures).some((p) => p.id === r.fixture));
+    expect(failed.length).toBeGreaterThan(0);
+  });
+  test("a stub adapter that folds everything to null fails the reject fixture and the value fixtures", async () => {
+    const stub = { name: "stub", specVersion: "1.1", shape: () => ({ accepted: true } as const), foldExport: () => ({ ok: true as const, value: null }) };
+    const reports = await runFixtures(stub, fixtures);
+    expect(reports.some((r) => !r.pass)).toBe(true);
+  });
+});

package/src/runner.ts

@@ -0,0 +1,119 @@
+import type { ConformanceAdapter } from "./adapter.js";
+import type { ExpressionFixture, Fixture, ProjectFixture } from "./fixture.js";
+import { expressionFixtures, projectFixtures } from "./fixture.js";
+import { requireHost } from "./host.js";
+
+export interface FixtureReport { fixture: string; adapter: string; pass: boolean; skipped?: string; failures: string[] }
+
+/**
+ * The comparison form of a folded value. `JSON.stringify` drops an
+ * `undefined`-valued key and turns an `undefined` element into `null`, which
+ * is exactly the distinction F-Val-Undefined draws (#82): a fixture that wants
+ * to see it writes the sentinel `"$undefined"` where the fold must yield
+ * `undefined`, and this encoding maps the fold's `undefined` to the same
+ * sentinel before the two are compared. Non-finite numbers, which JSON cannot
+ * write either, encode as ToString would print them.
+ */
+export function encodeValue(v: unknown): string {
+  const walk = (x: unknown): unknown => {
+    if (x === undefined) return "$undefined";
+    if (typeof x === "number" && !Number.isFinite(x)) return String(x);
+    if (x === null || typeof x !== "object") return x;
+    if (Array.isArray(x)) return x.map(walk);
+    return Object.fromEntries(Object.entries(x).map(([k, e]) => [k, walk(e)]));
+  };
+  return JSON.stringify(walk(v));
+}
+
+export function runFixture(adapter: ConformanceAdapter, f: ExpressionFixture): FixtureReport {
+  const failures: string[] = []; let skipped: string | undefined;
+  const s = adapter.shape(f.input, f.exportName);
+  if (s === "unavailable") skipped = "shape classifier unavailable";
+  else if (s.accepted !== (f.shape === "accept")) failures.push(`shape: expected ${f.shape}, got ${s.accepted ? "accept" : `reject (${s.message})`}`);
+  const r = adapter.foldExport(f.input, f.exportName);
+  if (f.fold === "fold") {
+    if (!r.ok) failures.push(`fold: expected fold, got run (${r.message})`);
+    else if (encodeValue(r.value) !== encodeValue(f.value)) failures.push(`fold: value ${encodeValue(r.value)} ≠ expected ${encodeValue(f.value)}`);
+  } else {
+    if (r.ok) failures.push(`fold: expected run, got fold with ${JSON.stringify(r.value)}`);
+    else if (f.rejectAt && (r.line !== f.rejectAt.line || r.column !== f.rejectAt.column))
+      failures.push(`fold: rejection at ${r.line}:${r.column}, expected ${f.rejectAt.line}:${f.rejectAt.column}`);
+  }
+  return { fixture: f.id, adapter: adapter.name, pass: failures.length === 0, skipped, failures };
+}
+export async function runFixtures(adapter: ConformanceAdapter, fixtures: Fixture[]): Promise<FixtureReport[]> {
+  return [
+    ...expressionFixtures(fixtures).map((f) => runFixture(adapter, f)),
+    ...(await Promise.all(projectFixtures(fixtures).map((f) => runProjectFixture(adapter, f)))),
+  ];
+}
+
+/** #24 — a whole-build fixture. J3's edges are invisible in any single file, so this is the only shape that can test them. */
+export async function runProjectFixture(adapter: ConformanceAdapter, f: ProjectFixture): Promise<FixtureReport> {
+  const base = { fixture: f.id, adapter: adapter.name };
+  if (!adapter.foldProject) return { ...base, pass: true, skipped: "no project entry", failures: [] };
+  const r = await adapter.foldProject(f.files, f.host ? requireHost(f.host) : undefined);
+  if (r === "unavailable") return { ...base, pass: true, skipped: "project entry unavailable", failures: [] };
+  const failures: string[] = [];
+  for (const [path, want] of Object.entries(f.verdicts)) {
+    const got = r.verdicts[path];
+    if (!got) { failures.push(`${path}: no verdict reported`); continue; }
+    if (got.kind !== want) failures.push(`${path}: expected ${want}, got ${got.kind}${got.kind === "run" ? ` (${got.reason})` : ""}`);
+  }
+  for (const path of Object.keys(r.verdicts)) if (!(path in f.verdicts)) failures.push(`${path}: verdict reported but not expected`);
+  for (const [path, want] of Object.entries(f.tentative ?? {})) {
+    if (!r.tentative) { failures.push(`${path}: fixture expects a tentative verdict, adapter reports none`); continue; }
+    if (r.tentative[path] !== want) failures.push(`${path}: tentative expected ${want}, got ${r.tentative[path] ?? "none"}`);
+  }
+  for (const [path, want] of Object.entries(f.taintedBy ?? {})) {
+    if (!r.taintedBy) { failures.push(`${path}: fixture expects a taint source, adapter reports none`); continue; }
+    if (r.taintedBy[path] !== want) failures.push(`${path}: tainted by ${r.taintedBy[path] ?? "nothing"}, expected ${want}`);
+  }
+  for (const [path, want] of Object.entries(f.rejectRule ?? {})) {
+    const got = r.verdicts[path];
+    if (got?.kind !== "run") { failures.push(`${path}: expected a ${want} rejection, but the file folded`); continue; }
+    if (got.rule !== undefined && got.rule !== want) failures.push(`${path}: rejected under ${got.rule}, expected ${want} (${got.reason})`);
+  }
+  for (const [path, want] of Object.entries(f.exports ?? {})) {
+    const got = r.verdicts[path];
+    if (got?.kind !== "fold") { failures.push(`${path}: expected exports, but the file did not fold`); continue; }
+    for (const [name, value] of Object.entries(want)) {
+      if (encodeValue(got.exports[name]) !== encodeValue(value)) {
+        failures.push(`${path}: export ${name} = ${encodeValue(got.exports[name])} ≠ expected ${encodeValue(value)}`);
+      }
+    }
+  }
+  return { ...base, pass: failures.length === 0, failures };
+}
+
+/** #11 — two implementations must agree on every fixture, independently of what the fixture expects. */
+export async function compareAdapters(a: ConformanceAdapter, b: ConformanceAdapter, fixtures: Fixture[]): Promise<string[]> {
+  const dis: string[] = [];
+  for (const f of projectFixtures(fixtures)) {
+    if (!a.foldProject || !b.foldProject) continue;
+    const host = f.host ? requireHost(f.host) : undefined;
+    const [ra, rb] = await Promise.all([a.foldProject(f.files, host), b.foldProject(f.files, host)]);
+    if (ra === "unavailable" || rb === "unavailable") continue;
+    for (const path of new Set([...Object.keys(ra.verdicts), ...Object.keys(rb.verdicts)])) {
+      const va = ra.verdicts[path]?.kind ?? "absent", vb = rb.verdicts[path]?.kind ?? "absent";
+      if (va !== vb) dis.push(`${f.id} ${path}: ${a.name} ${va}, ${b.name} ${vb}`);
+      // The verdict alone cannot tell a seed from a taint casualty, and both of
+      // those are "run". Where both implementations report the tentative
+      // verdict and the edge, compare them: that is where J3 actually lives.
+      if (ra.tentative && rb.tentative && ra.tentative[path] !== rb.tentative[path]) {
+        dis.push(`${f.id} ${path}: tentative — ${a.name} ${ra.tentative[path] ?? "none"}, ${b.name} ${rb.tentative[path] ?? "none"}`);
+      }
+      if (ra.taintedBy && rb.taintedBy && ra.taintedBy[path] !== rb.taintedBy[path]) {
+        dis.push(`${f.id} ${path}: tainted by — ${a.name} ${ra.taintedBy[path] ?? "nothing"}, ${b.name} ${rb.taintedBy[path] ?? "nothing"}`);
+      }
+    }
+  }
+  for (const f of expressionFixtures(fixtures)) {
+    const ra = a.foldExport(f.input, f.exportName), rb = b.foldExport(f.input, f.exportName);
+    if (ra.ok !== rb.ok) dis.push(`${f.id}: ${a.name} ${ra.ok ? "folds" : "runs"}, ${b.name} ${rb.ok ? "folds" : "runs"}`);
+    else if (ra.ok && rb.ok && encodeValue(ra.value) !== encodeValue(rb.value)) dis.push(`${f.id}: values differ — ${a.name} ${encodeValue(ra.value)} vs ${b.name} ${encodeValue(rb.value)}`);
+    const sa = a.shape(f.input, f.exportName), sb = b.shape(f.input, f.exportName);
+    if (sa !== "unavailable" && sb !== "unavailable" && sa.accepted !== sb.accepted) dis.push(`${f.id}: shape — ${a.name} ${sa.accepted ? "accepts" : "rejects"}, ${b.name} ${sb.accepted ? "accepts" : "rejects"}`);
+  }
+  return dis;
+}

package/src/version.test.ts

@@ -0,0 +1,31 @@
+/** #18 — the reference implementation declares the specification version it implements, and it is the current one. */
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { referenceAdapter } from "@intentius/tsad-reference";
+import { chantAdapter } from "./adapters/chant";
+
+const VERSION = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "spec", "VERSION"), "utf8").trim();
+
+describe("specification version (#18)", () => {
+  test("spec/VERSION is a major.minor", () => {
+    expect(VERSION).toMatch(/^\d+\.\d+$/);
+  });
+  test("the changelog's newest entry is the current version", () => {
+    const changelog = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "spec", "CHANGELOG.md"), "utf8");
+    const newest = /^## (\d+\.\d+)\b/m.exec(changelog)?.[1];
+    expect(newest, "CHANGELOG.md has no versioned entry").toBe(VERSION);
+  });
+  test("the reference implementation declares the current version", () => {
+    expect(referenceAdapter.specVersion).toBe(VERSION);
+  });
+  test("chant declares a version of this specification's major (chant#2424)", () => {
+    // chant-v0.71.0 exports SPEC_VERSION. It may lag the minor: the policy says
+    // an implementation of 1.0 implements 1.1's full profile unchanged, so what
+    // is asserted is a real declaration on the same major, never "undeclared".
+    expect(chantAdapter.specVersion).toMatch(/^\d+\.\d+$/);
+    expect(chantAdapter.specVersion.split(".")[0]).toBe(VERSION.split(".")[0]);
+    expect(Number(chantAdapter.specVersion.split(".")[1])).toBeLessThanOrEqual(Number(VERSION.split(".")[1]));
+  });
+});