parseman 0.14.0 → 0.15.0

package/dist/index.cjs

@@ -124,6 +124,63 @@ function any() {
 function empty() {
   return { kind: "empty" };
 }
+function matchesEmpty(p, seen = /* @__PURE__ */ new Set()) {
+  if (seen.has(p)) return true;
+  seen.add(p);
+  const me = (c) => matchesEmpty(c, seen);
+  const d = p._def;
+  switch (d.tag) {
+    case "literal":
+      return d.value.length === 0;
+    case "keywords":
+      return false;
+    case "regex":
+      try {
+        const m = new RegExp(d.source).exec("");
+        return m != null && m[0] === "";
+      } catch {
+        return true;
+      }
+    case "many":
+    case "optional":
+    case "not":
+      return true;
+    // zero repetitions / absent / lookahead
+    case "oneOrMore":
+      return me(d.parser);
+    case "sequence":
+      return d.parsers.every(me);
+    case "choice":
+      return d.parsers.some(me);
+    case "transform":
+    case "label":
+    case "trivia":
+    case "expect":
+    case "withCtx":
+    case "node":
+    case "grammar":
+    case "recover":
+      return me(d.parser);
+    case "skip":
+      return me(d.main);
+    case "lazy":
+      try {
+        return me(d.thunk());
+      } catch {
+        return true;
+      }
+    default:
+      return true;
+  }
+}
+function sequenceFirstSet(parsers) {
+  let fs = empty();
+  for (const p of parsers) {
+    fs = union(fs, p._meta.firstSet);
+    if (!matchesEmpty(p)) return fs;
+  }
+  return fs;
+}
 function mergeRanges(ranges) {
   if (ranges.length === 0) return [];
   const sorted = [...ranges].sort((a, b) => a.lo - b.lo);
@@ -945,16 +1002,19 @@ function scanTrivia(input, cur, ctx) {
 // src/combinators/sequence.ts
 function sequence(...parsers) {
   const meta = {
-    firstSet: parsers[0]?._meta.firstSet ?? empty(),
+    // Union through the nullable prefix — a leading optional()/many() lets a later
+    // term's first char start the sequence. Just `parsers[0]` under-approximates.
+    firstSet: sequenceFirstSet(parsers),
     canMatchNewline: parsers.some((p) => p._meta.canMatchNewline),
     isTrivia: false
   };
+  const def = { tag: "sequence", parsers };
   return {
     _tag: "sequence",
     _meta: meta,
-    _def: { tag: "sequence", parsers },
+    _def: def,
     parse(input, pos, ctx) {
-      const values = [];
+      const values = def.valueUnused ? void 0 : [];
       let cur = pos;
       for (let i = 0; i < parsers.length; i++) {
         if (ctx.trivia && i > 0) {
@@ -974,17 +1034,18 @@ function sequence(...parsers) {
           } else {
             rollbackTrivia(ctx, mark);
           }
-          values.push(result2.value);
+          if (values !== void 0) values.push(result2.value);
           continue;
         }
         const result = parsers[i].parse(input, cur, ctx);
         if (!result.ok) return result;
-        values.push(result.value);
+        if (values !== void 0) values.push(result.value);
         cur = result.span.end;
       }
       return {
         ok: true,
-        value: values,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        value: values ?? void 0,
         span: { start: pos, end: cur }
       };
     }
@@ -1025,20 +1086,21 @@ function many(combinator) {
     canMatchNewline: combinator._meta.canMatchNewline,
     isTrivia: false
   };
+  const def = { tag: "many", parser: combinator, min: 0 };
   return {
     _tag: "many",
     _meta: meta,
-    _def: { tag: "many", parser: combinator, min: 0 },
+    _def: def,
     parse(input, pos, ctx) {
-      const values = [];
+      const values = def.valueUnused ? void 0 : [];
       let cur = pos;
       while (cur < input.length) {
         const item = repItem(combinator, input, cur, ctx);
         if (item === "stop" || "fail" in item) break;
-        values.push(item.value);
+        if (values !== void 0) values.push(item.value);
         cur = item.end;
       }
-      return { ok: true, value: values, span: { start: pos, end: cur } };
+      return { ok: true, value: values ?? void 0, span: { start: pos, end: cur } };
     }
   };
 }
@@ -1048,22 +1110,23 @@ function oneOrMore(combinator) {
     canMatchNewline: combinator._meta.canMatchNewline,
     isTrivia: false
   };
+  const def = { tag: "oneOrMore", parser: combinator, min: 1 };
   return {
     _tag: "oneOrMore",
     _meta: meta,
-    _def: { tag: "oneOrMore", parser: combinator, min: 1 },
+    _def: def,
     parse(input, pos, ctx) {
       const first = combinator.parse(input, pos, ctx);
       if (!first.ok) return first;
-      const values = [first.value];
+      const values = def.valueUnused ? void 0 : [first.value];
       let cur = first.span.end;
       while (cur < input.length) {
         const item = repItem(combinator, input, cur, ctx);
         if (item === "stop" || "fail" in item) break;
-        values.push(item.value);
+        if (values !== void 0) values.push(item.value);
         cur = item.end;
       }
-      return { ok: true, value: values, span: { start: pos, end: cur } };
+      return { ok: true, value: values ?? void 0, span: { start: pos, end: cur } };
     }
   };
 }
@@ -1171,6 +1234,90 @@ function ref() {
   return slot;
 }
 
+// src/compiler/value-usage.ts
+function markUnusedValues(root) {
+  const seenConsumed = /* @__PURE__ */ new WeakSet();
+  const seenUnconsumed = /* @__PURE__ */ new WeakSet();
+  const mark = (def, consumed) => {
+    if (consumed) def.valueUnused = false;
+    else if (def.valueUnused !== false) def.valueUnused = true;
+  };
+  const visit = (c, consumed) => {
+    const seen = consumed ? seenConsumed : seenUnconsumed;
+    if (seen.has(c)) return;
+    seen.add(c);
+    const def = c._def;
+    switch (def.tag) {
+      case "many":
+      case "oneOrMore":
+        mark(def, consumed);
+        visit(def.parser, consumed);
+        return;
+      case "optional":
+        visit(def.parser, consumed);
+        return;
+      case "sequence":
+        mark(def, consumed);
+        for (const p of def.parsers) visit(p, consumed);
+        return;
+      case "choice":
+        for (const p of def.parsers) visit(p, consumed);
+        return;
+      case "node":
+        visit(def.parser, false);
+        return;
+      case "transform":
+        visit(def.parser, true);
+        return;
+      case "skip":
+        visit(def.main, consumed);
+        visit(def.skipped, false);
+        return;
+      case "sepBy":
+        visit(def.parser, true);
+        visit(def.separator, false);
+        return;
+      case "not":
+        visit(def.parser, false);
+        return;
+      case "grammar":
+        visit(def.parser, consumed);
+        if (def.triviaParser) visit(def.triviaParser, false);
+        return;
+      case "recover":
+        visit(def.parser, consumed);
+        visit(def.sentinel, false);
+        return;
+      case "label":
+      case "trivia":
+      case "withCtx":
+      case "expect":
+        visit(def.parser, consumed);
+        return;
+      case "lazy":
+        return;
+      default:
+        return;
+    }
+  };
+  const resolveRoot = (c) => {
+    const guard2 = /* @__PURE__ */ new Set();
+    let cur = c;
+    while (!guard2.has(cur)) {
+      const d = cur._def;
+      if (d.tag !== "lazy") return cur;
+      guard2.add(cur);
+      try {
+        cur = d.thunk();
+      } catch {
+        return c;
+      }
+    }
+    return cur;
+  };
+  visit(resolveRoot(root), true);
+}
+
 // src/combinators/parser.ts
 function rules(factory) {
   const cache = {};
@@ -1200,6 +1347,9 @@ function rules(factory) {
       cache[key] = parser2;
     }
   }
+  for (const key of Object.keys(definitions)) {
+    markUnusedValues(cache[key]);
+  }
   return cache;
 }
 
@@ -1416,7 +1566,12 @@ function parser(opts, root) {
 function noTrivia(root) {
   return parser({ trivia: null }, root);
 }
+var _analyzed = /* @__PURE__ */ new WeakSet();
 function parse(combinator, input, opts = {}) {
+  if (!_analyzed.has(combinator)) {
+    _analyzed.add(combinator);
+    markUnusedValues(combinator);
+  }
   const trackLines = opts.trackLines ?? false;
   const _errors = opts.recover ? [] : void 0;
   const _probe = opts.recover ? { offset: input.length, best: null } : void 0;
@@ -3373,6 +3528,7 @@ function emitSeqValues(def, ctx, pos) {
 }
 function emitSeq(def, ctx, pos) {
   const { stmts, endVar, valueVars } = emitSeqValues(def, ctx, pos);
+  if (def.valueUnused) return { stmts, valueVar: "undefined", endVar };
   const arrV = v(ctx, "_arr");
   stmts.push(`${ind(ctx)}const ${arrV} = [${valueVars.join(", ")}]`);
   return { stmts, valueVar: arrV, endVar };
@@ -3579,7 +3735,8 @@ function emitFirstMatch(def, ctx, pos) {
     const autoNot = def.autoNot[i];
     const atStart = failsAtStart(p);
     const staticFx = armStaticExpected(ctx, p);
-    const fsGuard = needsFirstSetGuard(p) ? firstSetCond(codeV, p._meta.firstSet) : null;
+    const deferRuleName = ctx.deferFirstSetRefs ? p._ruleName : void 0;
+    const fsGuard = deferRuleName !== void 0 ? `/*@FS:${deferRuleName}:${codeV}@*/true` : needsFirstSetGuard(p) ? firstSetCond(codeV, p._meta.firstSet) : null;
     let gateCond = null;
     if (gate) {
       const gateIdx = ctx.mapFns.length;
@@ -3670,19 +3827,18 @@ function emitLiteralCondition(litVal, pos) {
   return checks.join(" && ");
 }
 function emitMany(def, ctx, pos) {
+  const wantValue = !def.valueUnused;
   const arrV = v(ctx, "_arr");
   const curV = v(ctx, "_cur");
   const stmts = [
-    `${ind(ctx)}const ${arrV} = []`,
+    ...wantValue ? [`${ind(ctx)}const ${arrV} = []`] : [],
     `${ind(ctx)}let ${curV} = ${pos}`
   ];
   if (def.min === 1) {
     const firstR = emit(def.parser, ctx, curV);
     stmts.push(...firstR.stmts);
-    stmts.push(
-      `${ind(ctx)}${arrV}.push(${firstR.valueVar})`,
-      `${ind(ctx)}${curV} = ${firstR.endVar}`
-    );
+    if (wantValue) stmts.push(`${ind(ctx)}${arrV}.push(${firstR.valueVar})`);
+    stmts.push(`${ind(ctx)}${curV} = ${firstR.endVar}`);
   }
   stmts.push(`${ind(ctx)}while (${curV} < input.length) {`);
   ctx.indent++;
@@ -3713,13 +3869,13 @@ function emitMany(def, ctx, pos) {
   const { stmts: iterStmts, okVar: iterOk, valVar: iterVal, endVar: iterEnd } = emitFallible(def.parser, ctx, itemPos, true);
   stmts.push(
     ...iterStmts,
-    `${ind(ctx)}if (!${iterOk} || ${iterEnd} <= ${itemPos}) { ${rollback}break }`,
-    `${ind(ctx)}${arrV}.push(${iterVal})`,
-    `${ind(ctx)}${curV} = ${iterEnd}`
+    `${ind(ctx)}if (!${iterOk} || ${iterEnd} <= ${itemPos}) { ${rollback}break }`
   );
+  if (wantValue) stmts.push(`${ind(ctx)}${arrV}.push(${iterVal})`);
+  stmts.push(`${ind(ctx)}${curV} = ${iterEnd}`);
   ctx.indent--;
   stmts.push(`${ind(ctx)}}`);
-  return { stmts, valueVar: arrV, endVar: curV };
+  return { stmts, valueVar: wantValue ? arrV : "undefined", endVar: curV };
 }
 function emitOptional(def, ctx, pos) {
   const valV = v(ctx, "_opt");
@@ -4329,6 +4485,7 @@ function ruleDependencies(ruleMap) {
   return deps;
 }
 function compile(combinator, mapFnSources) {
+  markUnusedValues(combinator);
   const ctx = {
     vars: 0,
     indent: 1,
@@ -4411,8 +4568,17 @@ function compile(combinator, mapFnSources) {
     }
   };
 }
+var RULE_NAME_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function assertRuleName(name) {
+  if (!RULE_NAME_RE.test(name)) {
+    throw new Error(
+      `parseman: grammar rule name ${JSON.stringify(name)} is not a valid JS identifier. Rule names compile to _r_<Name> functions and dispatch guards \u2014 use letters, digits, _ or $ (and don't start with a digit).`
+    );
+  }
+}
 function compileLinkable(ruleMapArg, ns) {
   if (!ns) throw new Error("compileLinkable: ns must be a non-empty namespace");
+  for (const [, rule] of ruleMapArg) markUnusedValues(rule);
   const ruleMap = ruleMapArg.filter(([, val]) => {
     const d = val._def;
     if (d.tag !== "lazy") return true;
@@ -4443,13 +4609,15 @@ function compileLinkable(ruleMapArg, ns) {
     namedFnDecls: [],
     capturing: ruleMap.some(([, rule]) => hasNodeDef(rule)),
     lazyUsage: analyzeLazyUsageMulti(ruleMap.map(([, rule]) => rule)),
-    ns
+    ns,
+    deferFirstSetRefs: true
   };
   const seen = /* @__PURE__ */ new Map();
   const ruleNames = /* @__PURE__ */ new Map();
   const fnNameToKey = /* @__PURE__ */ new Map();
   for (const [key, rule] of ruleMap) {
-    const base = `_r_${key.replace(/[^A-Za-z0-9_$]/g, "_")}`;
+    assertRuleName(key);
+    const base = `_r_${key}`;
     const n = seen.get(base) ?? 0;
     seen.set(base, n + 1);
     const fn = n === 0 ? base : `${base}$${n}`;
@@ -4473,7 +4641,8 @@ function compileLinkable(ruleMapArg, ns) {
         if (resolved === void 0) {
           const name = p._ruleName;
           if (name && !ctx.namedParsers.has(p)) {
-            const fn = `_r_${name.replace(/[^A-Za-z0-9_$]/g, "_")}`;
+            assertRuleName(name);
+            const fn = `_r_${name}`;
             ruleNames.set(p, fn);
             ctx.namedParsers.set(p, fn);
           }
@@ -4542,12 +4711,26 @@ function compileLinkable(ruleMapArg, ns) {
       `}`
     ].join("\n"));
   }
+  const firstSets = /* @__PURE__ */ new Map();
+  for (const [key, rule] of ruleMap) {
+    let resolved = rule;
+    const d = rule._def;
+    if (d.tag === "lazy") {
+      try {
+        resolved = d.thunk();
+      } catch {
+        resolved = rule;
+      }
+    }
+    firstSets.set(key, canMatchEmptyAtStart(resolved) ? { kind: "any" } : resolved._meta.firstSet);
+  }
   return {
     ns,
     keys: perEntry.map((e) => e.key),
     prelude,
     ruleFns,
     wrappers,
+    firstSets,
     deps: ruleDependencies(ruleMap),
     needsEmptyTl: !!ctx.needsEmptyTl,
     needsCollator: ctx.needsCollator,
@@ -4648,7 +4831,23 @@ function fusedBody(pieces) {
     ...[...winner].map(([k, p]) => p.ruleFns.get(k))
   ];
   const wrapperEntries = [...winner].map(([k, p]) => `${JSON.stringify(k)}: ${p.wrappers.get(k)}`);
-  const body = [...lines, "return {", wrapperEntries.join(",\n"), "}"].join("\n");
+  const rawBody = [...lines, "return {", wrapperEntries.join(",\n"), "}"].join("\n");
+  const finalFS = /* @__PURE__ */ new Map();
+  for (const [k, p] of winner) {
+    const fs = p.firstSets?.get(k);
+    if (fs) finalFS.set(k, fs);
+  }
+  const body = rawBody.replace(
+    // Rule name + code-point var are both JS identifiers (rule names are validated
+    // at compile time — see assertRuleName in codegen), so an identifier class
+    // matches every well-formed placeholder.
+    /\/\*@FS:([A-Za-z0-9_$]+):([A-Za-z0-9_$]+)@\*\/true/g,
+    (_m, name, codevar) => {
+      const fs = finalFS.get(name);
+      if (!fs || fs.kind === "any" || fs.kind === "empty") return "true";
+      return `(${firstSetCond(codevar, fs)})`;
+    }
+  );
   const env = {};
   for (const p of contributing) {
     if (p.mfFns.length) env[`${p.ns}mf`] = p.mfFns;
@@ -5040,6 +5239,11 @@ function parseDoc(registry, rootRule, input, opts = {}) {
 // src/functional/run.ts
 var invoke = (r, input, pos, ctx) => typeof r === "function" ? r(input, pos, ctx) : r.parse(input, pos, ctx);
 function run(entry, input, options = {}) {
+  if (typeof entry !== "function" && typeof entry?.parse !== "function") {
+    throw new TypeError(
+      `run(): start production is ${entry === null ? "null" : typeof entry}, not a rule \u2014 the requested grammar rule does not exist (check the rule name).`
+    );
+  }
   const triviaLog = [];
   const errors = [];
   const ctx = {