parseman 0.45.0 → 0.47.0

package/src/recovery/scan.ts

@@ -0,0 +1,155 @@
+import type { Combinator, FirstSet, ParseContext, ParseError, ParseResult, RecoveryHelpers } from '../types.ts'
+import { cstCaptureActive, pushCstChild } from '../cst/capture-buffer.ts'
+import { annotateSpanFromLineContext, recordLineRangeFromContext } from '../line-index.ts'
+
+/**
+ * Recovery MECHANISM — sync-source-agnostic. These primitives implement "scan
+ * forward to a sync token and emit a ParseError" and "is the sync token here?".
+ * They are deliberately independent of WHERE the sync sentinel comes from: the
+ * grammar never carries recovery config. Sync points are inferred automatically
+ * from grammar structure (see `infer.ts`) and may be overridden externally by the
+ * language service via `ctx._listSync`. This is the salvaged core of the old
+ * `combinators/recover-scan.ts`.
+ */
+
+/**
+ * Run `sentinel` at `pos` as PURE lookahead: succeed/fail only, with every
+ * side-effecting sink suppressed (CST leaves/children/trivia, the trivia log,
+ * the recovery error sink, and the completions probe). A recovery scan probes the
+ * sentinel at many positions and must not capture leaves, log trivia, or pollute
+ * `completionsAt`'s furthest-failure set as a byproduct of looking ahead.
+ */
+function probeAt(sentinel: Combinator<unknown>, input: string, pos: number, ctx: ParseContext): boolean {
+  const s = {
+    _probe: ctx._probe, _errors: ctx._errors,
+    _cstLeaves: ctx._cstLeaves, _cstChildren: ctx._cstChildren, _cstRawChildren: ctx._cstRawChildren,
+    _cstTriviaLog: ctx._cstTriviaLog, _triviaLog: ctx._triviaLog, _rootTriviaLog: ctx._rootTriviaLog, _fields: ctx._fields, _cstBuf: ctx._cstBuf,
+    _tolerant: ctx._tolerant, _sync: ctx._sync,
+  }
+  ctx._probe = undefined; ctx._errors = undefined
+  ctx._cstLeaves = undefined; ctx._cstChildren = undefined; ctx._cstRawChildren = undefined
+  ctx._cstTriviaLog = undefined; ctx._triviaLog = undefined; ctx._rootTriviaLog = undefined; ctx._fields = undefined; ctx._cstBuf = undefined
+  // A sentinel is pure lookahead: it must not itself enter tolerant recovery (nor
+  // read a stale outer `_sync`). Otherwise a sentinel that composes many/sepBy would
+  // run recovery on every probed position — wasted work, and it could resync to the
+  // enclosing list's sync token. Cleared here and restored in `finally`.
+  ctx._tolerant = undefined; ctx._sync = undefined
+  try {
+    return sentinel.parse(input, pos, ctx).ok
+  } finally {
+    ctx._probe = s._probe; ctx._errors = s._errors
+    ctx._cstLeaves = s._cstLeaves; ctx._cstChildren = s._cstChildren; ctx._cstRawChildren = s._cstRawChildren
+    ctx._cstTriviaLog = s._cstTriviaLog; ctx._triviaLog = s._triviaLog; ctx._rootTriviaLog = s._rootTriviaLog; ctx._fields = s._fields; ctx._cstBuf = s._cstBuf
+    ctx._tolerant = s._tolerant; ctx._sync = s._sync
+  }
+}
+
+/**
+ * Combine two recovery sentinels into one that matches when either does — used by
+ * tolerant `sepBy` to resync to its own separator OR the enclosing delimiter. Cold
+ * path only; a bare wrapper so we don't pull `choice()` (and its analysis) in.
+ */
+export function orSentinel(
+  a: Combinator<unknown>,
+  b: Combinator<unknown> | undefined,
+): Combinator<unknown> {
+  if (b === undefined) return a
+  return {
+    _tag: 'orSentinel',
+    _meta: { firstSet: { kind: 'any' }, canMatchNewline: false, isTrivia: false },
+    _def: { tag: 'unknown' },
+    parse(input: string, pos: number, ctx: ParseContext): ParseResult<unknown> {
+      const ra = a.parse(input, pos, ctx)
+      if (ra.ok) return ra
+      return b.parse(input, pos, ctx)
+    },
+  }
+}
+
+/**
+ * A lightweight zero-width sentinel that "matches" (succeeds, consuming nothing)
+ * when the input code point at `pos` starts the given first set. Sync inference
+ * builds one from a list's follow set so a nested list can resync to the enclosing
+ * delimiter with no grammar annotation. Returns `null` when the first set is `any`
+ * or `empty` (no usable inference).
+ */
+export function firstSetSentinel(fs: FirstSet): Combinator<null> | null {
+  if (fs.kind !== 'ranges' || fs.ranges.length === 0) return null
+  const ranges = fs.ranges
+  return {
+    _tag: 'firstSetSentinel',
+    _meta: { firstSet: fs, canMatchNewline: false, isTrivia: false },
+    _def: { tag: 'unknown' },
+    parse(input: string, pos: number): ParseResult<null> {
+      const code = pos < input.length ? input.codePointAt(pos) : undefined
+      if (code !== undefined) {
+        for (const r of ranges) {
+          if (code >= r.lo && code <= r.hi) return { ok: true, value: null, span: { start: pos, end: pos } }
+        }
+      }
+      return { ok: false, expected: [], span: { start: pos, end: pos } }
+    },
+  }
+}
+
+/**
+ * Cold-path recovery scan shared by tolerant `many()` / `sepBy()`. Scans forward
+ * from `from` until `sync` matches (or EOF) — probing the sentinel as pure
+ * lookahead — emits a {@link ParseError} spanning the skipped range, and pushes it
+ * to `ctx._errors`. The sync token is NOT consumed; the caller's loop resumes from
+ * `end`. Only ever reached after an element has failed, so entirely off the hot path.
+ *
+ * The caller owns the loop guard: `sepBy` progress is driven by its separator (a
+ * zero-width error for a missing element is fine); `many` checks `matchesAt(sync)`
+ * itself and breaks when sitting on the terminator, so a zero-width failure can
+ * never spin.
+ */
+export function recoverScan(
+  input: string,
+  from: number,
+  ctx: ParseContext,
+  sync: Combinator<unknown>,
+  expected: string[],
+): { error: ParseError; end: number } {
+  let scanPos = from
+  while (scanPos < input.length && !probeAt(sync, input, scanPos, ctx)) scanPos++
+  const span = { start: from, end: scanPos }
+  if (ctx.trackLines) recordLineRangeFromContext(ctx, input, from, scanPos)
+  const error: ParseError = { _tag: 'parseError', span: ctx.trackLines ? annotateSpanFromLineContext(span, ctx) : span, expected }
+  ctx._errors?.push(error)
+  return { error, end: scanPos }
+}
+
+/**
+ * Does `sentinel` match at `pos` (pure lookahead)? Used by the tolerant list loops
+ * to detect "we are sitting on the sync/terminator token" without consuming it or
+ * capturing anything.
+ */
+export function matchesAt(
+  sentinel: Combinator<unknown>,
+  input: string,
+  pos: number,
+  ctx: ParseContext,
+): boolean {
+  return probeAt(sentinel, input, pos, ctx)
+}
+
+/**
+ * Embed a recovered error as a `parseError` CST child at the recovery point, so the
+ * error lives IN the tree (rides reused subtrees across incremental edits; a tree
+ * walk finds every diagnostic) — not only in the flat `ctx._errors` side-channel.
+ * No-op when CST capture is off (value/AST mode). Both the interpreter list loops
+ * and the compiled recovery branches call this (the latter via `_ctx._rec.capture`),
+ * so the embedded node is identical on both paths.
+ */
+export function captureError(ctx: ParseContext, error: ParseError): void {
+  if (cstCaptureActive(ctx)) pushCstChild(ctx, error, error)
+}
+
+/**
+ * The recovery-helper bundle handed to a tolerant parse via `ctx._rec`. A COMPILED
+ * grammar can't import these, so the driver (`run`, `parseDoc`) injects them; the
+ * interpreter list loops read the same bundle, guaranteeing byte-identical recovery
+ * across paths. Shared here so every driver installs the exact same instance.
+ */
+export const REC: RecoveryHelpers = { scan: recoverScan, at: matchesAt, or: orSentinel, sentinel: firstSetSentinel, capture: captureError }

package/src/regex/classes.ts

@@ -0,0 +1,183 @@
+/**
+ * Low-level regex char-class primitives, shared by every hand-rolled regex
+ * analysis in the codebase — the interpreter's first-set walker
+ * (`./first-set.ts`), `regex()`'s short-scan fast path, and codegen's scannable
+ * lowering (`../compiler/scannable-run.ts`). Kept dependency-free (no combinator,
+ * no codegen imports) so it lands in even the leanest interpreter bundle.
+ *
+ * Everything here parses a regex STRUCTURE to code-point ranges; nothing encodes
+ * a specific byte meaning ("this is whitespace"). `\d`/`\w` lower to their ASCII
+ * ranges (correct for the default, non-`u` engine); `\s` uses the fixed
+ * `SPACE_RANGES` set (unaffected by the `u` flag).
+ */
+
+/** Single-char escapes whose code point is fixed regardless of context. */
+export const CLASS_ESCAPES: Record<string, number> = { t: 9, n: 10, r: 13, f: 12, v: 11, '0': 0 }
+
+/**
+ * `\s`'s code-point set per the spec's `WhiteSpace` + `LineTerminator`
+ * productions — TAB/LF/VT/FF/CR, SPACE, NBSP, and the Unicode `Zs` space
+ * separators. Fixed regardless of the `u` flag, so always safe to lower.
+ */
+export const SPACE_RANGES: Array<[number, number]> = [
+  [9, 13], [32, 32], [160, 160], [5760, 5760], [8192, 8202],
+  [8232, 8232], [8233, 8233], [8239, 8239], [8287, 8287], [12288, 12288], [65279, 65279],
+]
+
+/**
+ * ASCII code-point ranges for the shorthand classes we lower. `\d`/`\w` are
+ * ASCII-only in the default (non-`u`) engine; `\s` maps to `SPACE_RANGES`.
+ */
+export function shorthandRanges(ch: 'd' | 'w' | 's'): Array<[number, number]> {
+  if (ch === 'd') return [[48, 57]]
+  if (ch === 's') return SPACE_RANGES
+  // Order matches the canonical `scannable-run` lowering (underscore last), so
+  // `ScanShape` output and generated code stay byte-identical. Membership is
+  // order-independent (ranges are iterated / the FirstSet union sorts), so the
+  // non-sorted order is purely representational — see PR #16 discussion.
+  return [[48, 57], [65, 90], [97, 122], [95, 95]]
+}
+
+/** `\uXXXX` at `body[i]` → its code point and the index past it, or null. */
+export function readUnicodeEscape(body: string, i: number): { cp: number; next: number } | null {
+  if (body[i] !== '\\' || body[i + 1] !== 'u') return null
+  const hex = body.slice(i + 2, i + 6)
+  if (!/^[0-9a-fA-F]{4}$/.test(hex)) return null
+  return { cp: Number.parseInt(hex, 16), next: i + 6 }
+}
+
+/** Regex syntax characters that cannot appear in a LITERAL fragment unescaped. */
+const META = new Set('()[]{}*+?|^$.'.split(''))
+
+/**
+ * A regex fragment that is a plain run of literal characters → its code points,
+ * or null when the fragment contains any operator (so a caller can never mistake
+ * `a*` for the two-char literal `a*`). An empty fragment returns null, because
+ * every caller wants "at least one char to match".
+ */
+export function literalCodePoints(frag: string): number[] | null {
+  const out: number[] = []
+  let i = 0
+  while (i < frag.length) {
+    const ch = frag[i]!
+    if (ch === '\\') {
+      const e = frag[i + 1]
+      if (e === undefined) return null
+      out.push(e in CLASS_ESCAPES ? CLASS_ESCAPES[e]! : e.codePointAt(0)!)
+      i += 2
+      continue
+    }
+    if (META.has(ch)) return null
+    out.push(ch.codePointAt(0)!)
+    i += 1
+  }
+  return out.length ? out : null
+}
+
+/**
+ * Index of the `]` that CLOSES the class opening at `body[0]`, honouring `\]`,
+ * or −1 if the class is unterminated. A leading `^` is negation, never a member;
+ * every other char up to the first unescaped `]` is. This is JS's own non-`u`
+ * reading, under which `[]` is the empty class — so in `[]]` the FIRST `]`
+ * closes and a literal `]` follows, and this returns 1, not 2.
+ */
+function classCloseIndex(body: string): number {
+  let i = 1
+  if (body[i] === '^') i++
+  while (i < body.length) {
+    const ch = body[i]
+    if (ch === '\\') { i += 2; continue }
+    if (ch === ']') return i
+    i++
+  }
+  return -1
+}
+
+/**
+ * A single-character MATCHER fragment as a (possibly negated) range set: a
+ * bracketed class `[…]`/`[^…]`, a `\d`/`\w`/`\s` shorthand, or one literal char.
+ * Anything wider (a group, a multi-char literal, `.`) returns null.
+ *
+ * "Bracketed class" means the WHOLE fragment is ONE class. Testing only that it
+ * opens with `[` and ends with `]` is a different, weaker question, and
+ * `[ \t\n\r\f]*[\$(]` answers it while being a SEQUENCE — a whitespace run, then
+ * one of `$(`. Read as a single class its members become the garbage union of
+ * everything between the OUTER brackets, whitespace and `*` and `[` included, so
+ * scss's `\+(?=[ \t\n\r\f]*[\$(])` matched a `+` before a space; the shape oracle
+ * caught it at 203 positions of the scss corpus. Every caller here asks "is this
+ * ONE char matcher", so a fragment that is not gets null — declining costs a
+ * lowering or widens a first-set to `any()`, both of which only forgo a fast
+ * path, whereas accepting yields a wrong member set, which is a wrong scan or a
+ * wrong dispatch.
+ */
+export function parseClassOperand(body: string): { ranges: Array<[number, number]>; negated: boolean } | null {
+  if (body === '\\d' || body === '\\w' || body === '\\s') {
+    return { ranges: shorthandRanges(body[1] as 'd' | 'w' | 's'), negated: false }
+  }
+  if (body.length >= 2 && body[0] === '[') {
+    // The class must close at the LAST char; anything after it is a second token
+    // (a quantifier, another class, a literal) that this fragment cannot express.
+    if (classCloseIndex(body) !== body.length - 1) return null
+    let inner = body.slice(1, -1)
+    const negated = inner.startsWith('^')
+    if (negated) inner = inner.slice(1)
+    const ranges = parseClassRanges(inner)
+    return ranges ? { ranges, negated } : null
+  }
+  const cps = literalCodePoints(body)
+  if (cps && cps.length === 1) return { ranges: [[cps[0]!, cps[0]!]], negated: false }
+  return null
+}
+
+type ClassAtom = { cp: number } | { set: Array<[number, number]> }
+
+/**
+ * Parse a regex char-class body (the chars BETWEEN `[` and `]`, negation `^`
+ * already stripped by the caller) to code-point ranges. `\d`/`\w`/`\s` expand to
+ * their ranges; `\uXXXX` and the fixed single-char escapes resolve to their code
+ * point; any other letter escape (`\D`, `\W`, `\S`, `\b`, …) returns null rather
+ * than being mis-read as a literal letter, so callers fall back to a safe
+ * over-approximation instead of a wrong set.
+ */
+export function parseClassRanges(body: string): Array<[number, number]> | null {
+  const ranges: Array<[number, number]> = []
+  let i = 0
+  const readAtom = (): ClassAtom | null => {
+    const ch = body[i]
+    if (ch === undefined) return null
+    if (ch === '\\') {
+      const uni = readUnicodeEscape(body, i)
+      if (uni) {
+        i = uni.next
+        return { cp: uni.cp }
+      }
+      const e = body[i + 1]
+      if (e === undefined) return null
+      i += 2
+      if (e in CLASS_ESCAPES) return { cp: CLASS_ESCAPES[e]! }
+      if (e === 'd' || e === 'w' || e === 's') return { set: shorthandRanges(e) }
+      // Any other letter escape is a class we can't safely lower (\D, \W, \S, …).
+      if ((e >= 'a' && e <= 'z') || (e >= 'A' && e <= 'Z')) return null
+      return { cp: e.codePointAt(0)! }
+    }
+    i += ch.length
+    return { cp: ch.codePointAt(0)! }
+  }
+  while (i < body.length) {
+    const lo = readAtom()
+    if (lo === null) return null
+    if ('set' in lo) {
+      ranges.push(...lo.set)
+      continue
+    }
+    if (body[i] === '-' && body[i + 1] !== undefined && body[i + 1] !== ']') {
+      i += 1
+      const hi = readAtom()
+      if (hi === null || 'set' in hi) return null
+      ranges.push([lo.cp, hi.cp])
+    } else {
+      ranges.push([lo.cp, lo.cp])
+    }
+  }
+  return ranges.length ? ranges : null
+}

package/src/regex/first-set.ts

@@ -0,0 +1,316 @@
+/**
+ * Hand-rolled first-set analysis for `regex()` terminals — the interpreter's
+ * replacement for the old `regexp-tree`-backed analyzer (~264 KB). A `regex()`
+ * terminal's first-set is used ONLY to let `choice()` do first-char dispatch
+ * (see `choice.ts`); it is never consulted for whether a match succeeds. So this
+ * analyzer only has to be SOUND as an OVER-approximation: every char the pattern
+ * can actually start with must be in the returned set. Any construct it can't
+ * pin down widens to `any()` (— "could start with anything" —), which only
+ * disables a dispatch fast path, never changes a parse. Under-approximating
+ * (dropping a real start char) WOULD be a bug: dispatch would skip a matching
+ * arm. The soundness fuzz test (`test/unit/regex-first-set.test.ts`) checks this
+ * against the real `RegExp` engine as an oracle.
+ *
+ * It parses the regex into a tiny AST (single-char matchers, sequence,
+ * alternation, repetition, zero-width) reusing the shared char-class primitives
+ * in `./classes.ts`, then walks the AST unioning first-sets through the nullable
+ * prefix — the same shape the `regexp-tree` walker used.
+ *
+ * Note: flags are not consulted (matching the prior `regexp-tree` seam, which
+ * parsed `/${source}/` with no flags), so an `/i` pattern's first-set is its
+ * literal-case set. Sound for dispatch because the interpreter's `/i` regex arms
+ * are compared case-sensitively at the same seam.
+ */
+import type { FirstSet } from '../types.ts'
+import { any, empty, fromRange, union } from '../combinators/first-set.ts'
+import { shorthandRanges, parseClassRanges } from './classes.ts'
+
+// A minimal regex AST. Each node answers two questions: what first chars can a
+// non-empty match begin with (`firstSet`), and can the node match zero chars
+// (`nullable`). `any` is the over-approximation sentinel for anything we don't
+// model precisely.
+type Node =
+  | { t: 'char'; set: FirstSet; nl: boolean } // matches exactly one char from `set`
+  | { t: 'any' }                              // unknown 1-char-ish construct: could start with anything
+  | { t: 'empty' }                            // zero-width: anchors, lookaround, word boundary
+  | { t: 'seq'; parts: Node[] }
+  | { t: 'alt'; arms: Node[] }
+  | { t: 'rep'; node: Node; min: number }     // quantified; min 0 ⇒ nullable
+
+const ANY: Node = { t: 'any' }
+const EMPTY: Node = { t: 'empty' }
+
+function charNode(set: FirstSet, nl: boolean): Node {
+  return { t: 'char', set, nl }
+}
+
+function rangesToSet(ranges: Array<[number, number]>): FirstSet {
+  let fs: FirstSet = empty()
+  for (const [lo, hi] of ranges) fs = union(fs, fromRange(lo, hi))
+  return fs
+}
+
+function rangesHaveNewline(ranges: Array<[number, number]>): boolean {
+  return ranges.some(([lo, hi]) => lo <= 0x0a && 0x0a <= hi)
+}
+
+// ---------------------------------------------------------------------------
+// Parser: recursive descent over a raw regex source (no surrounding delimiters).
+// Throws `Bail` on a structure it can't parse (unbalanced group/class); the
+// entry point catches it and degrades the WHOLE pattern to `any()`. A construct
+// that parses but isn't modeled (a backreference, an exotic escape) becomes an
+// `any` NODE instead — sound and more precise, since it only pollutes the
+// first-set if reached in the nullable prefix.
+// ---------------------------------------------------------------------------
+
+/** Thrown on a structure the parser can't handle (unbalanced group/class); the
+ * entry point catches it and degrades the whole pattern to `any()`. */
+const BAIL = Symbol('regex-bail')
+
+/**
+ * Parse a raw regex `src` (no delimiters) into a `Node`, or throw `BAIL`.
+ * Closure over a single cursor `i` — recursive-descent: alt → seq → quantified
+ * → atom.
+ */
+function parseRegex(src: string): Node {
+  let i = 0
+
+  const parseAlt = (): Node => {
+    const arms: Node[] = [parseSeq()]
+    while (src[i] === '|') { i++; arms.push(parseSeq()) }
+    return arms.length === 1 ? arms[0]! : { t: 'alt', arms }
+  }
+
+  const parseSeq = (): Node => {
+    const parts: Node[] = []
+    while (i < src.length) {
+      const ch = src[i]!
+      if (ch === '|' || ch === ')') break
+      parts.push(parseQuantified())
+    }
+    if (parts.length === 0) return EMPTY
+    return parts.length === 1 ? parts[0]! : { t: 'seq', parts }
+  }
+
+  const parseQuantified = (): Node => {
+    const atom = parseAtom()
+    const ch = src[i]
+    let min: number | null = null
+    if (ch === '*') { min = 0; i++ }
+    else if (ch === '+') { min = 1; i++ }
+    else if (ch === '?') { min = 0; i++ }
+    else if (ch === '{') { min = parseBraceQuantifier() }
+    if (min === null) return atom
+    // Consume a lazy `?` on the quantifier — it changes greediness, not first-set.
+    if (src[i] === '?') i++
+    return { t: 'rep', node: atom, min }
+  }
+
+  // Parse `{n}` / `{n,}` / `{n,m}` at `i` (on `{`), returning the minimum; null
+  // (leaving `{` unconsumed) if it isn't a well-formed brace quantifier, so the
+  // caller keeps the `{` as the literal atom it already parsed.
+  const parseBraceQuantifier = (): number | null => {
+    const close = src.indexOf('}', i)
+    if (close === -1) return null
+    const m = /^(\d+)(?:,(\d*))?$/.exec(src.slice(i + 1, close))
+    if (!m) return null
+    i = close + 1
+    return Number.parseInt(m[1]!, 10)
+  }
+
+  const parseAtom = (): Node => {
+    const ch = src[i]!
+    switch (ch) {
+      case '(': return parseGroup()
+      case '[': return parseClass()
+      case '.': i++; return charNode(any(), false) // `.` matches any char except line terminators
+      case '\\': return parseEscape()
+      case '^':
+      case '$': i++; return EMPTY // anchors are zero-width
+      case '{': i++; return charNode(fromRange(0x7b, 0x7b), false) // a `{` with nothing to quantify is a literal brace
+      default:
+        i += ch.length
+        return charNode(fromRange(ch.codePointAt(0)!, ch.codePointAt(0)!), ch === '\n')
+    }
+  }
+
+  const parseGroup = (): Node => {
+    i++ // consume '('
+    // Group prefixes: (?:…) (?=…) (?!…) (?<=…) (?<!…) (?<name>…)
+    let lookaround = false
+    if (src[i] === '?') {
+      const c1 = src[i + 1]
+      if (c1 === ':') i += 2
+      else if (c1 === '=' || c1 === '!') { i += 2; lookaround = true }
+      else if (c1 === '<') {
+        const c2 = src[i + 2]
+        if (c2 === '=' || c2 === '!') { i += 3; lookaround = true } // lookbehind
+        else { // named group (?<name>…): skip to '>'
+          const gt = src.indexOf('>', i)
+          if (gt === -1) throw BAIL
+          i = gt + 1
+        }
+      } else throw BAIL // (? followed by something unexpected
+    }
+    const inner = parseAlt()
+    if (src[i] !== ')') throw BAIL
+    i++ // consume ')'
+    return lookaround ? EMPTY : inner // lookaround is zero-width
+  }
+
+  const parseClass = (): Node => {
+    // Read `[ ... ]`, honoring `\]`; detect leading `^` negation.
+    let k = i + 1
+    const negated = src[k] === '^'
+    if (negated) k++
+    let body = ''
+    while (k < src.length && src[k] !== ']') {
+      if (src[k] === '\\') { body += src[k]! + (src[k + 1] ?? ''); k += 2 }
+      else { body += src[k]!; k++ }
+    }
+    if (src[k] !== ']') throw BAIL
+    i = k + 1
+    const ranges = parseClassRanges(body)
+    // A negated class can start with (almost) any char, so the first-set widens to
+    // `any`, but its newline capability is still cheap and useful to know:
+    // `[^,\r\n]*` is a workhorse "field until line end" regex and must not force
+    // line-tracking code to rescan every field.
+    if (negated) return charNode(any(), !ranges || !rangesHaveNewline(ranges))
+    if (!ranges) return charNode(any(), true) // unparseable class → widen
+    return charNode(rangesToSet(ranges), rangesHaveNewline(ranges))
+  }
+
+  const parseEscape = (): Node => {
+    const e = src[i + 1]
+    if (e === undefined) throw BAIL
+    // \uXXXX
+    if (e === 'u' && /^[0-9a-fA-F]{4}$/.test(src.slice(i + 2, i + 6))) {
+      const cp = Number.parseInt(src.slice(i + 2, i + 6), 16)
+      i += 6
+      return charNode(fromRange(cp, cp), cp === 0x0a)
+    }
+    // \xHH
+    if (e === 'x' && /^[0-9a-fA-F]{2}$/.test(src.slice(i + 2, i + 4))) {
+      const cp = Number.parseInt(src.slice(i + 2, i + 4), 16)
+      i += 4
+      return charNode(fromRange(cp, cp), cp === 0x0a)
+    }
+    i += 2
+    switch (e) {
+      case 'd': return charNode(rangesToSet(shorthandRanges('d')), false)
+      case 'w': return charNode(rangesToSet(shorthandRanges('w')), false)
+      case 's': return charNode(rangesToSet(shorthandRanges('s')), true)
+      case 'D': case 'W': case 'S': return charNode(any(), true) // negated shorthand → widen
+      case 'b': case 'B': return EMPTY // word boundary: zero-width
+      case 'n': return charNode(fromRange(0x0a, 0x0a), true)
+      case 'r': return charNode(fromRange(0x0d, 0x0d), false)
+      case 't': return charNode(fromRange(0x09, 0x09), false)
+      case 'f': return charNode(fromRange(0x0c, 0x0c), false)
+      case 'v': return charNode(fromRange(0x0b, 0x0b), false)
+      case '0': return charNode(fromRange(0, 0), false)
+      default:
+        // A digit escape is a backreference we don't resolve → widen.
+        if (e >= '1' && e <= '9') return ANY
+        // Any other escape is a literal char (escaped metachar, `\/`, etc.).
+        return charNode(fromRange(e.codePointAt(0)!, e.codePointAt(0)!), e === '\n')
+    }
+  }
+
+  const node = parseAlt()
+  if (i < src.length) throw BAIL // leftover (e.g. an unbalanced `)`)
+  return node
+}
+
+// ---------------------------------------------------------------------------
+// Walkers over the AST.
+// ---------------------------------------------------------------------------
+
+/** Can `n` succeed consuming zero characters? Err toward `true` when unsure —
+ * over-estimating nullability only widens the (over-approximated) first-set. */
+function nullable(n: Node): boolean {
+  switch (n.t) {
+    case 'char': return false
+    case 'any': return true
+    case 'empty': return true
+    case 'seq': return n.parts.every(nullable)
+    case 'alt': return n.arms.some(nullable)
+    case 'rep': return n.min === 0 || nullable(n.node)
+  }
+}
+
+/** First chars a non-empty match of `n` can begin with (over-approximated). */
+function firstSet(n: Node): FirstSet {
+  switch (n.t) {
+    case 'char': return n.set
+    case 'any': return any()
+    case 'empty': return empty()
+    case 'rep': return firstSet(n.node)
+    case 'alt': {
+      let fs: FirstSet = empty()
+      for (const arm of n.arms) fs = union(fs, firstSet(arm))
+      return fs
+    }
+    case 'seq': {
+      // Union each part's first-set through the nullable prefix: a leading
+      // nullable part lets a LATER part's first chars start the sequence.
+      let fs: FirstSet = empty()
+      for (const part of n.parts) {
+        fs = union(fs, firstSet(part))
+        if (!nullable(part)) break
+      }
+      return fs
+    }
+  }
+}
+
+/** Whether a successful match can consume a newline anywhere. This is tracked
+ * separately from `firstSet`: dispatch only cares about the first consumed char,
+ * while optional line tracking cares whether the matched span needs scanning. */
+function canConsumeNewline(n: Node): boolean {
+  switch (n.t) {
+    case 'char': return n.nl
+    case 'any': return true
+    case 'empty': return false
+    case 'rep': return canConsumeNewline(n.node)
+    case 'alt': return n.arms.some(canConsumeNewline)
+    case 'seq': return n.parts.some(canConsumeNewline)
+  }
+}
+
+/**
+ * Compute a regex terminal's first-set and newline-start flag from its SOURCE
+ * (no delimiters, no flags). Over-approximates: an unparseable pattern degrades
+ * to `{ any, canMatchNewline: true }` — the same conservative value the prior
+ * `regexp-tree` seam returned on a parse failure.
+ */
+/**
+ * Can `source` match ZERO characters?
+ *
+ * Structural, over the same AST `firstSetFromRegex` uses — which already models
+ * every zero-width construct as `EMPTY`: anchors (`^`/`$`), lookaround
+ * (`(?=…)`/`(?!…)`/`(?<=…)`/`(?<!…)`) and word boundaries. That is what makes
+ * this usable as a proof of consumption: a pattern is zero-width exactly when
+ * the AST says it is nullable, so a lookaround BURIED inside an otherwise
+ * mandatory pattern no longer taints the whole answer.
+ *
+ * Errs toward `true` (nullable) — an unparseable pattern is assumed able to
+ * match empty, so callers that delete code on a `false` keep their proof.
+ */
+export function regexCanMatchEmpty(source: string): boolean {
+  try { return nullable(parseRegex(source)) } catch { return true }
+}
+
+export function firstSetFromRegex(source: string): { firstSet: FirstSet; canMatchNewline: boolean } {
+  let ast: Node
+  try {
+    ast = parseRegex(source)
+  } catch {
+    return { firstSet: any(), canMatchNewline: true }
+  }
+  // A NULLABLE pattern (can match zero chars) must widen to `any()`: as a
+  // `choice()` arm it can succeed with an empty match at ANY position, so a
+  // narrow first-set would let first-char dispatch wrongly skip it. Only a
+  // pattern that must consume ≥1 char has a meaningful first-set.
+  if (nullable(ast)) return { firstSet: any(), canMatchNewline: canConsumeNewline(ast) }
+  return { firstSet: firstSet(ast), canMatchNewline: canConsumeNewline(ast) }
+}

package/src/run/index.ts

@@ -0,0 +1,31 @@
+/**
+ * `parseman/run` — the minimal entry for EXECUTING an already-compiled grammar.
+ *
+ * The macro removes the combinators, the compiler and the codegen from your
+ * bundle, but not the driver: running a compiled grammar is still a `run()` call,
+ * so a package that SHIPS a parser keeps a runtime import of parseman. Importing
+ * that driver from the main entry drags the whole library along — the combinator
+ * set, `compile()`, the first-set analysis, the CST builders — none of which a
+ * compiled parser touches.
+ *
+ * This entry exists so it doesn't have to. `run()`'s complete module closure is
+ * intentionally tiny (this, `functional/run.ts`, recovery helpers, CST capture /
+ * trivia views, host-mode checks, and the line-index helper) — a fraction of the
+ * main entry.
+ * `test/unit/run-entry-closure.test.ts` asserts that stays true, so a future
+ * import into `functional/run.ts` that widens the closure fails the suite rather
+ * than quietly re-inflating everyone's bundle.
+ *
+ * Use the main entry when you BUILD grammars; use this one when you only run
+ * output the macro (or `compile()`) already produced.
+ *
+ *   import { run } from 'parseman/run'
+ *   import { myGrammar } from './grammar.js'   // macro-compiled
+ *
+ *   const result = run(myGrammar, source, { trivia })
+ */
+export { buildRootTriviaIndex } from '../cst/trivia-entries.ts'
+export { run } from '../functional/run.ts'
+export type { RootTriviaCapture, Runnable, RunOptions, RunResult } from '../functional/run.ts'
+export type { RootTriviaGap, RootTriviaIndex, TriviaEntriesView } from '../cst/trivia-entries.ts'
+export type { ParseContext, ParseError, ParseResult } from '../types.ts'