parseman 0.46.0 → 0.47.0

package/src/combinators/first-set.ts

@@ -0,0 +1,322 @@
+import type { CharRange, FirstSet, Combinator, ParserDef } from '../types.ts'
+
+/**
+ * Resolve a NAMED cross-artifact rule reference (`g.Foo`) whose own thunk does not
+ * resolve — the shared-shape hole, bound by name at fuse time.
+ *
+ * A shape module compiles `Ratio: sequence(g.Value, …)` without defining `Value`, so
+ * that `lazy`'s thunk throws and every first-set through it degrades to `any`. Once
+ * the shape is FUSED with a dialect that defines `Value`, the hole is bound — pass a
+ * resolver over the fused winner map and the first-set is the real one.
+ *
+ * Only NAMED refs are resolvable: an unnamed `ref()` that was never `.define()`d
+ * carries no name for anyone to bind, so it stays `any`.
+ */
+export type RefResolver = (name: string) => Combinator<unknown> | undefined
+
+/** The `resolve`-supplied target for an unresolvable NAMED lazy, if any. */
+function resolveNamedRef(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)
+}
+
+export function union(a: FirstSet, b: FirstSet): FirstSet {
+  if (a.kind === 'any' || b.kind === 'any') return { kind: 'any' }
+  if (a.kind === 'empty') return b
+  if (b.kind === 'empty') return a
+  return { kind: 'ranges', ranges: mergeRanges([...a.ranges, ...b.ranges]) }
+}
+
+export function intersects(a: FirstSet, b: FirstSet): boolean {
+  if (a.kind === 'any' || b.kind === 'any') return true
+  if (a.kind === 'empty' || b.kind === 'empty') return false
+  for (const ra of a.ranges) {
+    for (const rb of b.ranges) {
+      if (ra.lo <= rb.hi && rb.lo <= ra.hi) return true
+    }
+  }
+  return false
+}
+
+export function fromChar(code: number): FirstSet {
+  return { kind: 'ranges', ranges: [{ lo: code, hi: code }] }
+}
+
+/**
+ * True when `combinator`'s first set admits the code point at `input[pos]` (or its
+ * first set is `any`). The runtime counterpart of codegen's `firstSetCond` guard —
+ * used by the interpreter's first-set fail-fast in `optional`/`many`/`attempt`/
+ * `node` to reject a doomed sub-parse before doing any setup. Returns `false` at EOF.
+ */
+export function startsFirstSet(combinator: Combinator<unknown>, input: string, pos: number): boolean {
+  const fs = combinator._meta.firstSet
+  if (fs.kind === 'any') return true
+  if (fs.kind === 'empty') return false
+  const code = input.codePointAt(pos)
+  if (code === undefined) return false
+  for (const r of fs.ranges) if (code >= r.lo && code <= r.hi) return true
+  return false
+}
+
+export function fromRange(lo: number, hi: number): FirstSet {
+  return { kind: 'ranges', ranges: [{ lo, hi }] }
+}
+
+export function any(): FirstSet {
+  return { kind: 'any' }
+}
+
+export function empty(): FirstSet {
+  return { kind: 'empty' }
+}
+
+/**
+ * Can this parser SUCCEED consuming zero characters (nullable / matches-empty)?
+ * Used to compute a sound sequence first-set: a nullable leading term lets the
+ * NEXT term's first chars start the whole sequence. MUST err toward `true` when
+ * unsure — over-estimating nullability only widens the (over-approximated) first
+ * set, which stays sound; under-estimating would drop valid start chars and make
+ * first-char dispatch skip a matching arm.
+ */
+export function matchesEmpty(
+  p: Combinator<unknown>,
+  seen: Set<Combinator<unknown>> = new Set(),
+  resolve?: RefResolver,
+): boolean {
+  // Cycle guard: a mutually-nullable ref cycle (e.g. `A = oneOrMore(B); B = oneOrMore(A)`)
+  // would recurse forever. Treat a re-entered node as nullable — the safe (`true`)
+  // default, consistent with the err-toward-true contract below.
+  if (seen.has(p)) return true
+  seen.add(p)
+  const me = (c: Combinator<unknown>): boolean => matchesEmpty(c, seen, resolve)
+  const d = p._def as ParserDef
+  switch (d.tag) {
+    case 'literal':   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 d.fallback === undefined ? false : me(d.fallback)
+    case 'regex':
+      // Precise: does the pattern admit a zero-length match? (`a*`, `a?`, `a|`, …)
+      try { const m = new RegExp(d.source).exec(''); return m != null && m[0] === '' }
+      catch { return true }
+    case 'many':
+    case 'optional':
+    case 'not':
+    case 'peek':     return true          // zero repetitions / absent / lookahead
+    // Default `sepBy` is `(item (sep item)*)?` — it MATCHES THE EMPTY STRING.
+    // Any `min >= 1` requires that many ITEMS, so it is nullable only when the
+    // item is. (Keying this off `min === 1` reported every `{ min: 2 }` list as
+    // nullable — safe, but wrong, and it put a bogus `nullable-prefix` note on
+    // the gating diagnostic for a list that can never match empty.)
+    case 'sepBy':     return d.min >= 1 ? me(d.parser) : true
+    case 'oneOrMore': return me(d.parser)
+    case 'sequence':  return d.parsers.every(me)
+    case 'choice':
+      return d.parsers.some(me)
+    case 'dispatch':
+      return me(d.selector)
+    case 'transform':
+    case 'label':
+    case 'trivia':
+    case 'token':
+    case 'leaf':
+    case 'expect':
+    case 'withCtx':
+    case 'node':
+    case 'grammar':
+    case 'recover':   return me(d.parser)
+    case 'lazy':
+      try { return me(d.thunk()) }
+      catch { const t = resolveNamedRef(p, resolve); return t ? me(t) : true }
+    default:          return true          // scanTo / guard / unknown → assume nullable (safe)
+  }
+}
+
+/**
+ * A ZERO-WIDTH ASSERTION never consumes input, so it contributes NOTHING to a
+ * sequence's first-set — the first consumed char comes from the following
+ * non-nullable term. `not(X)` reports `firstSet: any()` (it cannot know what it
+ * forbids), which would otherwise poison a sequence's first-set to `any` and kill
+ * first-char dispatch of the whole arm. Skipping its contribution is SOUND: a
+ * first-set used for dispatch gating must stay a correct SUPERSET of the rule's
+ * true first chars, and `not(X) Y` can only start with a char in firstSet(Y) — the
+ * assertion only NARROWS the language (it forbids a full match ahead), it never
+ * widens the set of possible first chars beyond Y. So firstSet(Y) is a sound (and
+ * tighter) superset.
+ *
+ * The POSITIVE lookahead `peek(X)` is zero-width too, but it is NOT in this
+ * predicate: unlike `not`, it knows what it requires, so its first-set is a real
+ * constraint that must be INTERSECTED into the sequence's set rather than dropped
+ * (see `isPositiveLookahead` and `sequenceFirstSet`).
+ */
+export function isZeroWidthAssertion(p: Combinator<unknown>): boolean {
+  const tag = (p._def as ParserDef).tag
+  // `adjacency` joins `not` for the same reason: `adjacent()`/`notAdjacent()` are
+  // zero-width tests of the gap BEHIND the cursor, so they constrain nothing about
+  // the first char ahead and must not contribute their `any` to the sequence.
+  return tag === 'not' || tag === 'adjacency'
+}
+
+/**
+ * A POSITIVE zero-width assertion (`peek(X)`). It consumes nothing, so like
+ * `not(X)` it does not contribute a first char of its own — but it does REQUIRE
+ * that X match here, so `peek(X) Y` can only start with a char in
+ * firstSet(X) ∩ firstSet(Y). That intersection is what makes a leading `peek()`
+ * gate its choice arm; `not(not(X))`, the only previous spelling, reports `any()`
+ * and poisons the dispatch instead.
+ *
+ * Soundness: first-sets are SUPERSETS of the true first chars, and
+ * (A ⊇ a) ∧ (B ⊇ b) ⇒ A ∩ B ⊇ a ∩ b — so intersecting stays a superset and can
+ * never skip a real match. A NULLABLE body succeeds on the empty string and
+ * therefore constrains nothing; `peek()` reports `any()` in that case, which the
+ * intersection treats as "no constraint".
+ */
+export function isPositiveLookahead(p: Combinator<unknown>): boolean {
+  return (p._def as ParserDef).tag === 'peek'
+}
+
+/** Intersect a lookahead constraint into an accumulator; `any` = no constraint. */
+function narrowBy(acc: FirstSet | null, constraint: FirstSet): FirstSet | null {
+  if (constraint.kind === 'any') return acc
+  if (acc === null) return constraint
+  if (acc.kind === 'any') return constraint
+  if (acc.kind === 'empty' || constraint.kind === 'empty') return { kind: 'empty' }
+  const ranges: CharRange[] = []
+  for (const a of acc.ranges) for (const b of constraint.ranges) {
+    const lo = Math.max(a.lo, b.lo)
+    const hi = Math.min(a.hi, b.hi)
+    if (lo <= hi) ranges.push({ lo, hi })
+  }
+  return ranges.length === 0 ? { kind: 'empty' } : { kind: 'ranges', ranges }
+}
+
+/**
+ * Apply the accumulated `peek()` constraints to a sequence's first-set. When the
+ * consuming terms contributed NOTHING (the sequence is all zero-width/nullable,
+ * e.g. a bare `peek(X)` arm), the assertion IS the first-set: the sequence can
+ * only succeed — even zero-width — where X matches.
+ */
+function applyAssertion(fs: FirstSet, assertion: FirstSet | null): FirstSet {
+  if (assertion === null) return fs
+  if (fs.kind === 'empty') return assertion
+  return narrowBy(fs, assertion) ?? fs
+}
+
+/**
+ * First-set of a sequence: union each term's first-set through the NULLABLE
+ * PREFIX — a leading `optional(…)` / `many(…)` / nullable term can be skipped, so
+ * the sequence can begin with a LATER term's first char. Stop at (and include)
+ * the first non-nullable term. (`parsers[0].firstSet` alone under-approximates
+ * and silently breaks first-char dispatch — see the InterpolatedSelector bug.)
+ * A leading zero-width assertion (`not(…)`) is nullable but contributes NOTHING to
+ * the first-set (see `isZeroWidthAssertion`) — its `any` must not poison the union.
+ */
+export function sequenceFirstSet(parsers: readonly Combinator<unknown>[]): FirstSet {
+  let fs: FirstSet = empty()
+  let assertion: FirstSet | null = null
+  for (const p of parsers) {
+    if (isPositiveLookahead(p)) {
+      // Zero-width but CONSTRAINING: intersect, keep scanning (it consumes nothing).
+      assertion = narrowBy(assertion, p._meta.firstSet)
+      continue
+    }
+    if (!isZeroWidthAssertion(p)) fs = union(fs, p._meta.firstSet)
+    if (!matchesEmpty(p)) return applyAssertion(fs, assertion)
+  }
+  return applyAssertion(fs, assertion)
+}
+
+/**
+ * Deep first-set that RESOLVES `lazy`/`ref` combinators to their targets. The
+ * combinators bake `_meta.firstSet` at CONSTRUCTION, when a `ref()` still reads
+ * `any()` (define() never updates it) — so a `choice`/`sequence` built over refs
+ * caches a spuriously-`any` first-set and loses first-char dispatch. Recomputing
+ * here, following refs, recovers the real set. Over-approximates on cycles /
+ * unknown constructs (returns `any`) — always sound: a wider set only means "try
+ * this arm for more first chars", never skips a real match.
+ *
+ * SOUND ONLY where refs are FINAL (monolithic compile). Under compose OVERRIDE a
+ * referenced rule can be replaced with a WIDER first-set, so a baked deep set
+ * would wrongly skip valid input — the compose path defers dispatch to fuse time.
+ *
+ * `resolve` binds NAMED cross-artifact holes (`g.Foo`) against a fused winner map —
+ * see `RefResolver`. Diagnostic-only today: it is what lets the gating analysis ask
+ * the question at the site where the hole actually HAS an answer.
+ */
+export function firstSetOf(
+  p: Combinator<unknown>,
+  seen: Set<Combinator<unknown>> = new Set(),
+  resolve?: RefResolver,
+): FirstSet {
+  if (seen.has(p)) return any()               // cycle → any (safe over-approximation)
+  seen.add(p)
+  const fs = (c: Combinator<unknown>): FirstSet => firstSetOf(c, seen, resolve)
+  const empties = (c: Combinator<unknown>): boolean => matchesEmpty(c, new Set(), resolve)
+  const d = p._def as ParserDef
+  switch (d.tag) {
+    case 'literal':
+    case 'regex':
+    case 'keywords':  return p._meta.firstSet  // terminals: no refs, cached set is exact
+    case 'dispatch':  return fs(d.selector)
+    case 'lazy':
+      try { return fs(d.thunk()) }
+      catch { const t = resolveNamedRef(p, resolve); return t ? fs(t) : any() }
+    case 'choice': {
+      let out: FirstSet = empty()
+      for (const arm of d.parsers) out = union(out, fs(arm))
+      return out
+    }
+    case 'sequence': {
+      // Union through the nullable prefix (a leading nullable term lets a later
+      // term's first chars start the sequence) — ref-resolving `sequenceFirstSet`.
+      // A leading zero-width assertion (`not`) contributes nothing (its `any` would
+      // poison the union) but is still nullable, so keep scanning past it. A
+      // positive `peek()` is zero-width AND constraining → intersect.
+      let out: FirstSet = empty()
+      let assertion: FirstSet | null = null
+      for (const term of d.parsers) {
+        if (isPositiveLookahead(term)) { assertion = narrowBy(assertion, fs(term)); continue }
+        if (!isZeroWidthAssertion(term)) out = union(out, fs(term))
+        if (!empties(term)) return applyAssertion(out, assertion)
+      }
+      return applyAssertion(out, assertion)
+    }
+    case 'peek': {
+      // Deep-resolve the body: a `ref()` reads `any()` at CONSTRUCTION, so the
+      // shallow `_meta.firstSet` baked into the assertion would lose the gate.
+      const inner = d.parser
+      return empties(inner) ? any() : fs(inner)
+    }
+    case 'oneOrMore':
+    case 'many':
+    case 'optional':
+    case 'transform':
+    case 'label':
+    case 'trivia':
+    case 'token':
+    case 'leaf':
+    case 'node':
+    case 'grammar':
+    case 'expect':    return fs(d.parser)
+    case 'sepBy':     return fs(d.parser)   // both min 0 and min 1 start with the item
+    default:          return p._meta.firstSet  // not / scanTo / guard / withCtx / recover / unknown
+  }
+}
+
+function mergeRanges(ranges: CharRange[]): CharRange[] {
+  if (ranges.length === 0) return []
+  const sorted = [...ranges].sort((a, b) => a.lo - b.lo)
+  // Always copy — never alias input objects
+  const out: CharRange[] = [{ lo: sorted[0]!.lo, hi: sorted[0]!.hi }]
+  for (let i = 1; i < sorted.length; i++) {
+    const top = out[out.length - 1]!
+    const cur = sorted[i]!
+    if (cur.lo <= top.hi + 1) {
+      if (cur.hi > top.hi) top.hi = cur.hi
+    } else {
+      out.push({ lo: cur.lo, hi: cur.hi })
+    }
+  }
+  return out
+}

package/src/combinators/gate.ts

@@ -0,0 +1,50 @@
+import type { Combinator, ParseContext, ParseResult, ParserMeta } from '../types.ts'
+
+/**
+ * Zero-width state ASSERTION: succeeds (consuming nothing) only when `predicate`
+ * returns true for `ctx.state`. Fails otherwise.
+ *
+ * Intended for use inside sequence() to gate subsequent parsing on runtime
+ * context set with withCtx():
+ *
+ *   const returnStmt = sequence(
+ *     gate(ctx => (ctx as { inFn: boolean }).inFn),
+ *     literal('return'), optional(expr)
+ *   )
+ *
+ * Naming: this matches the `gate:` field on a gated CHOICE arm
+ * (`choice({ gate, combinator }, other)`). Use the arm FIELD to SELECT a branch by
+ * a cheap state predicate; use this COMBINATOR to ASSERT a state predicate
+ * mid-sequence. Formerly named `guard()` — see the deprecated alias in `guard.ts`.
+ *
+ * Note: like all state predicates its first-set is `any`, so a `gate(...)` as the
+ * LEADING term of a choice arm poisons that choice's first-char dispatch. Keep it
+ * after a concrete leading terminal.
+ */
+export function gate(predicate: (state: unknown) => boolean): Combinator<null> {
+  const meta: ParserMeta = {
+    firstSet: { kind: 'any' },
+    canMatchNewline: false,
+    isTrivia: false,
+  }
+  return {
+    _tag: 'guard',
+    _meta: meta,
+    _def: { tag: 'guard', predicate },
+    parse(_input: string, pos: number, ctx: ParseContext): ParseResult<null> {
+      if (predicate(ctx.state))
+        return { ok: true, value: null, span: { start: pos, end: pos } }
+      // The label is the PUBLIC name. It used to be `'guard'`, justified in a
+      // comment here as "parity with the compiled path" — which had not been true
+      // since the rename: codegen emitted `'gate'` and this emitted `'guard'`, so
+      // the same failing input reported a different expected set depending on
+      // which engine ran it. Nothing caught it because no test compared the two
+      // engines' expected sets on a state-scoped failure.
+      //
+      // `guard` was removed as a public name in 0.44.0, so it also pointed users
+      // at something they could no longer find. The def TAG stays `'guard'` —
+      // that is internal and the encoder switches on it.
+      return { ok: false, expected: ['gate'], span: { start: pos, end: pos } }
+    },
+  }
+}

package/src/combinators/grammar.ts

@@ -0,0 +1,272 @@
+import type { Combinator, ParseContext, ParseResult, ParseFail, ParseError } from '../types.ts'
+import { createLineIndex, recordLineRange, normalizeLineIndex, annotateSpan, type LineIndex } from '../line-index.ts'
+import { markUnusedValues } from '../compiler/value-usage.ts'
+import { triviaKindMask } from '../cst/trivia-kinds.ts'
+import { refuseUnclassifiedRootScope } from '../cst/root-trivia-scope.ts'
+import { createParseContext } from '../parse-context.ts'
+
+export type ParseOptions = {
+  trackLines?: boolean
+  /**
+   * Enable the error-collection channel. When true, recovery points (expect(), and
+   * tolerant list recovery) collect their ParseErrors into a side-channel array
+   * rather than only embedding them in the value tree. The returned ParseOk will
+   * have an `errors` field listing all recovered errors. Top-level parse failures
+   * (where nothing recovered) still return ParseFail as usual.
+   */
+  recover?: boolean
+}
+
+export type ParserOptions = ParseOptions & {
+  /**
+   * Trivia parser for this scope. Three states:
+   *   - a Combinator → skip this trivia between sequence/repeat terms
+   *   - `undefined`  → inherit the enclosing scope's trivia (no change)
+   *   - `null`       → CLEAR trivia: no trivia skipped, so terms must be contiguous.
+   *                    Re-enable inside a nested region with another parser({ trivia }).
+   */
+  trivia?: Combinator<unknown> | null
+  /**
+   * Declare that this local trivia scope intentionally does not preserve
+   * selected root categories. Required only by
+   * `rootTrivia: { select }` when the scope does not use
+   * `classifiedTrivia()`.
+   */
+  rootCapture?: 'opaque'
+  /** Record consumed trivia as CSTTrivia tokens in rawChildren. Default: skip. */
+  captureTrivia?: boolean
+  /**
+   * Restrict PER-NODE CST trivia capture to these trivia kinds (label names from
+   * the trivia's `label()` arms). Whitespace and any other unlisted kind is still
+   * skipped over but NOT recorded into a node's `triviaLog` — so a host that only
+   * consumes (say) comments pays nothing to log every whitespace run. The global
+   * trivia log is unaffected. Requires labeled trivia; ignored otherwise.
+   */
+  captureTriviaKinds?: readonly string[]
+}
+
+export interface ParsemanParser<T> extends Combinator<T> {
+  parse(input: string): ParseResult<T>
+  parse(input: string, pos: number, ctx: ParseContext): ParseResult<T>
+}
+
+function annotateResultLines<T, R extends ParseResult<T>>(result: R, index: LineIndex): R {
+  const annotated = { ...result, span: annotateSpan(result.span, index) } as R
+  const errors = (annotated as { errors?: ParseError[] }).errors
+  if (errors) {
+    ;(annotated as { errors: ParseError[] }).errors = errors.map(error => ({
+      ...error,
+      span: annotateSpan(error.span, index),
+    }))
+  }
+  return annotated
+}
+
+function createParseLineContext(input: string, pos: number): { lineIndex: LineIndex; lineScannedTo: number } {
+  const lineIndex = createLineIndex()
+  if (pos > 0) recordLineRange(lineIndex, input, 0, pos)
+  return { lineIndex, lineScannedTo: pos }
+}
+
+/** The three pre-written `trackLines` resolvers. One is SELECTED at link time. */
+const TRACK_LINES_ON = (): boolean => true
+const TRACK_LINES_OFF = (): boolean => false
+const TRACK_LINES_INHERIT = (ctx: ParseContext | undefined): boolean => ctx?.trackLines === true
+
+/**
+ * A trivia scope.
+ *
+ * ── NO RULE MAY CONSULT AN OPTION WHILE IT PARSES ───────────────────────────
+ *
+ * `opts` is fixed when `parser(opts, root)` is called. That is LINK TIME — the
+ * same moment `assemble.ts` resolves `RunCfg` into a choice of piece, and the
+ * same rule (`RunCfg`'s header, `scripts/check-invariants.mjs` INV-6/INV-7).
+ * Everything below used to be read INSIDE `parse`, which a nested scope enters
+ * on every visit, so a grammar with a `parser({ trivia })` region paid nine
+ * option reads per entry for answers that could not change.
+ *
+ * They are now resolved once, here, and the parse path reads only the resolved
+ * values. Where the answer genuinely depends on the CALLER's context — an
+ * inherited `trackLines`, inherited trivia labels — a pre-written variant is
+ * SELECTED at link time rather than branched on per entry. Selecting costs one
+ * closure per scope in the grammar; branching cost one test per entry per parse.
+ *
+ * `_ctx.trivia`, `_ctx.captureTrivia` and the CST sinks stay where they are:
+ * those are per-scope RUNTIME state that `node()` opens and closes mid-parse,
+ * not configuration. Resolving them early would be wrong, not fast.
+ */
+export function parser<T>(opts: ParserOptions, root: Combinator<T>): ParsemanParser<T> {
+  const clearTrivia = opts.trivia === null
+  const opaqueRootCapture = opts.rootCapture === 'opaque'
+  if (opaqueRootCapture && opts.trivia === undefined) {
+    throw new TypeError('parser({ rootCapture: \'opaque\' }) requires an explicit trivia scope.')
+  }
+  /** This scope's own trivia, or `undefined` for cleared/inherited. */
+  const scopeTrivia: Combinator<unknown> | undefined = clearTrivia ? undefined : (opts.trivia ?? undefined)
+  /**
+   * `?._meta?.` and not `?._meta.`: the macro's own evaluator builds a
+   * `parser({ trivia: /re/ })` from source text, so a raw RegExp reaches here.
+   * The reads used to happen inside `parse`, where such a scope threw only if it
+   * ever ran; hoisting them to construction must not turn that into a build-time
+   * throw. (`test/unit/plugin-coverage.test.ts`, "anyValue edge forms".)
+   */
+  const scopeLabels = scopeTrivia?._meta?.triviaKindLabels
+  /** Does this scope have to refuse an unclassified root scope? Link-time fact. */
+  const refuseUnclassified = scopeTrivia !== undefined
+    && !scopeTrivia._meta?.rootTriviaClassified && !opaqueRootCapture
+  const forceCaptureTrivia = opts.captureTrivia === true
+  const trackLinesOf = opts.trackLines === true ? TRACK_LINES_ON
+    : opts.trackLines === false ? TRACK_LINES_OFF
+    : TRACK_LINES_INHERIT
+  /**
+   * The per-node capture mask, resolved as far as this scope can resolve it.
+   *
+   * With its own labelled trivia the mask is a constant and is computed once.
+   * With INHERITED labels it depends on the caller, so the link step selects the
+   * deriving variant instead — `undefined` here means "no mask to install".
+   */
+  const captureKinds = clearTrivia ? undefined : opts.captureTriviaKinds
+  const ownCaptureMask = captureKinds === undefined ? undefined
+    : scopeLabels !== undefined ? triviaKindMask(scopeLabels, captureKinds)
+    : undefined
+  const inheritCaptureMask = captureKinds !== undefined && scopeLabels === undefined
+  return {
+    _tag: 'grammar',
+    _meta: {
+      ...root._meta,
+      // Trivia classification describes this grammar's own active trivia
+      // scope. A directly nested grammar may have classified trivia of its
+      // own, but that must not advertise classification for this wrapper.
+      triviaKindLabels: undefined,
+      rootTriviaClassified: undefined,
+      ...(opts.trivia?._meta?.triviaKindLabels ? { triviaKindLabels: opts.trivia._meta.triviaKindLabels } : {}),
+      ...(opts.trivia?._meta?.rootTriviaClassified ? { rootTriviaClassified: true as const } : {}),
+    },
+    _def: {
+      tag: 'grammar',
+      parser: root as Combinator<unknown>,
+      triviaParser: scopeTrivia,
+      clearTrivia,
+      ...(opaqueRootCapture ? { rootCapture: 'opaque' as const } : {}),
+      ...(opts.captureTrivia ? { captureTrivia: true } : {}),
+      trackLines: opts.trackLines ?? false,
+    },
+    parse(input: string, pos?: number, _ctx?: ParseContext): ParseResult<T> {
+      if (refuseUnclassified) refuseUnclassifiedRootScope(_ctx?._rootTriviaStrictScopes)
+      const trackLines = trackLinesOf(_ctx)
+      const lineContext = trackLines && _ctx?._lineIndex === undefined && _ctx?._lineStarts === undefined
+        ? createParseLineContext(input, pos ?? 0)
+        : undefined
+      const lineIndex = trackLines
+        ? (_ctx?._lineIndex ?? (_ctx?._lineStarts ? { lineStarts: _ctx._lineStarts } : lineContext!.lineIndex))
+        : undefined
+      // Preserve any CST collectors / capture flag from the caller (e.g. an
+      // enclosing node()), layering this grammar's trivia on top. Without this,
+      // a parser() nested inside a node() would drop the node's child collectors.
+      // Inheriting copy, then STORES — see `createParseContext`. `{ ..._ctx }`
+      // preserves the canonical shape because `_ctx` already has it, and the
+      // overrides below only touch slots that already exist.
+      const ctx: ParseContext = _ctx === undefined ? createParseContext() : { ..._ctx }
+      ctx.trackLines = trackLines
+      if (lineIndex) ctx._lineIndex = lineIndex
+      if (lineContext) ctx._lineScannedTo = lineContext.lineScannedTo
+      // trivia: null clears (contiguous terms); a Combinator sets; undefined inherits.
+      if (clearTrivia) {
+        ctx.trivia = undefined
+        ctx.triviaKindLabels = undefined
+      } else if (scopeTrivia !== undefined) {
+        ctx.trivia = scopeTrivia
+        if (scopeLabels) ctx.triviaKindLabels = scopeLabels
+      }
+      if (forceCaptureTrivia || _ctx?.captureTrivia) ctx.captureTrivia = true
+      // Kind-filter for per-node capture. Resolve against this scope's trivia
+      // labels — this parser's own trivia if it declares one, else the INHERITED
+      // labels (`_ctx.triviaKindLabels`), so captureTriviaKinds still applies when
+      // trivia is inherited rather than re-declared here. No labels → undefined
+      // (capture all).
+      if (ownCaptureMask !== undefined) ctx._triviaCaptureMask = ownCaptureMask
+      else if (inheritCaptureMask) ctx._triviaCaptureMask = triviaKindMask(_ctx?.triviaKindLabels, captureKinds)
+      // This is a property of the local trivia scope, not a post-parse filter:
+      // nested recognition can still skip its trivia, but selected root rows
+      // must never be written for an explicitly opaque region.
+      if (opaqueRootCapture) ctx._rootTriviaCapture = false
+      const result = root.parse(input, pos ?? 0, ctx)
+      if (trackLines && _ctx && ctx._lineScannedTo !== undefined) {
+        _ctx._lineScannedTo = Math.max(_ctx._lineScannedTo ?? 0, ctx._lineScannedTo)
+      }
+      return lineIndex ? annotateResultLines(result, normalizeLineIndex(lineIndex)) : result
+    },
+  } as ParsemanParser<T>
+}
+
+/**
+ * Run `root` with the active trivia cleared — no trivia is skipped between its
+ * sequence/repeat terms, so they must be contiguous in the input. (Trivia is
+ * whatever parser({ trivia }) installed — often whitespace/comments, but it is
+ * grammar-defined.) The inverse of parser({ trivia }); re-enable trivia in a
+ * nested region with another parser({ trivia }).
+ *
+ * Wrap the WHOLE contiguous run: an enclosing sequence skips trivia *before* a
+ * term runs, so wrapping just the inner part would let leading trivia through.
+ *
+ * For a static glued token just use one literal/regex; reach for noTrivia when a
+ * glued part is a structured sub-rule — e.g. a head glued to a `[subscript]`
+ * whose interior still allows trivia. Turn trivia back on for a region by nesting
+ * another parser({ trivia }) (innermost wins, reverts on exit); put the WHOLE
+ * spaced region — including its leading `[` — inside it, since sequence skips
+ * trivia only between terms, not before its first:
+ *
+ *   // `arr[i + 1]` — `arr` touches `[`, but the subscript is a spaced expr:
+ *   noTrivia(sequence(name,
+ *     parser({ trivia: ws }, sequence(literal('['), expr, literal(']')))))
+ */
+export function noTrivia<T>(root: Combinator<T>): ParsemanParser<T> {
+  return parser({ trivia: null }, root)
+}
+
+// Roots already run through dead-value analysis, so a hot parse loop doesn't
+// re-walk the tree. (A `rules()` grammar was analyzed at build; a bare combinator
+// passed straight to parse() is analyzed once here.)
+const _analyzed = new WeakSet<Combinator<unknown>>()
+
+export function parse<T>(
+  combinator: Combinator<T>,
+  input: string,
+  opts: ParseOptions = {}
+): ParseResult<T> {
+  if (!_analyzed.has(combinator)) {
+    _analyzed.add(combinator)
+    markUnusedValues(combinator)
+  }
+  const trackLines = opts.trackLines ?? combinator._meta.grammarTrackLines ?? false
+  const lineContext = trackLines ? createParseLineContext(input, 0) : undefined
+  const lineIndex = lineContext?.lineIndex
+  const _errors = opts.recover ? [] : undefined
+  // In recovery mode also track the furthest-position failure, so the caller can
+  // report "where it got stuck + what was expected" even when a permissive top
+  // rule succeeds with unconsumed trailing input. Off by default (it adds
+  // bookkeeping to every failed alternative).
+  const _probe = opts.recover ? { offset: input.length, best: null as ParseFail | null } : undefined
+  // Grammar-level ambient trivia declared via rules({ trivia }, factory): install
+  // it as ctx.trivia so it's ambient (interpreter). parser/noTrivia override locally.
+  const grammarTrivia = combinator._meta.grammarTrivia
+  const grammarScanSkip = combinator._meta.grammarScanSkip
+  // ONE shape — see `createParseContext`. Stores, not conditional spreads.
+  const ctx = createParseContext()
+  ctx.trackLines = trackLines
+  if (lineIndex) ctx._lineIndex = lineIndex
+  if (lineContext) ctx._lineScannedTo = lineContext.lineScannedTo
+  if (grammarTrivia !== undefined) {
+    ctx.trivia = grammarTrivia
+    if (grammarTrivia._meta.triviaKindLabels) ctx.triviaKindLabels = grammarTrivia._meta.triviaKindLabels
+  }
+  if (grammarScanSkip !== undefined) ctx.scanSkip = grammarScanSkip
+  if (_errors !== undefined) ctx._errors = _errors
+  if (_probe !== undefined) ctx._probe = _probe
+  const result = combinator.parse(input, 0, ctx)
+  if (!result.ok) return lineIndex ? annotateResultLines(result, normalizeLineIndex(lineIndex)) : result
+  const withErrors = _errors !== undefined
+    ? { ...result, errors: _errors, furthestFail: _probe?.best ?? null }
+    : result
+  return lineIndex ? annotateResultLines(withErrors, normalizeLineIndex(lineIndex)) : withErrors
+}