parseman 0.14.1 → 0.15.0

package/dist/plugin/index.cjs

@@ -69,6 +69,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 fs2 = empty();
+  for (const p of parsers) {
+    fs2 = union(fs2, p._meta.firstSet);
+    if (!matchesEmpty(p)) return fs2;
+  }
+  return fs2;
+}
 function mergeRanges(ranges) {
   if (ranges.length === 0) return [];
   const sorted = [...ranges].sort((a, b) => a.lo - b.lo);
@@ -917,16 +974,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) {
@@ -946,17 +1006,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 }
       };
     }
@@ -997,20 +1058,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 } };
     }
   };
 }
@@ -1020,22 +1082,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 } };
     }
   };
 }
@@ -1113,6 +1176,90 @@ function sepBy(combinator, separator) {
   };
 }
 
+// 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/not.ts
 function not(combinator) {
   const meta = {
@@ -3251,6 +3398,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 };
@@ -3457,7 +3605,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;
@@ -3548,19 +3697,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++;
@@ -3591,13 +3739,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");
@@ -4207,6 +4355,7 @@ function ruleDependencies(ruleMap) {
   return deps;
 }
 function compile(combinator, mapFnSources) {
+  markUnusedValues(combinator);
   const ctx = {
     vars: 0,
     indent: 1,
@@ -4289,7 +4438,16 @@ 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 compileRuleMap(ruleMap) {
+  for (const [, rule] of ruleMap) markUnusedValues(rule);
   const ctx = {
     vars: 0,
     indent: 1,
@@ -4314,7 +4472,8 @@ function compileRuleMap(ruleMap) {
   const seenNames = /* @__PURE__ */ new Map();
   const ruleNames = /* @__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 = seenNames.get(base) ?? 0;
     seenNames.set(base, n + 1);
     ruleNames.set(rule, n === 0 ? base : `${base}$${n}`);
@@ -4365,6 +4524,7 @@ function compileRuleMap(ruleMap) {
 }
 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;
@@ -4395,13 +4555,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}`;
@@ -4425,7 +4587,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);
           }
@@ -4494,12 +4657,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,
@@ -4569,7 +4746,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 fs2 = p.firstSets?.get(k);
+    if (fs2) finalFS.set(k, fs2);
+  }
+  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 fs2 = finalFS.get(name);
+      if (!fs2 || fs2.kind === "any" || fs2.kind === "empty") return "true";
+      return `(${firstSetCond(codevar, fs2)})`;
+    }
+  );
   const env = {};
   for (const p of contributing) {
     if (p.mfFns.length) env[`${p.ns}mf`] = p.mfFns;
@@ -5349,7 +5542,7 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
   const nsFor = (label2) => `_${(0, import_node_crypto.createHash)("sha1").update(`${id}#${label2}`).digest("hex").slice(0, 8)}_`;
   const serializePieces = (p) => {
     const mapLit = (m) => `new Map([${[...m].map(([k, v2]) => `[${JSON.stringify(k)}, ${JSON.stringify(v2)}]`).join(", ")}])`;
-    return `{ ns: ${JSON.stringify(p.ns)}, keys: ${JSON.stringify(p.keys)}, prelude: ${JSON.stringify(p.prelude)}, ruleFns: ${mapLit(p.ruleFns)}, wrappers: ${mapLit(p.wrappers)}, deps: ${mapLit(p.deps)}, needsEmptyTl: ${p.needsEmptyTl}, needsCollator: ${p.needsCollator}, mfFns: [], buildFns: [] }`;
+    return `{ ns: ${JSON.stringify(p.ns)}, keys: ${JSON.stringify(p.keys)}, prelude: ${JSON.stringify(p.prelude)}, ruleFns: ${mapLit(p.ruleFns)}, wrappers: ${mapLit(p.wrappers)}, firstSets: ${mapLit(p.firstSets)}, deps: ${mapLit(p.deps)}, needsEmptyTl: ${p.needsEmptyTl}, needsCollator: ${p.needsCollator}, mfFns: [], buildFns: [] }`;
   };
   const serializeList = (list) => `[${list.map(serializePieces).join(", ")}]`;
   const withCarriedPieces = (grammarExpr, list) => `/* @__PURE__ */ (() => { const _g = ${grammarExpr}; Object.defineProperty(_g, Symbol.for('parseman.composedPieces'), { value: ${serializeList(list)} }); return _g })()`;