parseman 0.36.0 → 0.37.0

package/dist/oracle/corpus.d.ts

@@ -0,0 +1,32 @@
+import type { CorpusEntry } from './identity.ts';
+export type LoadCorpusOptions = {
+    /** Ids are relative to this directory. Required — see the note above. */
+    base: string;
+    /** Directories to walk, relative to `base` (or absolute). */
+    roots: readonly string[];
+    /** File extensions to include, with the dot: `['.less', '.css']`. */
+    extensions: readonly string[];
+    /**
+     * Skip files larger than this. A handful of enormous generated fixtures can
+     * dominate the runtime of a gate meant to be run on every edit.
+     */
+    maxBytes?: number;
+    /**
+     * Directories never descended into. An entry with no `/` matches a directory
+     * NAME anywhere; an entry containing `/` matches a path suffix, in POSIX form,
+     * relative to the root being walked — so `node_modules/.cache` skips the cache
+     * without skipping the package tree around it.
+     */
+    ignoreDirs?: readonly string[];
+    /** Tolerate a root that does not exist, reporting it in `missingRoots`. */
+    allowMissingRoots?: boolean;
+};
+export type LoadedCorpus = {
+    entries: CorpusEntry[];
+    /** Roots that did not resolve. Non-empty only with `allowMissingRoots`. */
+    missingRoots: string[];
+    /** Files skipped for exceeding `maxBytes`, by id. */
+    skippedLarge: string[];
+};
+export declare function loadCorpus(options: LoadCorpusOptions): LoadedCorpus;
+//# sourceMappingURL=corpus.d.ts.map

package/dist/oracle/corpus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus.d.ts","sourceRoot":"","sources":["../../src/oracle/corpus.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ,6DAA6D;IAC7D,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,qEAAqE;IACrE,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,WAAW,EAAE,CAAA;IACtB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,qDAAqD;IACrD,YAAY,EAAE,MAAM,EAAE,CAAA;CACvB,CAAA;AAID,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,YAAY,CAgHnE"}

package/dist/oracle/digest.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Bump when the token grammar below changes in a way that alters output for any
+ * input. It is a coarse, human-readable companion to the behavioural harness
+ * digest — the harness digest is what actually enforces this, but a reader
+ * comparing two reports should not have to diff hex to see that the format moved.
+ */
+export declare const DIGEST_FORMAT = 1;
+/**
+ * The canonical token string for a value. Exported because a moved digest is
+ * only actionable if you can see WHAT moved: diff two canonical strings and the
+ * answer is a line, not a hex mismatch.
+ */
+export declare function canonicalize(value: unknown): string;
+/** Full 64-hex sha256 of a string. */
+export declare function hash(payload: string): string;
+/**
+ * Per-entry fingerprint width. 64 bits over any realistic corpus is far below
+ * the collision floor, and a report a human has to read stays readable.
+ */
+export declare const FINGERPRINT_HEX = 16;
+//# sourceMappingURL=digest.d.ts.map

package/dist/oracle/digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.d.ts","sourceRoot":"","sources":["../../src/oracle/digest.ts"],"names":[],"mappings":"AAsDA;;;;;GAKG;AACH,eAAO,MAAM,aAAa,IAAI,CAAA;AAyG9B;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAInD;AAED,sCAAsC;AACtC,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,KAAK,CAAA"}

package/dist/oracle/identity.d.ts

@@ -0,0 +1,117 @@
+/**
+ * One parse entry point under test.
+ *
+ * Declare EVERY shipped surface, not just the one you are editing. A refactor
+ * that touches one grammar should move neither, and the untouched surface is a
+ * free control: if it moves too, the harness or the corpus moved, not the rule
+ * you edited.
+ */
+export type Surface = {
+    /** Stable identifier. Renaming a surface changes its aggregate, deliberately. */
+    name: string;
+    /** Called once per corpus entry. May return anything, and may throw. */
+    parse: (source: string, id: string) => unknown;
+};
+export type CorpusEntry = {
+    /**
+     * Stable, RELATIVE identifier — a path relative to a base, not an absolute
+     * one. An absolute path makes the digest depend on the checkout directory,
+     * which means two machines can never agree.
+     */
+    id: string;
+    source: string;
+};
+export type SurfaceReport = {
+    name: string;
+    /** sha256 over every entry's fingerprint, in id order. The gate. */
+    aggregate: string;
+    /** How many entries threw. Expected to be non-zero; expected not to MOVE. */
+    threw: number;
+};
+export type IdentityReport = {
+    format: number;
+    /** Behavioural fingerprint of the harness that produced this report. */
+    harness: string;
+    entries: number;
+    surfaces: SurfaceReport[];
+    /** entry id → surface name → 16-hex fingerprint. Diff this to localise a move. */
+    perEntry: Record<string, Record<string, string>>;
+};
+export type DigestOptions = {
+    /**
+     * Project a thrown value into something hashable. The default keeps an Error's
+     * `name` and `message`.
+     *
+     * Override when your messages embed anything machine-specific — an absolute
+     * path, a wall-clock time, a memory address. Those make a digest that cannot
+     * be compared across machines, and the symptom is a gate that fails for
+     * everyone except its author.
+     */
+    projectError?: (thrown: unknown, id: string, surface: string) => unknown;
+    /**
+     * How many entries to re-parse to prove the grammar is deterministic. Sampled
+     * evenly across the corpus, not from the front. `0` disables the check; do that
+     * only if you have another reason to trust it.
+     */
+    determinismSample?: number;
+};
+/**
+ * Run every surface over every entry and produce the report.
+ *
+ * The corpus is sorted by id, so the aggregate does not depend on the order the
+ * caller happened to list files in. The aggregate covers the ids as well as the
+ * fingerprints, so a corpus that quietly SHRANK — a root that stopped resolving,
+ * a glob that stopped matching — moves the aggregate instead of producing a
+ * smaller, greener gate. {@link compareReports} then tells you it was the corpus.
+ */
+export declare function digestCorpus(surfaces: readonly Surface[], corpus: readonly CorpusEntry[], options?: DigestOptions): IdentityReport;
+export type SurfaceComparison = {
+    name: string;
+    before: string | null;
+    after: string | null;
+    equal: boolean;
+    /** Entry ids whose fingerprint moved on this surface. Empty when equal. */
+    moved: string[];
+    beforeThrew: number | null;
+    afterThrew: number | null;
+};
+export type IdentityComparison = {
+    /**
+     * `identical` — output-neutral, the refactor is accepted.
+     * `moved` — the output changed; this is not a refactor.
+     * `incomparable` — the two reports cannot be compared at all. Never a pass.
+     */
+    verdict: 'identical' | 'moved' | 'incomparable';
+    reason: string | null;
+    addedEntries: string[];
+    removedEntries: string[];
+    surfaces: SurfaceComparison[];
+};
+/**
+ * Compare two reports.
+ *
+ * Refuses — `incomparable`, with a reason — when the two were not produced by the
+ * same harness over comparable inputs. That is the whole point: the failure mode
+ * this guards against is a harness change that quietly re-baselines every recorded
+ * digest, and the only defence is that mismatched provenance can never come out
+ * as a verdict about the grammar.
+ *
+ * A corpus that gained or lost entries is reported but is NOT by itself
+ * incomparable — the surviving entries still carry a real signal, and telling you
+ * "1 entry disappeared, the other 4,300 are unchanged" is more useful than
+ * refusing. The verdict still reflects the difference.
+ */
+export declare function compareReports(before: IdentityReport, after: IdentityReport): IdentityComparison;
+/** Human-readable rendering of a comparison, for a CLI or a CI log. */
+export declare function formatComparison(c: IdentityComparison, options?: {
+    maxMoved?: number;
+}): string;
+/**
+ * Behavioural fingerprint of this harness, embedded in every report it produces.
+ *
+ * Parseman's suite pins this to a literal. If you change the projection, that
+ * test fails and the constant has to be updated in the same diff — which is the
+ * point. There is no quiet edit here.
+ */
+export declare const HARNESS_DIGEST: string;
+//# sourceMappingURL=identity.d.ts.map

package/dist/oracle/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/oracle/identity.ts"],"names":[],"mappings":"AA0DA;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAA;CAC/C,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAA;IACjB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,aAAa,EAAE,CAAA;IACzB,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACjD,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAA;IACxE;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B,CAAA;AAyBD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,OAAO,GAAE,aAAkB,GAC1B,cAAc,CAmDhB;AAyBD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,KAAK,EAAE,OAAO,CAAA;IACd,2EAA2E;IAC3E,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;OAIG;IACH,OAAO,EAAE,WAAW,GAAG,OAAO,GAAG,cAAc,CAAA;IAC/C,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,QAAQ,EAAE,iBAAiB,EAAE,CAAA;CAC9B,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,GAAG,kBAAkB,CA0ChG;AAMD,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,kBAAkB,EAAE,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CA0BnG;AA+ED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,MAKzB,CAAA"}

package/dist/oracle/index.cjs

@@ -0,0 +1,423 @@
+"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/oracle/index.ts
+var oracle_exports = {};
+__export(oracle_exports, {
+  DIGEST_FORMAT: () => DIGEST_FORMAT,
+  HARNESS_DIGEST: () => HARNESS_DIGEST,
+  canonicalize: () => canonicalize,
+  compareReports: () => compareReports,
+  digestCorpus: () => digestCorpus,
+  formatComparison: () => formatComparison,
+  loadCorpus: () => loadCorpus
+});
+module.exports = __toCommonJS(oracle_exports);
+
+// src/oracle/digest.ts
+var import_node_crypto = require("node:crypto");
+var DIGEST_FORMAT = 1;
+var str = (s) => JSON.stringify(s);
+var tagOf = (v) => {
+  const ctor = v.constructor;
+  return typeof ctor === "function" && typeof ctor.name === "string" ? ctor.name : "";
+};
+function writeScalar(v, out) {
+  switch (typeof v) {
+    case "undefined":
+      out.push("u");
+      return;
+    case "boolean":
+      out.push(v ? "T" : "F");
+      return;
+    case "bigint":
+      out.push(`n${v}`);
+      return;
+    case "string":
+      out.push(`s${str(v)}`);
+      return;
+    // TODO(oracle-callable-identity): a callable is projected by NAME and a symbol by
+    // DESCRIPTION, so two distinct same-named functions — or two same-description
+    // symbols — digest identically, and a change between them reads as "identical".
+    // This is a real hole in a tool whose whole claim is paranoia, and it is left open
+    // deliberately: closing it means either hashing `Function.prototype.toString()`,
+    // which flips the digest on a comment edit inside a builder, or REFUSING to digest
+    // any value carrying a callable, which rejects legitimate ASTs that park a callback
+    // on a node. Both are worse than the hole for some caller, and picking between them
+    // is a product decision, not a bug fix. Documented under "What it is not" in
+    // `docs/guide/identity-oracle.md` so no reader infers a guarantee that is not here.
+    case "symbol":
+      out.push(`y${str(v.description ?? "")}`);
+      return;
+    case "function":
+      out.push(`f${str(v.name)}`);
+      return;
+    case "number":
+      if (Number.isNaN(v)) out.push("#nan");
+      else if (v === Number.POSITIVE_INFINITY) out.push("#inf");
+      else if (v === Number.NEGATIVE_INFINITY) out.push("#-inf");
+      else if (Object.is(v, -0)) out.push("#-0");
+      else out.push(`#${v}`);
+      return;
+    default:
+      out.push("z");
+  }
+}
+function write(v, path, depth, out) {
+  if (typeof v !== "object" || v === null) {
+    writeScalar(v, out);
+    return;
+  }
+  const seenAt = path.get(v);
+  if (seenAt !== void 0) {
+    out.push(`^${depth - seenAt}`);
+    return;
+  }
+  path.set(v, depth);
+  if (Array.isArray(v)) {
+    out.push("[");
+    for (const item of v) write(item, path, depth + 1, out);
+    out.push("]");
+  } else if (v instanceof Map) {
+    out.push("M");
+    for (const [k, val] of v) {
+      write(k, path, depth + 1, out);
+      write(val, path, depth + 1, out);
+    }
+    out.push("}");
+  } else if (v instanceof Set) {
+    out.push("S");
+    for (const item of v) write(item, path, depth + 1, out);
+    out.push("}");
+  } else if (v instanceof Date) {
+    out.push(`D${v.getTime()}`);
+  } else if (v instanceof RegExp) {
+    out.push(`R${str(v.source)}${str(v.flags)}`);
+  } else {
+    const tag = tagOf(v);
+    out.push(`{${str(tag === "Object" ? "" : tag)}`);
+    for (const k of Object.keys(v).sort()) {
+      out.push(`k${str(k)}`);
+      write(v[k], path, depth + 1, out);
+    }
+    out.push("}");
+  }
+  path.delete(v);
+}
+function canonicalize(value) {
+  const out = [];
+  write(value, /* @__PURE__ */ new Map(), 0, out);
+  return out.join("\0");
+}
+function hash(payload2) {
+  return (0, import_node_crypto.createHash)("sha256").update(payload2).digest("hex");
+}
+var FINGERPRINT_HEX = 16;
+
+// src/oracle/identity.ts
+var defaultProjectError = (thrown) => thrown instanceof Error ? { name: thrown.name, message: thrown.message } : { thrown };
+function payload(surface, entry, options) {
+  try {
+    return { text: `OK:${canonicalize(surface.parse(entry.source, entry.id))}`, threw: false };
+  } catch (thrown) {
+    const project = options.projectError ?? defaultProjectError;
+    return { text: `ERR:${canonicalize(project(thrown, entry.id, surface.name))}`, threw: true };
+  }
+}
+var fingerprint = (text) => hash(text).slice(0, FINGERPRINT_HEX);
+function digestCorpus(surfaces, corpus, options = {}) {
+  if (surfaces.length === 0) throw new Error("digestCorpus: no surfaces \u2014 there is nothing to compare.");
+  const names = /* @__PURE__ */ new Set();
+  for (const s of surfaces) {
+    if (names.has(s.name)) throw new Error(`digestCorpus: duplicate surface name ${JSON.stringify(s.name)}.`);
+    names.add(s.name);
+  }
+  const entries = [...corpus].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+  for (let n = 1; n < entries.length; n++) {
+    if (entries[n].id === entries[n - 1].id) {
+      throw new Error(`digestCorpus: duplicate corpus id ${JSON.stringify(entries[n].id)}.`);
+    }
+  }
+  const perEntry = {};
+  const threw = {};
+  const texts = [];
+  for (const s of surfaces) threw[s.name] = 0;
+  for (const entry of entries) {
+    const row = {};
+    const rowTexts = /* @__PURE__ */ new Map();
+    for (const s of surfaces) {
+      const result = payload(s, entry, options);
+      if (result.threw) threw[s.name]++;
+      row[s.name] = fingerprint(result.text);
+      rowTexts.set(s.name, result.text);
+    }
+    perEntry[entry.id] = row;
+    texts.push(rowTexts);
+  }
+  verifyDeterminism(surfaces, entries, texts, options);
+  return {
+    format: DIGEST_FORMAT,
+    harness: HARNESS_DIGEST,
+    entries: entries.length,
+    surfaces: surfaces.map((s) => ({
+      name: s.name,
+      // The surface NAME is inside its own aggregate: two surfaces that happen
+      // to agree on every entry must still have distinct aggregates, or a
+      // report that swapped them would compare equal.
+      aggregate: hash(
+        [`surface:${s.name}`, ...entries.map((e) => `${e.id}:${perEntry[e.id][s.name]}`)].join("\n")
+      ),
+      threw: threw[s.name]
+    })),
+    perEntry
+  };
+}
+function verifyDeterminism(surfaces, entries, texts, options) {
+  const want = options.determinismSample ?? 32;
+  if (want <= 0 || entries.length === 0) return;
+  const stride = Math.max(1, Math.floor(entries.length / Math.min(want, entries.length)));
+  for (let n = 0; n < entries.length; n += stride) {
+    const entry = entries[n];
+    for (const s of surfaces) {
+      if (payload(s, entry, options).text === texts[n].get(s.name)) continue;
+      throw new Error(
+        `digestCorpus: surface ${JSON.stringify(s.name)} is NOT DETERMINISTIC on ${JSON.stringify(entry.id)} \u2014 two parses of the same source produced different output. Every digest from this grammar would move on its own, so a comparison against it cannot mean anything. Usual causes: a timestamp or counter in the output, iteration over a keyed-by-object Map, or a node carrying a reference to mutable shared state.`
+      );
+    }
+  }
+}
+function compareReports(before, after) {
+  if (before.harness !== after.harness) {
+    return incomparable(
+      `harness drift: reports were produced by DIFFERENT versions of the identity harness (${before.harness.slice(0, 12)}\u2026 vs ${after.harness.slice(0, 12)}\u2026). Their digests are not comparable, and treating them as such would either invent a regression or hide one. Re-run BOTH sides on one harness.`
+    );
+  }
+  if (before.format !== after.format) {
+    return incomparable(`digest format ${before.format} vs ${after.format} \u2014 re-run both sides on one version.`);
+  }
+  const beforeIds = new Set(Object.keys(before.perEntry));
+  const afterIds = new Set(Object.keys(after.perEntry));
+  const addedEntries = [...afterIds].filter((id) => !beforeIds.has(id)).sort();
+  const removedEntries = [...beforeIds].filter((id) => !afterIds.has(id)).sort();
+  const shared = [...beforeIds].filter((id) => afterIds.has(id)).sort();
+  const byName = /* @__PURE__ */ new Map();
+  for (const s of before.surfaces) byName.set(s.name, { ...byName.get(s.name), before: s });
+  for (const s of after.surfaces) byName.set(s.name, { ...byName.get(s.name), after: s });
+  const surfaces = [...byName.entries()].sort(([a], [b]) => a < b ? -1 : 1).map(([name, pair]) => {
+    const moved = pair.before && pair.after ? shared.filter((id) => before.perEntry[id][name] !== after.perEntry[id][name]) : [];
+    return {
+      name,
+      before: pair.before?.aggregate ?? null,
+      after: pair.after?.aggregate ?? null,
+      equal: pair.before !== void 0 && pair.after !== void 0 && pair.before.aggregate === pair.after.aggregate,
+      moved,
+      beforeThrew: pair.before?.threw ?? null,
+      afterThrew: pair.after?.threw ?? null
+    };
+  });
+  const identical = addedEntries.length === 0 && removedEntries.length === 0 && surfaces.every((s) => s.equal);
+  return { verdict: identical ? "identical" : "moved", reason: null, addedEntries, removedEntries, surfaces };
+}
+function incomparable(reason) {
+  return { verdict: "incomparable", reason, addedEntries: [], removedEntries: [], surfaces: [] };
+}
+function formatComparison(c, options = {}) {
+  if (c.verdict === "incomparable") return `INCOMPARABLE \u2014 ${c.reason ?? "unknown reason"}`;
+  const max = options.maxMoved ?? 10;
+  const lines = [];
+  for (const s of c.surfaces) {
+    if (s.before === null) lines.push(`  + surface ${s.name} (added)`);
+    else if (s.after === null) lines.push(`  - surface ${s.name} (removed)`);
+    else if (s.equal) lines.push(`  = ${s.name}  ${s.before.slice(0, 16)}\u2026  threw=${s.afterThrew}`);
+    else {
+      lines.push(
+        `  ! ${s.name}  ${s.before.slice(0, 16)}\u2026 -> ${s.after.slice(0, 16)}\u2026  threw ${s.beforeThrew} -> ${s.afterThrew}  (${s.moved.length} entries moved)`
+      );
+      for (const id of s.moved.slice(0, max)) lines.push(`      ${id}`);
+      if (s.moved.length > max) lines.push(`      \u2026 and ${s.moved.length - max} more`);
+    }
+  }
+  if (c.addedEntries.length > 0) lines.push(`  corpus GAINED ${c.addedEntries.length} entries`);
+  if (c.removedEntries.length > 0) {
+    lines.push(
+      `  corpus LOST ${c.removedEntries.length} entries \u2014 a differential over a SMALLER corpus is a weaker gate, not a passing one`
+    );
+  }
+  return [c.verdict === "identical" ? "IDENTICAL \u2014 output-neutral" : "MOVED \u2014 this is not a refactor", ...lines].join("\n");
+}
+function canaryReport() {
+  class Tagged {
+    x;
+    constructor(x) {
+      this.x = x;
+    }
+  }
+  const shared = { shared: true };
+  const cyclic = { name: "root" };
+  cyclic.self = cyclic;
+  cyclic.child = { up: cyclic };
+  const values = {
+    "a/scalars": [0, -0, 1.5, Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY, 10n, true, false, null],
+    "b/absent": [{ a: void 0 }, {}, { a: null }, [void 0], []],
+    "c/key-order": [{ a: 1, b: 2 }, { b: 2, a: 1 }],
+    "d/collections": [/* @__PURE__ */ new Map([["k", 1], ["j", 2]]), /* @__PURE__ */ new Set([1, 2]), /* @__PURE__ */ new Date(0), /ab+c/giu],
+    "e/tagged": [new Tagged(1), { x: 1 }],
+    "f/sharing": { left: shared, right: shared },
+    "g/cycle": cyclic,
+    "h/text": ["", "a\0b", "a b", '"quoted"', "\\"],
+    "i/callable": [function named() {
+    }, /* @__PURE__ */ Symbol("sym")]
+  };
+  const surfaces = [
+    { name: "value", parse: (_source, id) => values[id] },
+    {
+      name: "thrower",
+      parse: (_source, id) => {
+        if (id === "a/scalars") throw new TypeError("canary");
+        if (id === "b/absent") throw "a bare string";
+        return { id };
+      }
+    }
+  ];
+  const corpus = Object.keys(values).map((id) => ({ id, source: id }));
+  const perEntry = {};
+  const threw = { value: 0, thrower: 0 };
+  for (const entry of [...corpus].sort((a, b) => a.id < b.id ? -1 : 1)) {
+    const row = {};
+    for (const s of surfaces) {
+      const result = payload(s, entry, {});
+      if (result.threw) threw[s.name]++;
+      row[s.name] = fingerprint(result.text);
+    }
+    perEntry[entry.id] = row;
+  }
+  const ids = Object.keys(perEntry).sort();
+  return {
+    format: DIGEST_FORMAT,
+    harness: "",
+    entries: ids.length,
+    surfaces: surfaces.map((s) => ({
+      name: s.name,
+      aggregate: hash([`surface:${s.name}`, ...ids.map((id) => `${id}:${perEntry[id][s.name]}`)].join("\n")),
+      threw: threw[s.name]
+    })),
+    perEntry
+  };
+}
+var HARNESS_DIGEST = (() => {
+  const canary = canaryReport();
+  return hash(
+    [`format:${DIGEST_FORMAT}`, ...canary.surfaces.map((s) => `${s.name}:${s.aggregate}:${s.threw}`)].join("\n")
+  );
+})();
+
+// src/oracle/corpus.ts
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+var DEFAULT_IGNORE = [".git", "node_modules/.cache"];
+function loadCorpus(options) {
+  const base = (0, import_node_path.resolve)(options.base);
+  const ignoreDirs = options.ignoreDirs ?? DEFAULT_IGNORE;
+  const ignoreNames = new Set(ignoreDirs.filter((d) => !d.includes("/")));
+  const ignorePaths = ignoreDirs.filter((d) => d.includes("/")).map((d) => d.replace(/^\.?\/+/, "").replace(/\/+$/, ""));
+  const maxBytes = options.maxBytes ?? Number.POSITIVE_INFINITY;
+  const exts = new Set(options.extensions.map((e) => e.toLowerCase()));
+  const missingRoots = [];
+  const skippedLarge = [];
+  const files = /* @__PURE__ */ new Map();
+  const isIgnored = (name, relFromRoot) => {
+    if (ignoreNames.has(name)) return true;
+    return ignorePaths.some((p) => relFromRoot === p || relFromRoot.endsWith(`/${p}`));
+  };
+  const walk = (dir, root, visited) => {
+    let real;
+    try {
+      real = (0, import_node_fs.realpathSync)(dir);
+    } catch {
+      return;
+    }
+    if (visited.has(real)) return;
+    visited.add(real);
+    for (const item of (0, import_node_fs.readdirSync)(dir, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : 1)) {
+      const full = (0, import_node_path.join)(dir, item.name);
+      if (isIgnored(item.name, (0, import_node_path.relative)(root, full).split(import_node_path.sep).join("/"))) continue;
+      let isDir = item.isDirectory();
+      let isFile = item.isFile();
+      let size = 0;
+      if (item.isSymbolicLink() || !isDir && !isFile) {
+        try {
+          const st = (0, import_node_fs.statSync)(full);
+          isDir = st.isDirectory();
+          isFile = st.isFile();
+          size = st.size;
+        } catch {
+          continue;
+        }
+      }
+      if (isDir) {
+        walk(full, root, visited);
+        continue;
+      }
+      if (!isFile) continue;
+      const dot = item.name.lastIndexOf(".");
+      if (dot < 0 || !exts.has(item.name.slice(dot).toLowerCase())) continue;
+      if (size === 0) {
+        try {
+          size = (0, import_node_fs.statSync)(full).size;
+        } catch {
+          continue;
+        }
+      }
+      if (size > maxBytes) {
+        skippedLarge.push(idOf(base, full));
+        continue;
+      }
+      let realFile;
+      try {
+        realFile = (0, import_node_fs.realpathSync)(full);
+      } catch {
+        continue;
+      }
+      const id = idOf(base, full);
+      const existing = files.get(realFile);
+      if (existing === void 0 || id < existing) files.set(realFile, id);
+    }
+  };
+  for (const root of options.roots) {
+    const full = (0, import_node_path.resolve)(base, root);
+    try {
+      if (!(0, import_node_fs.statSync)(full).isDirectory()) throw new Error("not a directory");
+    } catch {
+      if (!options.allowMissingRoots) {
+        throw new Error(
+          `loadCorpus: root ${JSON.stringify(root)} does not resolve to a directory (${full}). A corpus that quietly shrank produces a different aggregate that looks like a grammar change. Fix the root, or pass allowMissingRoots and record \`missingRoots\` alongside the digest.`
+        );
+      }
+      missingRoots.push(root);
+      continue;
+    }
+    walk(full, full, /* @__PURE__ */ new Set());
+  }
+  const entries = [...files.values()].sort().map((id) => ({ id, source: (0, import_node_fs.readFileSync)((0, import_node_path.resolve)(base, id), "utf8") }));
+  return { entries, missingRoots, skippedLarge: skippedLarge.sort() };
+}
+function idOf(base, full) {
+  return (0, import_node_path.relative)(base, full).split(import_node_path.sep).join("/");
+}
+//# sourceMappingURL=index.cjs.map