parseman 0.50.3 → 0.50.5

package/dist/version.d.ts

@@ -13,5 +13,5 @@
  * Kept in sync with `package.json` by `test/unit/version-sync.test.ts`, which fails
  * the build if this constant drifts from the published version.
  */
-export declare const PARSEMAN_VERSION = "0.50.3";
+export declare const PARSEMAN_VERSION = "0.50.5";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "parseman",
-  "version": "0.50.3",
+  "version": "0.50.5",
   "packageManager": "pnpm@10.15.1",
   "engines": {
     "node": "^20.19.0 || >=22.13.0"
   },
-  "description": "Parser combinators that compile to optimized JavaScript \u2014 use as a library or as a build-time macro",
+  "description": "Parser combinators that compile to optimized JavaScript — use as a library or as a build-time macro",
   "type": "module",
   "sideEffects": false,
   "author": "Matthew Dean <matthew-dean@users.noreply.github.com>",

package/src/combinators/first-set.ts

@@ -63,11 +63,31 @@ export function classifyFinalChoice(
   return { exclusive, firstSets, nullable }
 }
 
-/** The `resolve`-supplied target for an unresolvable NAMED lazy, if any. */
-function resolveNamedRef(p: Combinator<unknown>, resolve: RefResolver | undefined): Combinator<unknown> | undefined {
+/** The compose WINNER a named lazy ref resolves to — the same row the encoder's
+ * `lazy` case calls via `winners`/`scopedRef`. Winner-FIRST resolution is what makes
+ * first-set / nullability analysis AGREE with emission: a base piece's thunk still
+ * closes over its own binding, so a compose OVERRIDE (and any undefined cross-piece
+ * ref) would otherwise be invisible to the gate — the reducer reroutes, the recognizer
+ * does not. `undefined` → no winner; fall back to the thunk. Monolithic: the winner IS
+ * the thunk's target, a no-op. A winner that recurses back to `p` (recursive or
+ * self-alias rule) is caught by the shared `seen` guard → `any`, a sound over-approx. */
+function winnerForRef(p: Combinator<unknown>, resolve: RefResolver | undefined): Combinator<unknown> | undefined {
   if (resolve === undefined) return undefined
   const name = (p as unknown as { _ruleName?: string })._ruleName
-  return name === undefined ? undefined : resolve(name)
+  const w = name === undefined ? undefined : resolve(name)
+  // Skip a winner that merely wraps THIS reference (a transparent rules()/parser()
+  // alias): resolving to it is a self-hop, not an override — matches the encoder's
+  // own `winnerWrapsReference` guard so first-set analysis agrees with emission.
+  if (w === undefined || w === p) return undefined
+  let cur = w
+  for (const seen = new Set<Combinator<unknown>>(); !seen.has(cur); ) {
+    if (cur === p) return undefined
+    seen.add(cur)
+    const cd = cur._def as ParserDef
+    if (cd.tag !== 'grammar' && cd.tag !== 'trivia') return w
+    cur = cd.parser
+  }
+  return w
 }
 
 export function union(a: FirstSet, b: FirstSet): FirstSet {
@@ -190,9 +210,12 @@ function matchesEmptyBody(
     case 'node':
     case 'grammar':
     case 'recover':   return me(d.parser)
-    case 'lazy':
+    case 'lazy': {
+      const w = winnerForRef(p, resolve)
+      if (w !== undefined) return me(w)
       try { return me(d.thunk()) }
-      catch { const t = resolveNamedRef(p, resolve); return t ? me(t) : true }
+      catch { return true }
+    }
     default:          return true          // scanTo / guard / unknown → assume nullable (safe)
   }
 }
@@ -338,9 +361,12 @@ function firstSetBody(
     case 'regex':
     case 'keywords':  return p._meta.firstSet  // terminals: no refs, cached set is exact
     case 'dispatch':  return fs(d.selector)
-    case 'lazy':
+    case 'lazy': {
+      const w = winnerForRef(p, resolve)
+      if (w !== undefined) return fs(w)
       try { return fs(d.thunk()) }
-      catch { const t = resolveNamedRef(p, resolve); return t ? fs(t) : any() }
+      catch { return any() }
+    }
     case 'choice': {
       let out: FirstSet = empty()
       for (const arm of d.parsers) out = union(out, fs(arm))

package/src/compiler/ir-serialize.ts

@@ -321,6 +321,33 @@ class Serializer {
     return c._def.tag === 'lazy' && ruleNameOf(c) !== undefined ? (lazyTarget(c) ?? c) : c
   }
 
+  /**
+   * The child a rule-entry grammar scope should serialize as its body, when that
+   * scope merely WRAPS the rule's own named `lazy` proxy.
+   *
+   * `rules({ trackLines: true }, …)` wraps every rule VALUE — which is that rule's
+   * own named lazy proxy — in a `grammarParser({ trackLines: true })` scope
+   * (`parser.ts:229-242`). `body()` unwraps a BARE lazy entry to its defined target;
+   * a lazy wrapped one level deep by that scope must be unwrapped INSIDE the scope
+   * too. Left wrapped, the inner proxy serializes as a `g[name]` SELF-reference and
+   * the rule's real body is dropped, so it re-lowers to `Name: parser(opts, g.Name)`
+   * — a bodyless self-cycle the table encoder rejects with `alias cycle — lazy (rule
+   * 'Name') encodes to its own recursion trampoline`. This is why the four
+   * `*PositionsGrammar` exports fell back to a runtime `compose()` under trackLines.
+   *
+   * STRICT: only a scope that IS a rule entry (in `localRuleNames`) AND wraps ITS
+   * OWN name unwraps. A scope wrapping another rule's ref (a genuine cross-rule
+   * alias, `Name: parser(opts, g.Other)`) or a real body is untouched, so the
+   * non-trackLines and non-self-wrap output stays byte-identical.
+   */
+  private scopeSelfBody(c: Comb): Comb | undefined {
+    const name = this.localRuleNames.get(c)
+    if (name === undefined || c._def.tag !== 'grammar') return undefined
+    const inner = c._def.parser
+    if (inner._def.tag !== 'lazy' || ruleNameOf(inner) !== name) return undefined
+    return lazyTarget(inner) ?? undefined
+  }
+
   run(): string {
     for (const [, c] of this.ruleMap) this.analyze(this.body(c), new Set())
     for (const c of this.scanSkip) { this.assertNoRuleRef(c, new Set()); this.analyze(c, new Set()) }
@@ -415,7 +442,19 @@ class Serializer {
       return
     }
     active.add(c)
-    for (const child of childrenOf(def)) this.analyze(child, active)
+    // When a rule-entry scope wraps its own named lazy, substitute the lazy's
+    // unwrapped body for `def.parser` — but keep the scope's OTHER children (its
+    // `triviaParser`) in the analysis, exactly as `childrenOf('grammar')` returns
+    // both. Dropping the trivia parser here would leave a recursive/shared trivia
+    // unanalysed, so its const/self-ref hoisting would be missing when `expr` emits
+    // it via `kid(def.triviaParser)`. selfBody is non-undefined only for `'grammar'`.
+    const selfBody = def.tag === 'grammar' ? this.scopeSelfBody(c) : undefined
+    const kids = selfBody === undefined
+      ? childrenOf(def)
+      : def.tag === 'grammar' && def.triviaParser
+        ? [selfBody, def.triviaParser]
+        : [selfBody]
+    for (const child of kids) this.analyze(child, active)
     active.delete(c)
   }
 
@@ -602,7 +641,7 @@ class Serializer {
           : spec
             ? `classifiedTrivia({ ${spec.arms.map(arm => `${JSON.stringify(arm.label)}: ${kid(arm.parser)}`).join(', ')} })`
             : def.triviaParser ? kid(def.triviaParser) : 'undefined'
-        return `parser({ trivia: ${trivia}${def.captureTrivia ? ', captureTrivia: true' : ''}${def.rootCapture ? `, rootCapture: ${JSON.stringify(def.rootCapture)}` : ''}${def.trackLines ? ', trackLines: true' : ''} }, ${kid(def.parser)})`
+        return `parser({ trivia: ${trivia}${def.captureTrivia ? ', captureTrivia: true' : ''}${def.rootCapture ? `, rootCapture: ${JSON.stringify(def.rootCapture)}` : ''}${def.trackLines ? ', trackLines: true' : ''} }, ${kid(this.scopeSelfBody(c) ?? def.parser)})`
       }
       case 'withCtx': {
         // A `withCtx` round-trips through `_wc`, which rebuilds it AND re-attaches

package/src/table/encode.ts

@@ -1404,7 +1404,15 @@ class Encoder {
         // names tokens the run would have skipped — `['"@"', '"(", '"x"']` where
         // running the body reports `['"x"']` alone.
         if (matchesEmpty(d.parser)) return body
-        const fs = d.parser._meta.firstSet
+        // A node whose BODY is a bare cross-rule ref (`node('X', g.Y, …)`) caches its
+        // first set from the ref's base binding. Under a compose OVERRIDE the winner
+        // for `Y` may be WIDER, so the cached set gates out input the merged rule
+        // accepts (the reducer reroutes via `winners`, but this recognizer gate did
+        // not). Resolve the ref's gate through `winners`, exactly as the `lazy` case
+        // resolves the call. Non-ref bodies keep the cached set (byte-identical).
+        const fs = d.parser._def.tag === 'lazy'
+          ? firstSetOf(d.parser, new Set(), this.refResolver())
+          : d.parser._meta.firstSet
         if (fs.kind === 'any') return body
         const cls = this.charClass(fs)
         if (cls < 0) return body
@@ -1594,7 +1602,11 @@ class Encoder {
         // run itself would have skipped past. Running the inner instead reported a
         // strictly smaller set, so omitting the guard was an observable divergence,
         // not a slower equivalent.
-        const fs = d.parser._meta.firstSet
+        // Same override-aware resolution as the node gate: a bare-ref inner resolves
+        // its gate through `winners` so a widened winner is not gated out.
+        const fs = d.parser._def.tag === 'lazy'
+          ? firstSetOf(d.parser, new Set(), this.refResolver())
+          : d.parser._meta.firstSet
         if (fs.kind === 'any' || matchesEmpty(d.parser)) return inner
         const cls = this.charClass(fs)
         if (cls < 0) return inner

package/src/version.ts

@@ -13,4 +13,4 @@
  * Kept in sync with `package.json` by `test/unit/version-sync.test.ts`, which fails
  * the build if this constant drifts from the published version.
  */
-export const PARSEMAN_VERSION = '0.50.3'
+export const PARSEMAN_VERSION = '0.50.5'