@particle-academy/fancy-conformance 0.0.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,10 +1,165 @@
-# Placeholder
+# fancy-conformance
 
-This `0.0.0` exists only to claim the name so a **Trusted Publisher** can be
-configured — npm has no way to configure OIDC for a package that does not exist
-yet, and staged publishing explicitly cannot create a new name either.
+Shared cross-language conformance fixtures for the [Fancy](https://ui.particle.academy) suite.
 
-Do not install this version. The real releases are published from GitHub Actions
-with provenance, starting at `0.1.0`.
+One contract, N implementations, and a single fixture table that **every**
+implementation asserts in **its own CI, on every push** — so "parity" is a test
+result rather than a claim.
 
-https://github.com/Particle-Academy/fancy-conformance
+```bash
+npm install --save-dev @particle-academy/fancy-conformance
+composer require --dev particle-academy/fancy-conformance
+```
+
+For a language with no package yet, every release attaches a plain
+`fancy-conformance-<version>.tar.gz` containing just the fixtures — no npm, no
+Composer, no JavaScript toolchain.
+
+## The policy
+
+> **N implementations of one contract are acceptable if and only if a shared
+> fixture table is asserted by every implementation, in that implementation's
+> own CI, on every push.**
+
+Anything less is not parity. It is a transliteration with a README.
+
+## Why this exists
+
+Most Fancy server capabilities ship as a matched PHP + Node pair, so the same
+feature works behind the same UI whichever backend runs it. Keeping two
+implementations honest by hand does not work, and we have the receipts:
+
+- `mcp-relay-client` ships four single-file clients. All four were
+  hand-transliterated in one commit and none was touched again while the
+  TypeScript source took four substantive changes. Result: **9 divergences**,
+  including a wrong default relay path in all four. CI never compiled the Go
+  one, never imported the Python one, never executed the shell one.
+- `holy-sheet`'s PHP↔JS parity suite — the strongest guarantee in that pair —
+  **never ran in CI**. `describe.skipIf(!HAS_PHP)` skipped silently and the
+  workflow installed Node only. It also hard-coded `../../holy-sheet/src/`, so
+  it worked in exactly one directory layout.
+- `dark-slide`'s harness had the same shape, with the same green-on-zero-coverage
+  outcome.
+- The `FeatureSource` contract is byte-identical in two packages and maintained
+  by hand. It survives only because TypeScript's structural typing does the
+  checking — a mechanism that does not exist in Rust or Go.
+
+**The counter-example is in the same org and is the whole argument.**
+`satisfiesRange` is *also* a three-way duplicate — `fancy-ui-cli`, `fancy-flow`,
+`fancy-flow-php` — and it has **not** drifted. The only thing it does
+differently: each repo carries the identical case table in its own CI, the PHP
+one literally titled *"matches the TypeScript satisfiesRange, clause for
+clause."*
+
+Same organisation, same problem shape, opposite outcome. The variable is the
+shared table. That table is now `suites/shared/satisfies-range/`, promoted here
+verbatim.
+
+## What is in here
+
+| Suite | Cases | Pins |
+|---|---|---|
+| `shared/satisfies-range` | 17 | Minimal semver range matching, including **two rows that deliberately disagree with standard semver** |
+| `shared/decimal` | 18 | Float formatting, numeric-string coercion, and money rounding |
+| `shared/strings` | 8 | Inline-markdown segmentation across CJK, emoji, combining marks and accented Latin |
+
+Every case carries an `id`, a `title`, the suite version it arrived in, and —
+where it exists to catch something specific — a `notes` field saying what.
+
+## Using it
+
+```ts
+import { runTable, formatSummary } from "@particle-academy/fancy-conformance";
+import { satisfiesRange } from "../src/marketplace/manifest";
+
+const summary = runTable(
+  "shared/satisfies-range",
+  (c) => satisfiesRange(c.input.version, c.input.range),
+  { language: "node" },
+);
+
+console.log(formatSummary(summary));   // always — see rule 3
+if (!summary.ok) process.exit(1);
+```
+
+```php
+use ParticleAcademy\Conformance\Conformance;
+
+$summary = Conformance::runTable(
+    'shared/satisfies-range',
+    fn (array $c) => NodeManifest::satisfiesRange($c['input']['version'], $c['input']['range']),
+);
+
+echo Conformance::formatSummary($summary), "\n";
+exit($summary['ok'] ? 0 : 1);
+```
+
+Full runner contract, including the subprocess CLI for suites that emit
+documents rather than return values: [`runners/README.md`](./runners/README.md).
+
+## The four rules for a consuming repo
+
+Each one is traceable to a suite in this org that reported green while covering
+nothing.
+
+1. **Run the suite on every push and PR.** Not nightly, not at release.
+2. **A missing toolchain is a FAILURE, not a skip.** `skipIf(!HAS_PHP)`
+   returning green is the specific mechanism that hid two-way drift for months.
+   If the suite cannot run, the job goes red.
+3. **Print the summary unconditionally, including every skip and its reason.**
+   A bare "3 skipped" reads identically to full coverage at a glance.
+4. **Print and assert the pinned suite version**, so "we're on an old fixture
+   set" is visible rather than inferred.
+
+## Skipping a case
+
+`skip` is the only sanctioned way not to run a case, it is keyed by language,
+and **the reason may not be empty** — an empty one is a load error, in both
+loaders, asserted on both sides:
+
+```json
+{
+  "id": "0014-round-negative-half",
+  "skip": { "go": "no decimal type yet — tracking Particle-Academy/…#12" }
+}
+```
+
+Every runner prints every skip. A silent skip is what turned two existing parity
+suites into decoration, so it is not representable here.
+
+## This repository holds itself to the same standard
+
+It ships two loaders for one fixture format, which is itself a duplicated
+contract. So:
+
+- Each language's test suite proves that language reads the fixtures correctly.
+- `npm run cross-check` runs **both** loaders over the same suites and requires
+  identical verdicts case by case — the claim neither suite can make about
+  itself. It is a required CI job, and it exits non-zero if zero cases were
+  compared.
+- `tests/discrimination.test.ts` runs deliberately **wrong** implementations and
+  requires each to fail the exact cases that exist to catch it. A golden table
+  that every plausible implementation passes is decoration; this is what proves
+  it is not.
+
+## Adding a case
+
+A new case lands **here first, red**, then in each implementation. Where an
+implementation cannot pass it yet, it gets a `skip` with a real reason and a
+tracking issue — and that skip appears in that repo's CI log every run until it
+is gone.
+
+Never renumber an id. Ids appear in changelogs and in other repos' skip lists.
+
+## Versioning
+
+`VERSION` is the fixture set's own semver, and the publish workflow refuses a
+tag unless the tag, `VERSION` and `package.json` all agree. Every implementation
+pins a version and states it in its README; raising the pin is a deliberate act
+with a changelog entry.
+
+Pre-1.0, breaking changes land in minor releases.
+
+## License
+
+MIT

package/VERSION

@@ -0,0 +1 @@
+0.2.0

package/dist/index.cjs

@@ -0,0 +1,201 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  deepEquals: () => deepEquals,
+  formatSummary: () => formatSummary,
+  listSuites: () => listSuites,
+  loadSuite: () => loadSuite,
+  loadSuiteFrom: () => loadSuiteFrom,
+  runTable: () => runTable,
+  suitePath: () => suitePath,
+  suiteVersion: () => suiteVersion
+});
+module.exports = __toCommonJS(src_exports);
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_node_url = require("url");
+var import_meta = {};
+function packageRoot() {
+  let dir = (0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
+  for (let i = 0; i < 6; i++) {
+    try {
+      if ((0, import_node_fs.statSync)((0, import_node_path.join)(dir, "suites")).isDirectory()) {
+        return dir;
+      }
+    } catch {
+    }
+    const parent = (0, import_node_path.dirname)(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    "fancy-conformance: could not locate the suites/ directory. If you vendored this package, keep suites/ next to dist/."
+  );
+}
+function suiteVersion() {
+  return (0, import_node_fs.readFileSync)((0, import_node_path.join)(packageRoot(), "VERSION"), "utf8").trim();
+}
+function listSuites() {
+  const root = (0, import_node_path.join)(packageRoot(), "suites");
+  const found = [];
+  const walk = (dir) => {
+    for (const entry of (0, import_node_fs.readdirSync)(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const child = (0, import_node_path.join)(dir, entry.name);
+      try {
+        (0, import_node_fs.statSync)((0, import_node_path.join)(child, "manifest.json"));
+        found.push((0, import_node_path.relative)(root, child).split(import_node_path.sep).join("/"));
+      } catch {
+        walk(child);
+      }
+    }
+  };
+  walk(root);
+  return found.sort();
+}
+function loadSuite(id) {
+  return loadSuiteFrom(packageRoot(), id);
+}
+function loadSuiteFrom(root, id) {
+  const dir = (0, import_node_path.join)(root, "suites", ...id.split("/"));
+  const manifest = JSON.parse((0, import_node_fs.readFileSync)((0, import_node_path.join)(dir, "manifest.json"), "utf8"));
+  if (manifest.caseFormat !== "table") {
+    throw new Error(
+      `fancy-conformance: suite "${id}" uses caseFormat "${manifest.caseFormat}", which loadSuite() does not read. Use the artifact runner in runners/.`
+    );
+  }
+  const table = JSON.parse(
+    (0, import_node_fs.readFileSync)((0, import_node_path.join)(dir, manifest.cases ?? "cases.json"), "utf8")
+  );
+  assertUsableCases(id, table.cases);
+  return { manifest, cases: table.cases };
+}
+function assertUsableCases(id, cases) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const c of cases) {
+    if (seen.has(c.id)) {
+      throw new Error(`fancy-conformance: suite "${id}" has duplicate case id "${c.id}".`);
+    }
+    seen.add(c.id);
+    for (const [lang, reason] of Object.entries(c.skip ?? {})) {
+      if (typeof reason !== "string" || reason.trim() === "") {
+        throw new Error(
+          `fancy-conformance: case "${id}/${c.id}" skips ${lang} with no reason. A skip must say why, because every runner prints it.`
+        );
+      }
+    }
+  }
+}
+function runTable(suiteId, impl, options) {
+  const { manifest, cases } = loadSuite(suiteId);
+  const equals = options.equals ?? deepEquals;
+  const results = [];
+  for (const c of cases) {
+    const reason = c.skip?.[options.language];
+    if (reason !== void 0) {
+      results.push({ id: c.id, title: c.title, status: "skip", reason });
+      continue;
+    }
+    let actual;
+    try {
+      actual = impl(c);
+    } catch (error) {
+      results.push({
+        id: c.id,
+        title: c.title,
+        status: "fail",
+        expected: c.expected,
+        actual: `threw: ${error instanceof Error ? error.message : String(error)}`
+      });
+      continue;
+    }
+    results.push(
+      equals(actual, c.expected) ? { id: c.id, title: c.title, status: "pass" } : { id: c.id, title: c.title, status: "fail", expected: c.expected, actual }
+    );
+  }
+  const failed = results.filter((r) => r.status === "fail").length;
+  return {
+    suite: manifest.suite,
+    language: options.language,
+    suiteVersion: suiteVersion(),
+    passed: results.filter((r) => r.status === "pass").length,
+    failed,
+    skipped: results.filter((r) => r.status === "skip").length,
+    results,
+    ok: failed === 0
+  };
+}
+function formatSummary(summary) {
+  const lines = [
+    `${summary.suite} [${summary.language}] \u2014 fancy-conformance ${summary.suiteVersion}`,
+    `  ${summary.passed} passed, ${summary.failed} failed, ${summary.skipped} skipped`
+  ];
+  for (const r of summary.results) {
+    if (r.status === "skip") {
+      lines.push(`  SKIP ${r.id} \u2014 ${r.reason}`);
+    }
+    if (r.status === "fail") {
+      lines.push(`  FAIL ${r.id} ${r.title}`);
+      lines.push(`       expected: ${preview(r.expected)}`);
+      lines.push(`       actual:   ${preview(r.actual)}`);
+    }
+  }
+  return lines.join("\n");
+}
+function preview(value) {
+  const s = typeof value === "string" ? value : JSON.stringify(value);
+  if (s === void 0) return String(value);
+  return s.length > 120 ? `${s.slice(0, 60)}\u2026${s.slice(-40)} (len ${s.length})` : s;
+}
+function deepEquals(a, b) {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((v, i) => deepEquals(v, b[i]));
+  }
+  if (typeof a === "object") {
+    const ka = Object.keys(a).sort();
+    const kb = Object.keys(b).sort();
+    if (ka.length !== kb.length || ka.some((k, i) => k !== kb[i])) return false;
+    return ka.every(
+      (k) => deepEquals(a[k], b[k])
+    );
+  }
+  return false;
+}
+function suitePath(id) {
+  return (0, import_node_path.resolve)((0, import_node_path.join)(packageRoot(), "suites", ...id.split("/")));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  deepEquals,
+  formatSummary,
+  listSuites,
+  loadSuite,
+  loadSuiteFrom,
+  runTable,
+  suitePath,
+  suiteVersion
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { readFileSync, readdirSync, statSync } from \"node:fs\";\nimport { dirname, join, relative, resolve, sep } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nimport type {\n  CaseResult,\n  ConformanceCase,\n  Language,\n  RunSummary,\n  Suite,\n  SuiteManifest,\n} from \"./types\";\n\nexport * from \"./types\";\n\n/**\n * The repository root, whether this is running from `dist/` in an installed\n * package or from `src/` in a checkout.\n *\n * Resolved by walking up to the directory that holds `suites/`, rather than by\n * a fixed `../..`. The two existing parity harnesses in this suite both\n * hard-coded a relative path to a sibling checkout (`../../holy-sheet/src/`),\n * which is why they work in exactly one directory layout and silently no-op\n * everywhere else. This package must not repeat that.\n */\nfunction packageRoot(): string {\n  let dir = dirname(fileURLToPath(import.meta.url));\n\n  for (let i = 0; i < 6; i++) {\n    try {\n      if (statSync(join(dir, \"suites\")).isDirectory()) {\n        return dir;\n      }\n    } catch {\n      // keep walking\n    }\n    const parent = dirname(dir);\n    if (parent === dir) break;\n    dir = parent;\n  }\n\n  throw new Error(\n    \"fancy-conformance: could not locate the suites/ directory. \" +\n      \"If you vendored this package, keep suites/ next to dist/.\",\n  );\n}\n\n/** The suite collection's own version — the thing a runner must print. */\nexport function suiteVersion(): string {\n  return readFileSync(join(packageRoot(), \"VERSION\"), \"utf8\").trim();\n}\n\n/** Every suite id present, e.g. `[\"shared/decimal\", \"shared/satisfies-range\", …]`. */\nexport function listSuites(): string[] {\n  const root = join(packageRoot(), \"suites\");\n  const found: string[] = [];\n\n  const walk = (dir: string): void => {\n    for (const entry of readdirSync(dir, { withFileTypes: true })) {\n      if (!entry.isDirectory()) continue;\n      const child = join(dir, entry.name);\n      try {\n        statSync(join(child, \"manifest.json\"));\n        found.push(relative(root, child).split(sep).join(\"/\"));\n      } catch {\n        walk(child);\n      }\n    }\n  };\n\n  walk(root);\n  return found.sort();\n}\n\n/** Load one suite's manifest and cases. Throws rather than returning a partial. */\nexport function loadSuite(id: string): Suite {\n  return loadSuiteFrom(packageRoot(), id);\n}\n\n/**\n * Load a suite from an explicit root.\n *\n * Exported so the load-time guards below can be tested against a throwaway\n * fixture tree, rather than a test re-implementing them. A guard asserted by a\n * copy of itself is the failure mode this whole repository exists to stop, and\n * it would be an embarrassing one to ship here.\n */\nexport function loadSuiteFrom(root: string, id: string): Suite {\n  const dir = join(root, \"suites\", ...id.split(\"/\"));\n  const manifest = JSON.parse(readFileSync(join(dir, \"manifest.json\"), \"utf8\")) as SuiteManifest;\n\n  if (manifest.caseFormat !== \"table\") {\n    throw new Error(\n      `fancy-conformance: suite \"${id}\" uses caseFormat \"${manifest.caseFormat}\", ` +\n        \"which loadSuite() does not read. Use the artifact runner in runners/.\",\n    );\n  }\n\n  const table = JSON.parse(\n    readFileSync(join(dir, manifest.cases ?? \"cases.json\"), \"utf8\"),\n  ) as { cases: ConformanceCase[] };\n\n  assertUsableCases(id, table.cases);\n\n  return { manifest, cases: table.cases };\n}\n\n/**\n * Reject a case table that cannot do its job, at LOAD time.\n *\n * A skip with no reason, and a duplicate id, are both silent in every other\n * respect: the suite still loads, still reports green, and still covers less\n * than it appears to. That is the exact failure this repository exists to stop,\n * so it is a hard error here rather than a lint somewhere else.\n */\nfunction assertUsableCases(id: string, cases: ConformanceCase[]): void {\n  const seen = new Set<string>();\n\n  for (const c of cases) {\n    if (seen.has(c.id)) {\n      throw new Error(`fancy-conformance: suite \"${id}\" has duplicate case id \"${c.id}\".`);\n    }\n    seen.add(c.id);\n\n    for (const [lang, reason] of Object.entries(c.skip ?? {})) {\n      if (typeof reason !== \"string\" || reason.trim() === \"\") {\n        throw new Error(\n          `fancy-conformance: case \"${id}/${c.id}\" skips ${lang} with no reason. ` +\n            \"A skip must say why, because every runner prints it.\",\n        );\n      }\n    }\n  }\n}\n\nexport interface RunOptions {\n  /** Which language is under test — decides which `skip` entries apply. */\n  language: Language;\n  /**\n   * Compare a produced value with the expected one. Defaults to a\n   * canonicalising deep equality: object keys sorted, arrays order-sensitive.\n   */\n  equals?: (actual: unknown, expected: unknown) => boolean;\n}\n\n/**\n * Run one implementation against a table suite.\n *\n * `impl` receives the case and returns the value to compare. Throwing is a\n * failure, not a crash — a case that blows up is data about the implementation.\n */\nexport function runTable(\n  suiteId: string,\n  impl: (c: ConformanceCase) => unknown,\n  options: RunOptions,\n): RunSummary {\n  const { manifest, cases } = loadSuite(suiteId);\n  const equals = options.equals ?? deepEquals;\n  const results: CaseResult[] = [];\n\n  for (const c of cases) {\n    const reason = c.skip?.[options.language];\n    if (reason !== undefined) {\n      results.push({ id: c.id, title: c.title, status: \"skip\", reason });\n      continue;\n    }\n\n    let actual: unknown;\n    try {\n      actual = impl(c);\n    } catch (error) {\n      results.push({\n        id: c.id,\n        title: c.title,\n        status: \"fail\",\n        expected: c.expected,\n        actual: `threw: ${error instanceof Error ? error.message : String(error)}`,\n      });\n      continue;\n    }\n\n    results.push(\n      equals(actual, c.expected)\n        ? { id: c.id, title: c.title, status: \"pass\" }\n        : { id: c.id, title: c.title, status: \"fail\", expected: c.expected, actual },\n    );\n  }\n\n  const failed = results.filter((r) => r.status === \"fail\").length;\n\n  return {\n    suite: manifest.suite,\n    language: options.language,\n    suiteVersion: suiteVersion(),\n    passed: results.filter((r) => r.status === \"pass\").length,\n    failed,\n    skipped: results.filter((r) => r.status === \"skip\").length,\n    results,\n    ok: failed === 0,\n  };\n}\n\n/**\n * A summary a CI log can be read from — including every skip, by name and\n * reason.\n *\n * Skips are printed unconditionally and never folded into a count. \"3 skipped\"\n * in a log is indistinguishable from full coverage at a glance, which is how a\n * suite stops meaning anything without anyone deciding that it should.\n */\nexport function formatSummary(summary: RunSummary): string {\n  const lines: string[] = [\n    `${summary.suite} [${summary.language}] — fancy-conformance ${summary.suiteVersion}`,\n    `  ${summary.passed} passed, ${summary.failed} failed, ${summary.skipped} skipped`,\n  ];\n\n  for (const r of summary.results) {\n    if (r.status === \"skip\") {\n      lines.push(`  SKIP ${r.id} — ${r.reason}`);\n    }\n    if (r.status === \"fail\") {\n      lines.push(`  FAIL ${r.id} ${r.title}`);\n      lines.push(`       expected: ${preview(r.expected)}`);\n      lines.push(`       actual:   ${preview(r.actual)}`);\n    }\n  }\n\n  return lines.join(\"\\n\");\n}\n\nfunction preview(value: unknown): string {\n  const s = typeof value === \"string\" ? value : JSON.stringify(value);\n  if (s === undefined) return String(value);\n  return s.length > 120 ? `${s.slice(0, 60)}…${s.slice(-40)} (len ${s.length})` : s;\n}\n\n/** Order-sensitive for arrays, order-insensitive for object keys. */\nexport function deepEquals(a: unknown, b: unknown): boolean {\n  if (Object.is(a, b)) return true;\n  if (typeof a !== typeof b) return false;\n  if (a === null || b === null) return false;\n\n  if (Array.isArray(a) || Array.isArray(b)) {\n    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;\n    return a.every((v, i) => deepEquals(v, b[i]));\n  }\n\n  if (typeof a === \"object\") {\n    const ka = Object.keys(a as object).sort();\n    const kb = Object.keys(b as object).sort();\n    if (ka.length !== kb.length || ka.some((k, i) => k !== kb[i])) return false;\n    return ka.every((k) =>\n      deepEquals((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]),\n    );\n  }\n\n  return false;\n}\n\n/** Absolute path to a suite's directory — for runners that read artifacts. */\nexport function suitePath(id: string): string {\n  return resolve(join(packageRoot(), \"suites\", ...id.split(\"/\")));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,qBAAoD;AACpD,uBAAsD;AACtD,sBAA8B;AAF9B;AAyBA,SAAS,cAAsB;AAC7B,MAAI,UAAM,8BAAQ,+BAAc,YAAY,GAAG,CAAC;AAEhD,WAAS,IAAI,GAAG,IAAI,GAAG,KAAK;AAC1B,QAAI;AACF,cAAI,6BAAS,uBAAK,KAAK,QAAQ,CAAC,EAAE,YAAY,GAAG;AAC/C,eAAO;AAAA,MACT;AAAA,IACF,QAAQ;AAAA,IAER;AACA,UAAM,aAAS,0BAAQ,GAAG;AAC1B,QAAI,WAAW,IAAK;AACpB,UAAM;AAAA,EACR;AAEA,QAAM,IAAI;AAAA,IACR;AAAA,EAEF;AACF;AAGO,SAAS,eAAuB;AACrC,aAAO,iCAAa,uBAAK,YAAY,GAAG,SAAS,GAAG,MAAM,EAAE,KAAK;AACnE;AAGO,SAAS,aAAuB;AACrC,QAAM,WAAO,uBAAK,YAAY,GAAG,QAAQ;AACzC,QAAM,QAAkB,CAAC;AAEzB,QAAM,OAAO,CAAC,QAAsB;AAClC,eAAW,aAAS,4BAAY,KAAK,EAAE,eAAe,KAAK,CAAC,GAAG;AAC7D,UAAI,CAAC,MAAM,YAAY,EAAG;AAC1B,YAAM,YAAQ,uBAAK,KAAK,MAAM,IAAI;AAClC,UAAI;AACF,yCAAS,uBAAK,OAAO,eAAe,CAAC;AACrC,cAAM,SAAK,2BAAS,MAAM,KAAK,EAAE,MAAM,oBAAG,EAAE,KAAK,GAAG,CAAC;AAAA,MACvD,QAAQ;AACN,aAAK,KAAK;AAAA,MACZ;AAAA,IACF;AAAA,EACF;AAEA,OAAK,IAAI;AACT,SAAO,MAAM,KAAK;AACpB;AAGO,SAAS,UAAU,IAAmB;AAC3C,SAAO,cAAc,YAAY,GAAG,EAAE;AACxC;AAUO,SAAS,cAAc,MAAc,IAAmB;AAC7D,QAAM,UAAM,uBAAK,MAAM,UAAU,GAAG,GAAG,MAAM,GAAG,CAAC;AACjD,QAAM,WAAW,KAAK,UAAM,iCAAa,uBAAK,KAAK,eAAe,GAAG,MAAM,CAAC;AAE5E,MAAI,SAAS,eAAe,SAAS;AACnC,UAAM,IAAI;AAAA,MACR,6BAA6B,EAAE,sBAAsB,SAAS,UAAU;AAAA,IAE1E;AAAA,EACF;AAEA,QAAM,QAAQ,KAAK;AAAA,QACjB,iCAAa,uBAAK,KAAK,SAAS,SAAS,YAAY,GAAG,MAAM;AAAA,EAChE;AAEA,oBAAkB,IAAI,MAAM,KAAK;AAEjC,SAAO,EAAE,UAAU,OAAO,MAAM,MAAM;AACxC;AAUA,SAAS,kBAAkB,IAAY,OAAgC;AACrE,QAAM,OAAO,oBAAI,IAAY;AAE7B,aAAW,KAAK,OAAO;AACrB,QAAI,KAAK,IAAI,EAAE,EAAE,GAAG;AAClB,YAAM,IAAI,MAAM,6BAA6B,EAAE,4BAA4B,EAAE,EAAE,IAAI;AAAA,IACrF;AACA,SAAK,IAAI,EAAE,EAAE;AAEb,eAAW,CAAC,MAAM,MAAM,KAAK,OAAO,QAAQ,EAAE,QAAQ,CAAC,CAAC,GAAG;AACzD,UAAI,OAAO,WAAW,YAAY,OAAO,KAAK,MAAM,IAAI;AACtD,cAAM,IAAI;AAAA,UACR,4BAA4B,EAAE,IAAI,EAAE,EAAE,WAAW,IAAI;AAAA,QAEvD;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;AAkBO,SAAS,SACd,SACA,MACA,SACY;AACZ,QAAM,EAAE,UAAU,MAAM,IAAI,UAAU,OAAO;AAC7C,QAAM,SAAS,QAAQ,UAAU;AACjC,QAAM,UAAwB,CAAC;AAE/B,aAAW,KAAK,OAAO;AACrB,UAAM,SAAS,EAAE,OAAO,QAAQ,QAAQ;AACxC,QAAI,WAAW,QAAW;AACxB,cAAQ,KAAK,EAAE,IAAI,EAAE,IAAI,OAAO,EAAE,OAAO,QAAQ,QAAQ,OAAO,CAAC;AACjE;AAAA,IACF;AAEA,QAAI;AACJ,QAAI;AACF,eAAS,KAAK,CAAC;AAAA,IACjB,SAAS,OAAO;AACd,cAAQ,KAAK;AAAA,QACX,IAAI,EAAE;AAAA,QACN,OAAO,EAAE;AAAA,QACT,QAAQ;AAAA,QACR,UAAU,EAAE;AAAA,QACZ,QAAQ,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC;AAAA,MAC1E,CAAC;AACD;AAAA,IACF;AAEA,YAAQ;AAAA,MACN,OAAO,QAAQ,EAAE,QAAQ,IACrB,EAAE,IAAI,EAAE,IAAI,OAAO,EAAE,OAAO,QAAQ,OAAO,IAC3C,EAAE,IAAI,EAAE,IAAI,OAAO,EAAE,OAAO,QAAQ,QAAQ,UAAU,EAAE,UAAU,OAAO;AAAA,IAC/E;AAAA,EACF;AAEA,QAAM,SAAS,QAAQ,OAAO,CAAC,MAAM,EAAE,WAAW,MAAM,EAAE;AAE1D,SAAO;AAAA,IACL,OAAO,SAAS;AAAA,IAChB,UAAU,QAAQ;AAAA,IAClB,cAAc,aAAa;AAAA,IAC3B,QAAQ,QAAQ,OAAO,CAAC,MAAM,EAAE,WAAW,MAAM,EAAE;AAAA,IACnD;AAAA,IACA,SAAS,QAAQ,OAAO,CAAC,MAAM,EAAE,WAAW,MAAM,EAAE;AAAA,IACpD;AAAA,IACA,IAAI,WAAW;AAAA,EACjB;AACF;AAUO,SAAS,cAAc,SAA6B;AACzD,QAAM,QAAkB;AAAA,IACtB,GAAG,QAAQ,KAAK,KAAK,QAAQ,QAAQ,8BAAyB,QAAQ,YAAY;AAAA,IAClF,KAAK,QAAQ,MAAM,YAAY,QAAQ,MAAM,YAAY,QAAQ,OAAO;AAAA,EAC1E;AAEA,aAAW,KAAK,QAAQ,SAAS;AAC/B,QAAI,EAAE,WAAW,QAAQ;AACvB,YAAM,KAAK,UAAU,EAAE,EAAE,WAAM,EAAE,MAAM,EAAE;AAAA,IAC3C;AACA,QAAI,EAAE,WAAW,QAAQ;AACvB,YAAM,KAAK,UAAU,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE;AACtC,YAAM,KAAK,oBAAoB,QAAQ,EAAE,QAAQ,CAAC,EAAE;AACpD,YAAM,KAAK,oBAAoB,QAAQ,EAAE,MAAM,CAAC,EAAE;AAAA,IACpD;AAAA,EACF;AAEA,SAAO,MAAM,KAAK,IAAI;AACxB;AAEA,SAAS,QAAQ,OAAwB;AACvC,QAAM,IAAI,OAAO,UAAU,WAAW,QAAQ,KAAK,UAAU,KAAK;AAClE,MAAI,MAAM,OAAW,QAAO,OAAO,KAAK;AACxC,SAAO,EAAE,SAAS,MAAM,GAAG,EAAE,MAAM,GAAG,EAAE,CAAC,SAAI,EAAE,MAAM,GAAG,CAAC,SAAS,EAAE,MAAM,MAAM;AAClF;AAGO,SAAS,WAAW,GAAY,GAAqB;AAC1D,MAAI,OAAO,GAAG,GAAG,CAAC,EAAG,QAAO;AAC5B,MAAI,OAAO,MAAM,OAAO,EAAG,QAAO;AAClC,MAAI,MAAM,QAAQ,MAAM,KAAM,QAAO;AAErC,MAAI,MAAM,QAAQ,CAAC,KAAK,MAAM,QAAQ,CAAC,GAAG;AACxC,QAAI,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,OAAQ,QAAO;AAC5E,WAAO,EAAE,MAAM,CAAC,GAAG,MAAM,WAAW,GAAG,EAAE,CAAC,CAAC,CAAC;AAAA,EAC9C;AAEA,MAAI,OAAO,MAAM,UAAU;AACzB,UAAM,KAAK,OAAO,KAAK,CAAW,EAAE,KAAK;AACzC,UAAM,KAAK,OAAO,KAAK,CAAW,EAAE,KAAK;AACzC,QAAI,GAAG,WAAW,GAAG,UAAU,GAAG,KAAK,CAAC,GAAG,MAAM,MAAM,GAAG,CAAC,CAAC,EAAG,QAAO;AACtE,WAAO,GAAG;AAAA,MAAM,CAAC,MACf,WAAY,EAA8B,CAAC,GAAI,EAA8B,CAAC,CAAC;AAAA,IACjF;AAAA,EACF;AAEA,SAAO;AACT;AAGO,SAAS,UAAU,IAAoB;AAC5C,aAAO,8BAAQ,uBAAK,YAAY,GAAG,UAAU,GAAG,GAAG,MAAM,GAAG,CAAC,CAAC;AAChE;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,125 @@
+/** The languages a case may be skipped for, and that a runner may report. */
+type Language = "php" | "node" | "rust" | "python" | "go";
+interface ImplementationRef {
+    language: Language;
+    package: string;
+    symbol?: string;
+}
+interface SuiteContract {
+    summary: string;
+    function?: string;
+    functions?: Record<string, string>;
+    runShape?: Record<string, unknown>;
+    /** Whose behaviour the goldens were taken from. */
+    reference?: Language;
+    referenceNote?: string;
+    implementations: ImplementationRef[];
+}
+interface SuiteManifest {
+    suite: string;
+    title: string;
+    since: string;
+    /**
+     * `table` — one `cases.json` whose rows are the cases. For pure functions.
+     * `directory` — `cases/<id>/` holding input and expected artifacts. For
+     * capabilities that emit files, where an expectation is a tree of bytes and
+     * cannot live in a JSON cell.
+     */
+    caseFormat: "table" | "directory";
+    cases?: string;
+    contract: SuiteContract;
+    normalisation?: {
+        ignoreAttributes?: string[];
+        orderInsensitive?: string[];
+        whitespace?: "preserve" | "collapse-between-elements";
+        newline?: "lf" | "crlf" | "preserve";
+    };
+    notes?: string[];
+}
+interface ConformanceCase {
+    id: string;
+    title: string;
+    since: string;
+    tags?: string[];
+    /** Which of the suite's functions this case exercises. */
+    fn?: string;
+    input: Record<string, unknown>;
+    expected: unknown;
+    /**
+     * The only sanctioned way not to run a case. Keyed by language, valued with a
+     * REASON that may not be empty — and every runner prints these.
+     */
+    skip?: Partial<Record<Language, string>>;
+    notes?: string;
+}
+interface Suite {
+    manifest: SuiteManifest;
+    cases: ConformanceCase[];
+}
+interface CaseResult {
+    id: string;
+    title: string;
+    status: "pass" | "fail" | "skip";
+    /** Present when skipped — always non-empty, because an empty reason is a load error. */
+    reason?: string;
+    expected?: unknown;
+    actual?: unknown;
+}
+interface RunSummary {
+    suite: string;
+    language: Language;
+    /** The suite version the results were produced against. Printed, not inferred. */
+    suiteVersion: string;
+    passed: number;
+    failed: number;
+    skipped: number;
+    results: CaseResult[];
+    ok: boolean;
+}
+
+/** The suite collection's own version — the thing a runner must print. */
+declare function suiteVersion(): string;
+/** Every suite id present, e.g. `["shared/decimal", "shared/satisfies-range", …]`. */
+declare function listSuites(): string[];
+/** Load one suite's manifest and cases. Throws rather than returning a partial. */
+declare function loadSuite(id: string): Suite;
+/**
+ * Load a suite from an explicit root.
+ *
+ * Exported so the load-time guards below can be tested against a throwaway
+ * fixture tree, rather than a test re-implementing them. A guard asserted by a
+ * copy of itself is the failure mode this whole repository exists to stop, and
+ * it would be an embarrassing one to ship here.
+ */
+declare function loadSuiteFrom(root: string, id: string): Suite;
+interface RunOptions {
+    /** Which language is under test — decides which `skip` entries apply. */
+    language: Language;
+    /**
+     * Compare a produced value with the expected one. Defaults to a
+     * canonicalising deep equality: object keys sorted, arrays order-sensitive.
+     */
+    equals?: (actual: unknown, expected: unknown) => boolean;
+}
+/**
+ * Run one implementation against a table suite.
+ *
+ * `impl` receives the case and returns the value to compare. Throwing is a
+ * failure, not a crash — a case that blows up is data about the implementation.
+ */
+declare function runTable(suiteId: string, impl: (c: ConformanceCase) => unknown, options: RunOptions): RunSummary;
+/**
+ * A summary a CI log can be read from — including every skip, by name and
+ * reason.
+ *
+ * Skips are printed unconditionally and never folded into a count. "3 skipped"
+ * in a log is indistinguishable from full coverage at a glance, which is how a
+ * suite stops meaning anything without anyone deciding that it should.
+ */
+declare function formatSummary(summary: RunSummary): string;
+/** Order-sensitive for arrays, order-insensitive for object keys. */
+declare function deepEquals(a: unknown, b: unknown): boolean;
+/** Absolute path to a suite's directory — for runners that read artifacts. */
+declare function suitePath(id: string): string;
+
+export { type CaseResult, type ConformanceCase, type ImplementationRef, type Language, type RunOptions, type RunSummary, type Suite, type SuiteContract, type SuiteManifest, deepEquals, formatSummary, listSuites, loadSuite, loadSuiteFrom, runTable, suitePath, suiteVersion };

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+/** The languages a case may be skipped for, and that a runner may report. */
+type Language = "php" | "node" | "rust" | "python" | "go";
+interface ImplementationRef {
+    language: Language;
+    package: string;
+    symbol?: string;
+}
+interface SuiteContract {
+    summary: string;
+    function?: string;
+    functions?: Record<string, string>;
+    runShape?: Record<string, unknown>;
+    /** Whose behaviour the goldens were taken from. */
+    reference?: Language;
+    referenceNote?: string;
+    implementations: ImplementationRef[];
+}
+interface SuiteManifest {
+    suite: string;
+    title: string;
+    since: string;
+    /**
+     * `table` — one `cases.json` whose rows are the cases. For pure functions.
+     * `directory` — `cases/<id>/` holding input and expected artifacts. For
+     * capabilities that emit files, where an expectation is a tree of bytes and
+     * cannot live in a JSON cell.
+     */
+    caseFormat: "table" | "directory";
+    cases?: string;
+    contract: SuiteContract;
+    normalisation?: {
+        ignoreAttributes?: string[];
+        orderInsensitive?: string[];
+        whitespace?: "preserve" | "collapse-between-elements";
+        newline?: "lf" | "crlf" | "preserve";
+    };
+    notes?: string[];
+}
+interface ConformanceCase {
+    id: string;
+    title: string;
+    since: string;
+    tags?: string[];
+    /** Which of the suite's functions this case exercises. */
+    fn?: string;
+    input: Record<string, unknown>;
+    expected: unknown;
+    /**
+     * The only sanctioned way not to run a case. Keyed by language, valued with a
+     * REASON that may not be empty — and every runner prints these.
+     */
+    skip?: Partial<Record<Language, string>>;
+    notes?: string;
+}
+interface Suite {
+    manifest: SuiteManifest;
+    cases: ConformanceCase[];
+}
+interface CaseResult {
+    id: string;
+    title: string;
+    status: "pass" | "fail" | "skip";
+    /** Present when skipped — always non-empty, because an empty reason is a load error. */
+    reason?: string;
+    expected?: unknown;
+    actual?: unknown;
+}
+interface RunSummary {
+    suite: string;
+    language: Language;
+    /** The suite version the results were produced against. Printed, not inferred. */
+    suiteVersion: string;
+    passed: number;
+    failed: number;
+    skipped: number;
+    results: CaseResult[];
+    ok: boolean;
+}
+
+/** The suite collection's own version — the thing a runner must print. */
+declare function suiteVersion(): string;
+/** Every suite id present, e.g. `["shared/decimal", "shared/satisfies-range", …]`. */
+declare function listSuites(): string[];
+/** Load one suite's manifest and cases. Throws rather than returning a partial. */
+declare function loadSuite(id: string): Suite;
+/**
+ * Load a suite from an explicit root.
+ *
+ * Exported so the load-time guards below can be tested against a throwaway
+ * fixture tree, rather than a test re-implementing them. A guard asserted by a
+ * copy of itself is the failure mode this whole repository exists to stop, and
+ * it would be an embarrassing one to ship here.
+ */
+declare function loadSuiteFrom(root: string, id: string): Suite;
+interface RunOptions {
+    /** Which language is under test — decides which `skip` entries apply. */
+    language: Language;
+    /**
+     * Compare a produced value with the expected one. Defaults to a
+     * canonicalising deep equality: object keys sorted, arrays order-sensitive.
+     */
+    equals?: (actual: unknown, expected: unknown) => boolean;
+}
+/**
+ * Run one implementation against a table suite.
+ *
+ * `impl` receives the case and returns the value to compare. Throwing is a
+ * failure, not a crash — a case that blows up is data about the implementation.
+ */
+declare function runTable(suiteId: string, impl: (c: ConformanceCase) => unknown, options: RunOptions): RunSummary;
+/**
+ * A summary a CI log can be read from — including every skip, by name and
+ * reason.
+ *
+ * Skips are printed unconditionally and never folded into a count. "3 skipped"
+ * in a log is indistinguishable from full coverage at a glance, which is how a
+ * suite stops meaning anything without anyone deciding that it should.
+ */
+declare function formatSummary(summary: RunSummary): string;
+/** Order-sensitive for arrays, order-insensitive for object keys. */
+declare function deepEquals(a: unknown, b: unknown): boolean;
+/** Absolute path to a suite's directory — for runners that read artifacts. */
+declare function suitePath(id: string): string;
+
+export { type CaseResult, type ConformanceCase, type ImplementationRef, type Language, type RunOptions, type RunSummary, type Suite, type SuiteContract, type SuiteManifest, deepEquals, formatSummary, listSuites, loadSuite, loadSuiteFrom, runTable, suitePath, suiteVersion };