parseman 0.44.0 → 0.46.0

package/dist/oracle/index.js

@@ -1,11 +1,113 @@
 // src/oracle/digest.ts
 import { createHash } from "node:crypto";
 var DIGEST_FORMAT = 1;
+var SEPARATOR = String.fromCharCode(0);
 var str = (s) => JSON.stringify(s);
 var tagOf = (v) => {
   const ctor = v.constructor;
   return typeof ctor === "function" && typeof ctor.name === "string" ? ctor.name : "";
 };
+var ArraySink = class {
+  tokens = [];
+  push(token) {
+    this.tokens.push(token);
+  }
+};
+var StreamSink = class {
+  target;
+  buffer = [];
+  buffered = 0;
+  started = false;
+  constructor(target) {
+    this.target = target;
+  }
+  /**
+   * Write text that is NOT a canonical token and takes no separator — the
+   * `OK:` / `ERR:` discriminator, which the string form concatenates onto the
+   * front rather than joining.
+   */
+  prefix(text) {
+    if (text === "") return;
+    this.buffer.push(text);
+    this.buffered += text.length;
+  }
+  push(token) {
+    if (this.started) {
+      this.buffer.push(SEPARATOR);
+      this.buffered += 1;
+    } else {
+      this.started = true;
+    }
+    this.buffer.push(token);
+    this.buffered += token.length;
+    if (this.buffered >= FLUSH_CHARS) this.flush();
+  }
+  flush() {
+    if (this.buffer.length === 0) return;
+    this.target.update(this.buffer.join(""));
+    this.buffer = [];
+    this.buffered = 0;
+  }
+};
+var FLUSH_CHARS = 1 << 16;
+var CanonicalBudgetError = class extends Error {
+  name = "CanonicalBudgetError";
+  constructor(budget, projected) {
+    super(
+      `canonicalize: exceeded ${budget} visits. The value is not merely large \u2014 it is almost certainly a DAG being unrolled. This projection writes a shared subtree once per PATH that reaches it (see "Sharing is not a cycle"), so a node referenced from two places at each of d levels costs 2^d. Deduplicate the shared structure, or raise \`maxVisits\` if the value really is that big.` + (projected === void 0 ? "" : ` Refused EARLY: the walk was projected to visit ${projected} objects, so it could not have finished under this budget however long it ran. See {@link projectVisits}.`)
+    );
+  }
+};
+var DEFAULT_MAX_VISITS = 1e8;
+var EXPANSION_PROBE_VISITS = 1e6;
+var EXPANSION_PROBE_NODES = 2e5;
+var EXPANSION_PROBE_MARGIN = 4;
+function projectVisits(root) {
+  const memo = /* @__PURE__ */ new Map();
+  const path = /* @__PURE__ */ new Set();
+  let nodes = 0;
+  let usable = true;
+  const count = (v) => {
+    if (typeof v !== "object" || v === null) return 0;
+    if (path.has(v)) {
+      usable = false;
+      return 1;
+    }
+    const done = memo.get(v);
+    if (done !== void 0) return done;
+    if (++nodes > EXPANSION_PROBE_NODES) {
+      usable = false;
+      return 1;
+    }
+    path.add(v);
+    let total = 1;
+    if (Array.isArray(v)) {
+      for (const item of v) total += count(item);
+    } else if (v instanceof Map) {
+      for (const [k, val] of v) total += count(k) + count(val);
+    } else if (v instanceof Set) {
+      for (const item of v) total += count(item);
+    } else if (!(v instanceof Date) && !(v instanceof RegExp)) {
+      for (const k of Object.keys(v)) total += count(v[k]);
+    }
+    path.delete(v);
+    memo.set(v, total);
+    return total;
+  };
+  try {
+    const total = count(root);
+    return usable ? total : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function probeExpansion(state) {
+  state.probeAt = -1;
+  const projected = projectVisits(state.root);
+  if (projected !== void 0 && projected / EXPANSION_PROBE_MARGIN > state.budget) {
+    throw new CanonicalBudgetError(state.budget, projected);
+  }
+}
 function writeScalar(v, out) {
   switch (typeof v) {
     case "undefined":
@@ -47,11 +149,15 @@ function writeScalar(v, out) {
       out.push("z");
   }
 }
-function write(v, path, depth, out) {
+function write(v, state, depth) {
+  const out = state.sink;
   if (typeof v !== "object" || v === null) {
     writeScalar(v, out);
     return;
   }
+  if (--state.visits < 0) throw new CanonicalBudgetError(state.budget);
+  if (state.visits === state.probeAt) probeExpansion(state);
+  const path = state.path;
   const seenAt = path.get(v);
   if (seenAt !== void 0) {
     out.push(`^${depth - seenAt}`);
@@ -60,18 +166,18 @@ function write(v, path, depth, out) {
   path.set(v, depth);
   if (Array.isArray(v)) {
     out.push("[");
-    for (const item of v) write(item, path, depth + 1, out);
+    for (const item of v) write(item, state, depth + 1);
     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);
+      write(k, state, depth + 1);
+      write(val, state, depth + 1);
     }
     out.push("}");
   } else if (v instanceof Set) {
     out.push("S");
-    for (const item of v) write(item, path, depth + 1, out);
+    for (const item of v) write(item, state, depth + 1);
     out.push("}");
   } else if (v instanceof Date) {
     out.push(`D${v.getTime()}`);
@@ -82,319 +188,44 @@ function write(v, path, depth, out) {
     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);
+      write(v[k], state, depth + 1);
     }
     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 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.`
+function newState(sink, options, root) {
+  const budget = options?.maxVisits ?? DEFAULT_MAX_VISITS;
+  if (!Number.isSafeInteger(budget) || budget < 0) {
+    throw new RangeError(
+      `canonicalize: maxVisits must be a non-negative safe integer, received ${String(budget)}. A non-finite or fractional budget does not raise the ceiling, it REMOVES it \u2014 the budget is spent with \`--visits < 0\`, which is false forever for NaN and never reached for Infinity \u2014 so the walk this bounds would run unbounded into the OOM the budget exists to prevent.`
     );
   }
-  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 };
+  const probeAt = budget >= EXPANSION_PROBE_VISITS ? budget - EXPANSION_PROBE_VISITS : -1;
+  return { path: /* @__PURE__ */ new Map(), sink, budget, root, visits: budget, probeAt };
 }
-function incomparable(reason) {
-  return { verdict: "incomparable", reason, addedEntries: [], removedEntries: [], surfaces: [] };
+function canonicalize(value, options) {
+  const out = new ArraySink();
+  write(value, newState(out, options, value), 0);
+  return out.tokens.join(SEPARATOR);
 }
-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
-import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { join, relative, resolve, sep } from "node:path";
-var DEFAULT_IGNORE = [".git", "node_modules/.cache"];
-function loadCorpus(options) {
-  const base = 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 = realpathSync(dir);
-    } catch {
-      return;
-    }
-    if (visited.has(real)) return;
-    visited.add(real);
-    for (const item of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : 1)) {
-      const full = join(dir, item.name);
-      if (isIgnored(item.name, relative(root, full).split(sep).join("/"))) continue;
-      let isDir = item.isDirectory();
-      let isFile = item.isFile();
-      let size = 0;
-      if (item.isSymbolicLink() || !isDir && !isFile) {
-        try {
-          const st = 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 = statSync(full).size;
-        } catch {
-          continue;
-        }
-      }
-      if (size > maxBytes) {
-        skippedLarge.push(idOf(base, full));
-        continue;
-      }
-      let realFile;
-      try {
-        realFile = 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 = resolve(base, root);
-    try {
-      if (!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: readFileSync(resolve(base, id), "utf8") }));
-  return { entries, missingRoots, skippedLarge: skippedLarge.sort() };
+function digestInto(target, value, prefix = "", options) {
+  const sink = new StreamSink(target);
+  sink.prefix(prefix);
+  write(value, newState(sink, options, value), 0);
+  sink.flush();
 }
-function idOf(base, full) {
-  return relative(base, full).split(sep).join("/");
+function digestValue(value, prefix = "", options) {
+  const sha = createHash("sha256");
+  digestInto(sha, value, prefix, options);
+  return sha.digest("hex");
 }
 export {
+  CanonicalBudgetError,
+  DEFAULT_MAX_VISITS,
   DIGEST_FORMAT,
-  HARNESS_DIGEST,
   canonicalize,
-  compareReports,
-  digestCorpus,
-  formatComparison,
-  loadCorpus
+  digestInto,
+  digestValue
 };
 //# sourceMappingURL=index.js.map