parseman 0.60.3 → 0.60.5

package/src/plugin/evaluator.ts

@@ -16,7 +16,7 @@ import type {
 import type { Combinator } from '../types.ts'
 import type { DispatchArm } from '../combinators/dispatch.ts'
 import { ref } from '../combinators/ref.ts'
-import { rules, type RulesOptions } from '../combinators/parser.ts'
+import { rules, RULES_RECIPE, type PriorRules, type RulesOptions, type RulesRecipe } from '../combinators/parser.ts'
 import * as parseman from '../index.ts'
 import { confirmedBuildParamUnused } from '../compiler/build-arity.ts'
 import { directBuilderBindings } from './direct-builder-static.ts'
@@ -1478,11 +1478,17 @@ export function evaluateParserFactory(
 
   const factory = factoryNode as unknown as ArrowFunctionExpression | OxcFunction
   const params = factory.params
-  if (params.length !== 1) return null
-  const param = params[0] as unknown as { type: string; name?: string }
+  if (params.length !== 1 && params.length !== 2) return null
   // FormalParameter is { decorators? } & BindingPattern — BindingIdentifier has type "Identifier"
-  const proxyName = param.type === 'Identifier' ? param.name ?? null : null
+  const paramName = (param: unknown): string | null => {
+    const p = param as { type: string; name?: string }
+    return p.type === 'Identifier' ? p.name ?? null : null
+  }
+  const proxyName = paramName(params[0])
   if (!proxyName) return null
+  // `(g, prior)`: the second parameter is the `prior` handle (`PriorRules`).
+  const priorName = params.length === 2 ? paramName(params[1]) : undefined
+  if (priorName === null) return null
 
   const body = factory.body
   if (!body) return null
@@ -1566,11 +1572,12 @@ export function evaluateParserFactory(
   const ABORT = Symbol('parseman: factory not statically evaluable')
   let built: Record<string, Combinator<unknown>>
   try {
-    built = rules(options ?? {}, (g: Record<string, Combinator<unknown>>) => {
+    built = rules(options ?? {}, (g: Record<string, Combinator<unknown>>, prior: PriorRules) => {
       // Outer ScopeEntry values carry their mfSrcs and are replayed by scopeGet()
       // when body statements or return expressions reference them.
       const localScope: XScope = scope instanceof ModuleScope ? scope.fork() : new Map(scope as XScope)
       localScope.set(proxyName, g)
+      if (priorName !== undefined) localScope.set(priorName, prior)
 
       // ── Phase 1: the factory's own body statements ────────────────────────
       if (!evalBodyStatements(statements, localScope, code, out)) throw ABORT
@@ -1613,9 +1620,24 @@ export function evaluateParserFactory(
    */
   const map = new Map<string, Combinator<unknown>>()
   for (const key of keys) map.set(key, built[key]!)
+  const declared = new Set(keys)
+  externalAccesses.set(map, Object.keys(built).filter(name => !declared.has(name)))
+  ruleMapRecipes.set(map, (built as unknown as Record<symbol, readonly RulesRecipe[]>)[RULES_RECIPE]!)
   return map
 }
 
+/** The recipe an evaluated rule map came from, for a composition that links it. */
+export const ruleMapRecipes = new WeakMap<ReadonlyMap<string, Combinator<unknown>>, readonly RulesRecipe[]>()
+
+/**
+ * Every EXTERNAL name an evaluated factory read through `g`, keyed by the map
+ * `evaluateParserFactory` returned. The map holds declared rules only, so a `g.X`
+ * read outside every rule body (`const unused = g.X`) leaves no trace in it; the
+ * IR serializer reads this to keep that access, so a composition refuses an `X`
+ * nobody defines exactly as runtime `compose()` does.
+ */
+export const externalAccesses = new WeakMap<ReadonlyMap<string, Combinator<unknown>>, readonly string[]>()
+
 /** A combinator slot created by ref() — has a callable `define`. */
 type DefinableRef = Combinator<unknown> & { define(p: Combinator<unknown>): void }
 

package/src/plugin/index.ts

@@ -24,7 +24,7 @@ import { createUnplugin } from 'unplugin'
 import { parseSync } from 'oxc-parser'
 import { ResolverFactory } from 'oxc-resolver'
 import MagicString from 'magic-string'
-import { evaluateExpr, evaluateCombinatorArray, evaluateParserFactory, evaluateStaticValue, evaluateWordFactory, evaluateWhenFactory, evaluateRefDeclaration, applyDefineStatement, referencesAny, setReducerResolver, setBuilderImportResolver, propName, ModuleScope, type FreeNameResolution, type Scope, type ScopeEntry } from './evaluator.ts'
+import { evaluateExpr, evaluateCombinatorArray, evaluateParserFactory, externalAccesses, ruleMapRecipes, evaluateStaticValue, evaluateWordFactory, evaluateWhenFactory, evaluateRefDeclaration, applyDefineStatement, referencesAny, setReducerResolver, setBuilderImportResolver, propName, ModuleScope, type FreeNameResolution, type Scope, type ScopeEntry } from './evaluator.ts'
 import { classifyRuleMap } from '../analysis/commitment.ts'
 import { compile } from '../table/compile.ts'
 import { compileRuleMap, type CompiledRuleMapTable } from '../table/compile-rule-map.ts'
@@ -37,7 +37,7 @@ import {
   resolveDegradationLevel, recordDegradation, degradationCaptureDepth, unwindDegradationCapture,
 } from '../compiler/degradation.ts'
 import type { HostMode } from '../cst/host-mode.ts'
-import { COMPOSED_PIECES, type IRPiece } from '../compiler/linker.ts'
+import { COMPOSED_PIECES, danglingReference, type IRPiece } from '../compiler/linker.ts'
 import { serializeCombinator, serializeRuleMap } from '../compiler/ir-serialize.ts'
 import { evalCombinatorIR, evalRulesIR, INERT_BUILDER } from './ir-eval.ts'
 import { countSiteVisits } from '../table/assemble.ts'
@@ -220,6 +220,9 @@ const DEFAULT_ASSEMBLY_BUDGET = 0.25
  * ~79 ms against ~14 ms on `benchmark.less`. "Couldn't be inlined" alone does not
  * tell an author which construct to change; the compiler knows, so it says.
  */
+/** A build failure the lowering must not soften into a warning and a fallback. */
+class LinkRefusal extends Error {}
+
 function reasonSuffix(runtimeOnly: readonly string[] | undefined): string {
   return runtimeOnly === undefined || runtimeOnly.length === 0
     ? ''
@@ -2052,7 +2055,7 @@ function transformMacroImpl(
   /**
    * Evaluate a carried list back to combinators, one entry per piece: its rule map
    * and the `rules()` recipe it was built from. `compose()` links the recipes into
-   * one namespace (`mergedCarriedRules`); `composeLeaf()` merges the maps by name.
+   * one namespace (`mergedCarriedRules`), and `composeLeaf()` does the same.
    * Either way the merged grammar is encoded ONCE by `compileRuleMap` — no relocation
    * of code offsets and no merging of const / fn / expected pools between two
    * already-encoded programs.
@@ -2088,38 +2091,6 @@ function transformMacroImpl(
     return { pieces, trackLines }
   }
 
-  /**
-   * Fold ordered rule maps into the composed map: a later piece's name WINS, and
-   * `Map` keeps each name at its first-sighting position so the encoded rule order
-   * tracks the source lowering's rather than drifting per compose.
-   *
-   * A REFERENCE IS NOT A DEFINITION. A `rules(g => …)` cache also holds every `g.X`
-   * that was merely ACCESSED, so a delta that calls `g.Pair` carries a `Pair` entry
-   * that is an unresolved named lazy. Merged in name order that entry lands LAST and
-   * shadows the base piece which actually defines `Pair` — the encoder then finds a
-   * hole where the winner should be and refuses the whole grammar with "ref() used
-   * before .define()". The same filter guards `compileLinkableTable`'s `isLocal`
-   * (`compile-linkable-table.ts`) and `recoverComposedRules`; this site needs it
-   * for the same reason, and skipping it is why cross-piece composition looked blocked.
-   *
-   * The reference itself is not lost: it stays inside the delta's own rule bodies and
-   * `enc.winners` binds it BY NAME to whichever piece supplies the definition.
-   */
-  const mergeRuleMaps = (
-    maps: ReadonlyArray<ReadonlyArray<readonly [string, Combinator<unknown>]>>,
-  ): Array<[string, Combinator<unknown>]> => {
-    const winners = new Map<string, Combinator<unknown>>()
-    for (const map of maps) {
-      for (const [name, rule] of map) {
-        if (rule._def.tag === 'lazy') {
-          try { rule._def.thunk() } catch { continue }
-        }
-        winners.set(name, rule)
-      }
-    }
-    return [...winners]
-  }
-
   /**
    * LINK a carried list into the composed map, exactly as runtime `compose()` does:
    * every piece's carried `rules()` recipe runs again against ONE namespace
@@ -2136,36 +2107,15 @@ function transformMacroImpl(
   const mergedCarriedRules = (
     items: CarriedItem[],
     link: LinkOptions,
-  ): { rules: Array<[string, Combinator<unknown>]>; trackLines: boolean } | null => {
+  ): { rules: Array<[string, Combinator<unknown>]>; trackLines: boolean; dangling: string | undefined } | null => {
     const carriedMaps = carriedRuleMaps(items)
     if (carriedMaps === null) return null
     const linked = linkRules(carriedMaps.pieces.flatMap(p => p.recipes), link)
     // A name some piece only REFERENCES and none defines stays an undefined slot in
-    // the namespace. It is not a rule, so it is not handed to the encoder as one.
-    const rules = Object.entries(linked).filter(([, rule]) => {
-      if (rule._def.tag !== 'lazy') return true
-      try { rule._def.thunk(); return true } catch { return false }
-    })
-    return { rules, trackLines: carriedMaps.trackLines }
-  }
-
-  /**
-   * COMPOSING-WINS for `composeLeaf()`'s carried pieces, as an OVERRIDE rather than
-   * a gap-fill: `compileRuleMap`'s `applyAmbient` only fills a rule that carries no
-   * trivia of its own. (`compose()` gets the same override from `linkRules`.)
-   *
-   * Safe to mutate: every rule here came from `evalRuleMapIR`, which constructs FRESH
-   * combinators per piece per compose, so this cannot leak into another compose of the
-   * same base grammar.
-   */
-  const applyComposingTrivia = (
-    ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>,
-    composing: Combinator<unknown>,
-  ): void => {
-    for (const [, rule] of ruleMap) {
-      if (rule._meta.isTrivia) continue
-      ;(rule._meta as { grammarTrivia?: Combinator<unknown> }).grammarTrivia = composing
-    }
+    // the namespace. Runtime `compose()` refuses that grammar at link, so the build
+    // refuses it too (the caller throws `dangling`) rather than encode around the hole.
+    const dangling = danglingReference(linked)
+    return { rules: Object.entries(linked), trackLines: carriedMaps.trackLines, dangling }
   }
 
   /** Resolve one `compose([...])` argument to its RE-LOWERABLE carried items (IR
@@ -2183,7 +2133,7 @@ function transformMacroImpl(
     // `rules({ scanSkip }, …)` options, which stamps `_meta.grammarScanSkip` when the IR
     // is re-lowered (materializePiece → compileLinkable picks it up), and survives to a
     // downstream re-compose. The full-pieces fallback bakes it via the compile option.
-    const ir = serializeRuleMap(entries as never, scanSkip)
+    const ir = serializeRuleMap(entries as never, scanSkip, rm instanceof Map ? externalAccesses.get(rm) : undefined)
     if (ir) return { carried: [{ ns, ir, ...(trackLines ? { trackLines: true as const } : {}) }] }
     // NO FULL-PIECES FALLBACK. It used to bake the grammar to lowered source when the IR
     // would not serialize; with one lowering there is nothing to bake to, and IR is not
@@ -2333,10 +2283,18 @@ function transformMacroImpl(
     // does — one encode, one `tableRules(…)` expression, no linker. `carried` is
     // unchanged either way: it is the re-lowerable IR list, not a lowering artifact,
     // so a downstream re-compose behaves identically whichever engine emitted here.
-    const merged = mergedCarriedRules(carried, {
-      trivia: composing,
-      ...(cHostMode ? { hostMode: cHostMode as HostMode } : {}),
-    })
+    let merged: ReturnType<typeof mergedCarriedRules>
+    try {
+      merged = mergedCarriedRules(carried, {
+        trivia: composing,
+        ...(cHostMode ? { hostMode: cHostMode as HostMode } : {}),
+      })
+    } catch (e) {
+      // Linking refuses the composition (a `prior.X` no earlier piece defines): a
+      // runtime `compose()` would refuse it the same way, so the build fails, here.
+      throw new Error(`${id}:${lineOf(init.start)} — ${(e as Error).message}`, { cause: e })
+    }
+    if (merged?.dangling !== undefined) throw new Error(`${id}:${lineOf(init.start)} — compose: ${merged.dangling}`)
     if (merged !== null) {
       // Harvest the direct-builder import provenance carried on the merged graph so
       // the re-lower pass at the end of this transform re-emits those imports.
@@ -2467,22 +2425,15 @@ function transformMacroImpl(
       return null
     }
     const localArg = elements[elements.length - 1]!
-    let localRules: Iterable<readonly [string, unknown]> | null = null
-    // The LOCAL leaf grammar's own ambient scanSkip (from its `rules({ scanSkip })`)
-    // governs the scanTo/balanced sites IT defines — unlike trivia (composing-wins),
-    // opaque units are dialect-specific, so the local declaration is threaded to the
-    // local piece's compile.
-    let localScanSkip: Combinator<unknown>[] | undefined
+    let localRules: ReadonlyMap<string, Combinator<unknown>> | null = null
     const importedFactories: string[] = []
     if (isRulesCall(localArg)) {
       const evaluated = evaluateRulesFactory(localArg, `composeLeaf${init.start}`)
       localRules = evaluated?.ruleMap ?? null
-      localScanSkip = evaluated?.scanSkip
       if (evaluated?.importedFactory) importedFactories.push(evaluated.importedFactory)
     } else if (localArg.type === 'Identifier') {
       const name = (localArg as unknown as { name: string }).name
       localRules = localRuleMaps.get(name) ?? null
-      localScanSkip = localGrammarScanSkip.get(name)
     }
     if (!localRules) {
       // Distinguish "the argument is the wrong SHAPE" from "the argument is the right
@@ -2517,13 +2468,6 @@ function transformMacroImpl(
       // may place one beneath a direct node(). Re-lower their terminals with
       // capture enabled so that node receives the imported token values in its
       // normal child collector; the pieces still contain no semantic callback.
-      const localNs = nsFor(`composeLeaf${init.start}`)
-      const localEntries = [...localRules] as Array<[string, Combinator<unknown>]>
-
-      // TABLE FIRST — same merge as `compose()`, with the local leaf map appended LAST
-      // so it wins every name and binds the imported shapes' holes (`enc.winners`
-      // resolves those by name; see `mergedCarriedRules`).
-      //
       // The recognition-only gate is preserved EXACTLY, and is the reason this path
       // needs no `compileLinkable`: `hasDirectBuilders` / `isRecognitionOnly` are
       // predicates over the combinator graph, not products of lowering it, so
@@ -2546,27 +2490,23 @@ function transformMacroImpl(
           warn(init.start, 'composeLeaf(): every pre-final grammar must explicitly prove recognition-only')
           return null
         }
-        // The local grammar's OWN ambient scanSkip is stamped onto the LOCAL entries
-        // only. Passing it as a merged-map option instead would let `applyAmbient`
-        // hand it to every imported rule that happens to carry no stamp of its own —
-        // opaque units are dialect-specific, and that is precisely the leak the
-        // per-piece threading in the source path exists to avoid.
-        if (localScanSkip) {
-          for (const [, rule] of localEntries) {
-            if (rule._meta.isTrivia) continue
-            const meta = rule._meta as { grammarScanSkip?: Combinator<unknown>[] }
-            if (meta.grammarScanSkip === undefined) meta.grammarScanSkip = localScanSkip
-          }
+        // The same link as `compose()` and runtime `composeLeaf()`: the leaf is the last
+        // recipe, so it wins every name, binds the imported shapes' holes and fills its
+        // `prior.X`. Each recipe keeps its own scanSkip; the composing trivia governs all.
+        let linked: Record<string, Combinator<unknown>>
+        try {
+          linked = linkRules(
+            [...carriedMaps.pieces.flatMap(p => p.recipes), ...ruleMapRecipes.get(localRules)!],
+            { trivia: composing },
+          )
+        } catch (e) {
+          throw new LinkRefusal(`${id}:${lineOf(init.start)} — composeLeaf: ${(e as Error).message.replace(/^compose: /, '')}`, { cause: e })
         }
-        const leafMerged = mergeRuleMaps([...carriedMaps.pieces.map(p => p.rules), localEntries])
-        // Composing-wins governs the leaf fuse too. The local entries are NOT freshly
-        // evaluated (they come from this module's own `rules()` factory), so they are
-        // excluded from the override — their declared trivia IS the composing candidate,
-        // and rewriting `_meta` on them would mutate the module-level grammar object.
-        if (composing) applyComposingTrivia(carriedMaps.pieces.flatMap(p => p.rules), composing)
+        const dangling = danglingReference(linked)
+        if (dangling !== undefined) throw new LinkRefusal(`${id}:${lineOf(init.start)} — composeLeaf: ${dangling}`)
         const refusals: string[] = []
         const compiled = compileRuleMap(
-          leafMerged,
+          Object.entries(linked),
           {
             ...(composing ? { trivia: composing } : {}),
             ...(carriedMaps.trackLines ? { trackLines: true } : {}),
@@ -2595,6 +2535,7 @@ function transformMacroImpl(
       warn(init.start, 'composeLeaf(): a recognition piece has no re-lowerable IR')
       return null
     } catch (e) {
+      if (e instanceof LinkRefusal) throw e
       warn(init.start, `composeLeaf(): ${(e as Error).message}`)
       return null
     }
@@ -2796,7 +2737,7 @@ function transformMacroImpl(
             // lowering there is no such artifact, and a grammar that cannot serialize
             // simply is not carried: an absent carried list makes the downstream compose
             // say so, where a frozen one did not.
-            const ir = serializeRuleMap([...compiledRules.ruleMap] as never, compiledRules.scanSkip)
+            const ir = serializeRuleMap([...compiledRules.ruleMap] as never, compiledRules.scanSkip, externalAccesses.get(compiledRules.ruleMap))
             if (ir) carriedMetadata = [{ ns, ir, ...(compiledRules.trackLines ? { trackLines: true as const } : {}) }]
             // NOT SILENT. An export with no carried IR cannot be composed downstream at
             // all — the consumer's `compose()` will fall back to runtime and say so, but

package/src/spec/model.ts

@@ -507,7 +507,9 @@ class Builder {
 
       case 'lazy': {
         const inner = resolveLazy(self)
-        return inner ? this.walk(inner) : { kind: 'annotation', text: '?' }
+        if (inner) return this.walk(inner)
+        const prior = (self as { _priorOf?: string })._priorOf
+        return { kind: 'annotation', text: prior === undefined ? '?' : `prior.${prior}` }
       }
 
       case 'unknown':

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.60.3'
+export const PARSEMAN_VERSION = '0.60.5'