parseman 0.44.0 → 0.45.0

package/dist/spec/index.cjs

@@ -82,8 +82,9 @@ function matchesEmpty(p, seen = /* @__PURE__ */ new Set(), resolve) {
       return d.value.length === 0;
     case "keywords":
       return false;
+    // The routed token itself is the selector's match, never empty; a fallback can be.
     case "routed":
-      return false;
+      return d.fallback === void 0 ? false : me(d.fallback);
     case "regex":
       try {
         const m = new RegExp(d.source).exec("");
@@ -885,10 +886,11 @@ function childrenOf(def) {
       return [def.main, def.skipped];
     case "scanTo":
       return [def.sentinel, ...def.skip];
+    case "routed":
+      return def.fallback ? [def.fallback] : [];
     case "literal":
     case "regex":
     case "keywords":
-    case "routed":
     case "guard":
     case "lazy":
     case "unknown":
@@ -1197,8 +1199,11 @@ function derive(c, seen) {
     case "not":
     case "peek":
       return deriveExpected2(def.parser);
+    // A bare routed() can only fail as "there is no routed token here". With a
+    // fallback, THAT is the branch that can fail, so its expectations are the useful
+    // ones — the routed path either succeeds or is not taken.
     case "routed":
-      return ["routed()"];
+      return def.fallback === void 0 ? ["routed()"] : deriveExpected2(def.fallback);
     case "lazy": {
       const name = c._ruleName;
       if (seen.has(c)) return name ? [name] : [];
@@ -1813,7 +1818,7 @@ function detectStrategy(parsers) {
 function bareLeadingTermKey(term) {
   const d = term._def;
   if (d.tag === "literal" && !d.caseInsensitive) return `L:${d.value}`;
-  if (d.tag === "regex") return `R:${d.source}\0${d.flags}`;
+  if (d.tag === "regex") return `R:${JSON.stringify([d.source, d.flags])}`;
   return null;
 }
 function detectSharedPrefix(parsers) {
@@ -2666,6 +2671,37 @@ function scanTo(sentinel, { skip: skip2, raw = false, orEOF = false } = {}) {
   };
 }
 
+// src/compiler/degradation.ts
+function formatDegradation(d) {
+  return `[parseman] degraded [${d.code}] ${d.where}: ${d.subject} \u2014 ${d.fellBackTo}; otherwise ${d.otherwise}`;
+}
+var _sinks = [];
+function resolveDegradationLevel(explicit) {
+  if (explicit !== void 0) return explicit;
+  const env = typeof process !== "undefined" ? process.env?.PARSEMAN_DEGRADATION : void 0;
+  if (env === "off" || env === "warn" || env === "error") return env;
+  return "warn";
+}
+function degradationKey(d) {
+  return JSON.stringify([d.code, d.where, d.subject]);
+}
+function recordDegradation(d) {
+  const level = resolveDegradationLevel();
+  if (level === "off") return;
+  const key = degradationKey(d);
+  const sink = _sinks[_sinks.length - 1];
+  if (sink) {
+    if (!sink.has(key)) sink.set(key, d);
+    return;
+  }
+  if (_immediate.has(key)) return;
+  _immediate.add(key);
+  if (level === "error") throw new Error(`parseman: degraded compilation path
+${formatDegradation(d)}`);
+  console.warn(formatDegradation(d));
+}
+var _immediate = /* @__PURE__ */ new Set();
+
 // src/cst/trivia-entries.ts
 var EMPTY_INDICES = Object.freeze([]);
 var EMPTY_GAPS = Object.freeze([]);
@@ -2695,45 +2731,183 @@ var SELECTED_ROOT_FINISH = [
 function cstOutputHost(build) {
   return build?._parsemanCstOutput === true;
 }
-var PARAM_LIST_RE = (
-  // (params) => ...   |   function name?(params) ...   |   single-ident arrow `x => ...`
-  /^(?:function\b[^(]*\(([^)]*)\)|\(([^)]*)\)\s*=>|([A-Za-z_$][\w$]*)\s*=>)/
-);
-var CONFIRMABLE_PARAM_RE = /^[A-Za-z_$][\w$]*\s*\??\s*(?::[^,=]+)?$/;
+var SINGLE_IDENT_ARROW_RE = /^[A-Za-z_$][\w$]*\s*=>/;
+var PARAM_LIST_OPEN_RE = /^(?:function\b[^(]*)?\(/;
+var NATIVE_CODE_RE = /\{\s*\[native code\]\s*\}/;
+var PARAM_HEAD_RE = /^[A-Za-z_$][\w$]*\s*\??\s*/;
 function confirmedBuildArity(src) {
   const s = src.trim();
-  const m = PARAM_LIST_RE.exec(s);
-  if (!m) return null;
-  if (m[3] !== void 0) return 1;
-  const inner = (m[1] ?? m[2] ?? "").trim();
-  if (inner === "") return 0;
-  const parts = inner.split(",");
+  if (NATIVE_CODE_RE.test(s)) return null;
+  if (/\barguments\b/.test(s)) return null;
+  if (SINGLE_IDENT_ARROW_RE.test(s)) return 1;
+  const inner = paramListText(s);
+  if (inner === null) return null;
+  if (inner.trim() === "") return 0;
+  const parts = splitTopLevel(inner);
+  if (parts === null) return null;
   for (const part of parts) {
-    if (!CONFIRMABLE_PARAM_RE.test(part.trim())) return null;
+    if (!isConfirmableParam(part.trim())) return null;
   }
-  if (/\barguments\b/.test(s)) return null;
   return parts.length;
 }
+function paramListText(s) {
+  const open = PARAM_LIST_OPEN_RE.exec(s);
+  if (!open) return null;
+  const start = open[0].length;
+  const end = matchingParen(s, start);
+  if (end === null) return null;
+  if (!s.startsWith("function") && !/^\s*=>/.test(s.slice(end + 1))) return null;
+  return s.slice(start, end);
+}
+function matchingParen(s, start) {
+  let depth = 0;
+  for (let i = start; i < s.length; i++) {
+    const c = s[i];
+    if (c === '"' || c === "'" || c === "`") {
+      const close = skipString(s, i);
+      if (close === null) return null;
+      i = close;
+      continue;
+    }
+    if (c === "(" || c === "[" || c === "{") depth++;
+    else if (c === "]" || c === "}") {
+      if (--depth < 0) return null;
+    } else if (c === ")") {
+      if (depth === 0) return i;
+      depth--;
+    }
+  }
+  return null;
+}
+function skipString(s, open) {
+  const quote2 = s[open];
+  for (let i = open + 1; i < s.length; i++) {
+    if (s[i] === "\\") {
+      i++;
+      continue;
+    }
+    if (s[i] === quote2) return i;
+  }
+  return null;
+}
+function splitTopLevel(inner) {
+  const parts = [];
+  let depth = 0;
+  let angle = 0;
+  let last = 0;
+  for (let i = 0; i < inner.length; i++) {
+    const c = inner[i];
+    if (c === "=" && inner[i + 1] === ">") {
+      i++;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === "`") {
+      const close = skipString(inner, i);
+      if (close === null) return null;
+      i = close;
+      continue;
+    }
+    if (c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ")" || c === "]" || c === "}") {
+      if (--depth < 0) return null;
+    } else if (c === "<") angle++;
+    else if (c === ">") {
+      if (--angle < 0) return null;
+    } else if (c === "," && depth === 0 && angle === 0) {
+      parts.push(inner.slice(last, i));
+      last = i + 1;
+    }
+  }
+  if (depth !== 0 || angle !== 0) return null;
+  parts.push(inner.slice(last));
+  return parts;
+}
+function isConfirmableParam(part) {
+  const head = PARAM_HEAD_RE.exec(part);
+  if (!head) return false;
+  const rest = part.slice(head[0].length);
+  if (rest === "") return true;
+  if (rest[0] !== ":") return false;
+  return !hasDefaultAssign(rest.slice(1));
+}
+function hasDefaultAssign(annotation) {
+  for (let i = 0; i < annotation.length; i++) {
+    if (annotation[i] !== "=") continue;
+    if (annotation[i + 1] === ">" || annotation[i + 1] === "=") {
+      i++;
+      continue;
+    }
+    const prev = annotation[i - 1];
+    if (prev === "<" || prev === ">" || prev === "!" || prev === "=") continue;
+    return true;
+  }
+  return false;
+}
+function buildAnalysisSrc(def) {
+  return def.buildSigSrc ?? def.buildSrc ?? def.build.toString();
+}
+var RESOLVER_REASONS = {
+  "rest-parameter": "its parameter list uses a rest parameter, so the declared arity is unbounded",
+  "arguments": "its body references `arguments`",
+  "reassigned": "the binding it names is reassigned, so the function read here is not decidable",
+  "not-a-function": "the binding it names is not a function declaration",
+  "unresolved-import": "its module could not be resolved or parsed",
+  "not-found": "the name did not resolve to any binding",
+  "computed": "it is a computed expression",
+  "foreign-source": "it is named inside an imported factory, whose offsets the entry-file resolver cannot index"
+};
+function unconfirmableReason(def, src) {
+  const declared = def.buildArityUnresolved;
+  if (declared !== void 0 && RESOLVER_REASONS[declared]) return RESOLVER_REASONS[declared];
+  const s = src.trim();
+  const params = s.slice(0, s.indexOf(")") + 1);
+  if (params.includes("...")) return RESOLVER_REASONS["rest-parameter"];
+  if (/\barguments\b/.test(s)) return RESOLVER_REASONS["arguments"];
+  if (/^[A-Za-z_$][\w$]*(\s*\.\s*[A-Za-z_$][\w$]*)?$/.test(s)) {
+    return "it names a binding this build could not resolve to a function declaration";
+  }
+  return "its parameter list could not be parsed";
+}
+function confirmedArityForDef(def) {
+  if (def.buildArity !== void 0) return def.buildArity;
+  const src = buildAnalysisSrc(def);
+  const arity = confirmedBuildArity(src);
+  if (arity !== null) return arity;
+  const subject = `build reducer \`${(def.buildSrc ?? "<runtime fn>").trim().split("\n")[0].slice(0, 60)}\``;
+  recordDegradation({
+    code: "build-arity-unconfirmed",
+    severity: "warn",
+    where: `node("${def.type ?? "<inferred>"}")`,
+    subject,
+    fellBackTo: `could not confirm its declared arity \u2014 ${unconfirmableReason(def, src)} \u2014 so this node captures children, fields and raw children, logs trivia, and clones \`_ctx.state\` on every match`,
+    otherwise: "only the tiers the reducer actually declares would be captured (arity >= 1 children, >= 2 fields, >= 4 raw, >= 5 trivia, >= 6 state). Declare it with `node(..., { buildArity: n })` if it cannot be derived"
+  });
+  return null;
+}
 function buildReadsTrivia(def) {
   if (!def.build) return true;
-  const src = def.buildSrc ?? def.build.toString();
-  const arity = confirmedBuildArity(src);
+  const arity = confirmedArityForDef(def);
   if (arity === null) return true;
   return arity >= 5;
 }
 function buildReadsState(def) {
   if (!def.build) return true;
-  const src = def.buildSrc ?? def.build.toString();
-  const arity = confirmedBuildArity(src);
+  const arity = confirmedArityForDef(def);
   if (arity === null) return true;
   return arity >= 6;
 }
 
+// src/compiler/inline-build.ts
+var ANN = String.raw`\s*\??\s*(?::[^,)=]+)?`;
+var ANY_P = String.raw`\w+${ANN}`;
+var MK_BUILD_RE = new RegExp(
+  String.raw`^\(\s*(\w+)${ANN}\s*,\s*${ANY_P}\s*,\s*(\w+)${ANN}\s*,\s*(\w+)${ANN}\s*,\s*(\w+)${ANN}\s*\)\s*=>\s*mk\s*\(\s*(['"])([^'"]+)\5\s*,\s*\1\s*,\s*\3\s*,\s*\2\s*,\s*\4\s*\)\s*$`
+);
+
 // src/compiler/fields.ts
 function buildReadsFields(def) {
   if (!def.build) return true;
-  const src = def.buildSrc ?? def.build.toString();
-  const arity = confirmedBuildArity(src);
+  const arity = confirmedArityForDef(def);
   if (arity === null) return true;
   return arity >= 2;
 }
@@ -2984,17 +3158,21 @@ function when(key, parser2, opts = {}) {
 function otherwise(parser2) {
   return { kind: "otherwise", parser: parser2, usesRouted: parserUsesRouted(parser2) };
 }
-function routed() {
+function routed(fallback) {
   return {
     _tag: "routed",
-    _meta: { firstSet: { kind: "any" }, canMatchNewline: false, isTrivia: false },
-    _def: { tag: "routed" },
+    _meta: {
+      // The routed token is whatever the selector matched, so the first set stays
+      // `any` even with a fallback — `any` already subsumes the fallback's.
+      firstSet: { kind: "any" },
+      canMatchNewline: fallback?._meta.canMatchNewline ?? false,
+      isTrivia: false
+    },
+    _def: fallback === void 0 ? { tag: "routed" } : { tag: "routed", fallback },
     parse(_input, pos, ctx) {
       const item = ctx._routed;
-      if (item === void 0) {
-        return { ok: false, expected: ["routed()"], span: { start: pos, end: pos } };
-      }
-      if (pos !== item.span.start) {
+      if (item === void 0 || pos !== item.span.start) {
+        if (fallback !== void 0) return fallback.parse(_input, pos, ctx);
         return { ok: false, expected: ["routed()"], span: { start: pos, end: pos } };
       }
       if (cstCaptureActive(ctx)) {
@@ -3197,6 +3375,13 @@ function isCstChild(value) {
 function missingInferredType() {
   throw new Error('node(): inferred node type requires a rules() key; pass node("Type", parser) outside rules()');
 }
+function normalizeBuildArity(arity) {
+  if (arity === void 0) return void 0;
+  if (!Number.isInteger(arity) || arity < 0 || arity > 6) {
+    throw new Error("node() buildArity must be an integer 0..6 (children, fields, span, rawChildren, triviaLog, state)");
+  }
+  return arity;
+}
 function normalizeProject(project) {
   if (project === void 0) return void 0;
   if (!Number.isInteger(project) || project < 0) {
@@ -3232,13 +3417,14 @@ function node(typeOrCombinator, combinatorOrBuild, buildOrOpts, maybeOpts) {
   const captureTrivia = opts?.captureTrivia === true;
   const trailingTrivia = opts?.trailingTrivia === true;
   const tags = opts?.tags;
+  const buildArity = normalizeBuildArity(opts?.buildArity);
   if (unwrap && collapse) {
     throw new Error("node() options cannot set both unwrap and collapse");
   }
   if (project !== void 0 && (unwrap || collapse)) {
     throw new Error("node() options cannot combine project with unwrap or collapse");
   }
-  const def = unwrap || collapse || project !== void 0 || captureTrivia || trailingTrivia || tags !== void 0 && tags.length > 0 ? { ...baseDef, ...unwrap ? { unwrap: true } : {}, ...collapse ? { collapse: true } : {}, ...project !== void 0 ? { project } : {}, ...captureTrivia ? { captureTrivia: true } : {}, ...trailingTrivia ? { trailingTrivia: true } : {}, ...tags !== void 0 && tags.length > 0 ? { tags } : {} } : baseDef;
+  const def = unwrap || collapse || project !== void 0 || captureTrivia || trailingTrivia || buildArity !== void 0 || tags !== void 0 && tags.length > 0 ? { ...baseDef, ...unwrap ? { unwrap: true } : {}, ...collapse ? { collapse: true } : {}, ...project !== void 0 ? { project } : {}, ...captureTrivia ? { captureTrivia: true } : {}, ...trailingTrivia ? { trailingTrivia: true } : {}, ...buildArity !== void 0 ? { buildArity } : {}, ...tags !== void 0 && tags.length > 0 ? { tags } : {} } : baseDef;
   const capturesTrivia = captureTrivia || trailingTrivia || (build ? buildReadsTrivia(def) : project === void 0);
   const clonesState = build ? buildReadsState(def) : project === void 0;
   const hasOwnFields = parserHasOwnFields(combinator);
@@ -3284,7 +3470,7 @@ function node(typeOrCombinator, combinatorOrBuild, buildOrOpts, maybeOpts) {
       const cstOutput = cstOutputHost(ctx.build);
       const span = ctx.trackLines ? annotateSpanFromLineContext(r.span, ctx) : r.span;
       const hostState = clonesState ? st : ctx.state !== void 0 ? Object.assign({}, ctx.state) : void 0;
-      const built = unwrap && children.length === 1 ? unwrapChild(children[0]) : collapse && children.length === 1 ? children[0] : !build && project === void 0 && ctx.build?._parsemanCstCollapse && children.length === 1 && rawChildren.length === 1 && ctx.build._parsemanCstCollapse(nodeType, children[0], children, rawChildren) ? children[0] : project !== void 0 ? cstOutput && ctx.build ? ctx.build(nodeType, children, fields, span, rawChildren, triviaLog, hostState, tags) : projectChild(children, project, nodeType) : build ? cstOutput && ctx.build ? ctx.build(nodeType, children, fields, span, rawChildren, triviaLog, hostState, tags) : build(children, fields, span, rawChildren, triviaLog, st) : ctx.build ? ctx.build(nodeType, children, fields, span, rawChildren, triviaLog, st, tags) : { _tag: "node", type: nodeType, span: ctx.trackLines ? { ...span } : { start: r.span.start, end: r.span.end }, state: st ?? null, children };
+      const built = unwrap && children.length === 1 ? unwrapChild(children[0]) : collapse && children.length === 1 ? children[0] : (cstOutput || !build && project === void 0) && ctx.build?._parsemanCstCollapse && children.length === 1 && rawChildren.length === 1 && ctx.build._parsemanCstCollapse(nodeType, children[0], children, rawChildren) ? children[0] : project !== void 0 ? cstOutput && ctx.build ? ctx.build(nodeType, children, fields, span, rawChildren, triviaLog, hostState, tags) : projectChild(children, project, nodeType) : build ? cstOutput && ctx.build ? ctx.build(nodeType, children, fields, span, rawChildren, triviaLog, hostState, tags) : build(children, fields, span, rawChildren, triviaLog, st) : ctx.build ? ctx.build(nodeType, children, fields, span, rawChildren, triviaLog, st, tags) : { _tag: "node", type: nodeType, span: ctx.trackLines ? { ...span } : { start: r.span.start, end: r.span.end }, state: st ?? null, children };
       const rawEntry = isCstChild(built) ? built : { _tag: "leaf", value: typeof built === "string" ? built : typeof built === "object" && built !== null ? input.slice(r.span.start, r.span.end) : "", span };
       if (saved.buf !== void 0 || saved.ch !== void 0) {
         pushCstChild(ctx, built, rawEntry);
@@ -3439,7 +3625,7 @@ function evalRuleMapIR(ir) {
     l._def.fnSrc = src;
     return l;
   };
-  const _nd = (type, child, src, opts, staticError) => {
+  const _nd = (type, child, src, opts, staticError, sigSrc) => {
     if (staticError !== void 0 && staticError.length > 0) {
       throw new Error(`IR direct node builder for ${type} must be macro-static and self-contained; unsupported binding(s): ${staticError.join(", ")}`);
     }
@@ -3448,6 +3634,7 @@ function evalRuleMapIR(ir) {
     }), opts);
     n._def.buildSrc = src;
     if (staticError !== void 0) n._def.buildStaticError = staticError;
+    if (sigSrc !== void 0) n._def.buildSigSrc = sigSrc;
     return n;
   };
   const _gch = (items) => {
@@ -3780,7 +3967,7 @@ var Builder = class {
       case "peek":
         return { kind: "peek", item: this.walk(def.parser) };
       case "routed":
-        return { kind: "empty" };
+        return def.fallback === void 0 ? { kind: "empty" } : this.walk(def.fallback);
       // Transparent semantic wrappers — render the inner syntax.
       case "transform":
       case "token":