parseman 0.45.0 → 0.47.0

package/src/cst/trivia-index.ts

@@ -0,0 +1,131 @@
+import type { Span } from '../types.ts'
+
+/** One captured trivia token (a whitespace run or a comment) with its source span. */
+export type TriviaToken = { readonly value: string; readonly span: Span }
+
+/**
+ * Before/after offset index of captured trivia. Built from a tree whose nodes
+ * carry a `triviaLog` property (the flat `[start, end, insertIdx, ...]` array
+ * produced by parseman when `parser({ captureTrivia: true })` wraps a `node()` grammar).
+ *
+ *   index.before.get(node.span.start)  // trivia immediately before a node
+ *   index.after.get(node.span.end)     // trivia immediately after a node
+ *
+ * A given trivia entry is registered under BOTH the following item's start
+ * (`before`) and the preceding item's end (`after`), so either lookup finds it.
+ */
+export type TriviaIndex = {
+  readonly before: Map<number, TriviaToken[]>
+  readonly after: Map<number, TriviaToken[]>
+}
+
+type Spanned = { readonly span: Span }
+type NodeWithTrivia = {
+  readonly span?: Span
+  readonly children?: ReadonlyArray<unknown>
+  readonly rawChildren?: ReadonlyArray<Spanned>
+  readonly triviaLog?: readonly number[]
+}
+
+function merge(map: Map<number, TriviaToken[]>, key: number, run: TriviaToken[]): void {
+  if (run.length === 0) return
+  const existing = map.get(key)
+  if (existing) existing.push(...run)
+  else map.set(key, [...run])
+}
+
+/**
+ * Options for trailing/leading trivia at the document boundary. A repeating root
+ * (e.g. `many()`) rolls back the trivia after its last item — it's "trailing" and
+ * belongs to the enclosing context, which at the document root is the document
+ * itself. Pass `{ trivia }` to re-scan and register that boundary trivia,
+ * so a round-trippable trivia map isn't missing the run before EOF.
+ */
+export type TriviaIndexOptions = {
+  /**
+   * A regex matching ONE trivia token (a whitespace run or a comment). Applied
+   * repeatedly to tokenize the boundary trivia. Each match becomes one token, so
+   * write it to match a maximal run, e.g.
+   * `/[ \t\n\r\f]+|\/\*(?:[^*]|\*(?!\/))*\*\//`.
+   */
+  trivia: RegExp
+}
+
+/**
+ * Walk a tree whose nodes carry `triviaLog` (from `node()` + `captureTrivia`)
+ * and build a before/after trivia index. Each node must have
+ * `triviaLog: readonly number[]` (flat `[start, end, insertIdx, …]` —
+ * three numbers per entry) and `rawChildren` (structural items with `.span`).
+ * `input` is the source string used to materialize trivia values.
+ *
+ * With `opts`, also captures leading trivia (before the root's content) and
+ * trailing trivia (after it, up to EOF) — the document boundaries a repeating
+ * root rolls back.
+ */
+export function buildTriviaIndex(root: unknown, input = '', opts?: TriviaIndexOptions): TriviaIndex {
+  const before = new Map<number, TriviaToken[]>()
+  const after = new Map<number, TriviaToken[]>()
+
+  const visit = (node: NodeWithTrivia): void => {
+    const log = node.triviaLog
+    const raw = node.rawChildren
+
+    if (log && log.length && raw) {
+      for (let i = 0; i < log.length; i += 3) {
+        const tStart = log[i]!, tEnd = log[i + 1]!, insertIdx = log[i + 2]!
+        if (tEnd <= tStart) continue
+        const run: TriviaToken[] = [{ value: input.slice(tStart, tEnd), span: { start: tStart, end: tEnd } }]
+        const next = raw[insertIdx]
+        if (next) merge(before, next.span.start, run)
+        const prev = insertIdx > 0 ? raw[insertIdx - 1] : undefined
+        if (prev) merge(after, prev.span.end, run)
+      }
+    }
+
+    const ch = node.children
+    if (ch) {
+      for (const c of ch) {
+        if (typeof c === 'object' && c !== null && (c as NodeWithTrivia).children !== undefined) {
+          visit(c as NodeWithTrivia)
+        }
+      }
+    }
+  }
+
+  if (root) visit(root as NodeWithTrivia)
+
+  // Document-boundary trivia: re-scan leading (offset 0) and trailing (root end
+  // → EOF) trivia that a repeating root rolled back.
+  if (opts && input) {
+    const rootSpan = (root as NodeWithTrivia | null)?.span
+    const re = new RegExp(opts.trivia.source, opts.trivia.flags.replace(/[gy]/g, '') + 'y')
+    const scanFrom = (from: number): TriviaToken[] => {
+      const run: TriviaToken[] = []
+      let pos = from
+      re.lastIndex = pos
+      let m = re.exec(input)
+      while (m && m.index === pos && m[0].length > 0) {
+        run.push({ value: m[0], span: { start: pos, end: pos + m[0].length } })
+        pos += m[0].length
+        re.lastIndex = pos
+        m = re.exec(input)
+      }
+      return run
+    }
+
+    if (rootSpan && rootSpan.start > 0) {
+      const lead = scanFrom(0)
+      if (lead.length) merge(before, rootSpan.start, lead)
+    }
+    const end = rootSpan ? rootSpan.end : 0
+    if (end < input.length) {
+      const trail = scanFrom(end)
+      if (trail.length) {
+        merge(after, end, trail)
+        merge(before, end + trail.reduce((n, t) => n + (t.span.end - t.span.start), 0), trail)
+      }
+    }
+  }
+
+  return { before, after }
+}

package/src/cst/trivia-kinds.ts

@@ -0,0 +1,358 @@
+import type { Combinator, ParseContext } from '../types.ts'
+import { pushCstTriviaEntry, pushTriviaLogEntry } from './capture-buffer.ts'
+import { startsFirstSet } from '../combinators/first-set.ts'
+import { createDetachedParseContext } from '../parse-context.ts'
+import { charArmsFor, charTriviaEnd, charTriviaKindMask, charTriviaVisit } from './trivia-charscan.ts'
+
+export type TriviaChunk = { start: number; end: number; kindIndex: number }
+
+export type LabeledTriviaSpec = {
+  readonly labels: readonly string[]
+  readonly arms: ReadonlyArray<{ label: string; kindIndex: number; parser: Combinator<unknown> }>
+  readonly minRepeats: number
+}
+
+/** See `trivia-skip.ts`: bounded scalar memoisation avoids a WeakMap in the
+ * shipped table runtime while retaining the common trivia grammars. */
+let labeledTrivia0: Combinator<unknown> | undefined
+let labeledTrivia1: Combinator<unknown> | undefined
+let labeledTrivia2: Combinator<unknown> | undefined
+let labeledTrivia3: Combinator<unknown> | undefined
+let labeledSpec0: LabeledTriviaSpec | null | undefined
+let labeledSpec1: LabeledTriviaSpec | null | undefined
+let labeledSpec2: LabeledTriviaSpec | null | undefined
+let labeledSpec3: LabeledTriviaSpec | null | undefined
+
+function cacheLabeledTrivia(trivia: Combinator<unknown>, spec: LabeledTriviaSpec | null): LabeledTriviaSpec | null {
+  labeledTrivia3 = labeledTrivia2
+  labeledSpec3 = labeledSpec2
+  labeledTrivia2 = labeledTrivia1
+  labeledSpec2 = labeledSpec1
+  labeledTrivia1 = labeledTrivia0
+  labeledSpec1 = labeledSpec0
+  labeledTrivia0 = trivia
+  labeledSpec0 = spec
+  return spec
+}
+
+function unwrapTrivia(p: Combinator<unknown>): Combinator<unknown> {
+  let cur = p
+  while (cur._def.tag === 'trivia') cur = cur._def.parser
+  return cur
+}
+
+/** Strip `label()` wrapper; returns inner parser for matching. */
+export function peelLabel(p: Combinator<unknown>): { label: string; parser: Combinator<unknown> } | null {
+  if (p._def.tag === 'label') return { label: p._def.label, parser: p._def.parser }
+  return null
+}
+
+/**
+ * When every trivia arm is `label(name, parser)` inside `oneOrMore(choice(…))`
+ * (or a single labeled arm), return the label table and matchers.
+ */
+export function analyzeLabeledTrivia(trivia: Combinator<unknown>): LabeledTriviaSpec | null {
+  if (trivia === labeledTrivia0) return labeledSpec0!
+  if (trivia === labeledTrivia1) return labeledSpec1!
+  if (trivia === labeledTrivia2) return labeledSpec2!
+  if (trivia === labeledTrivia3) return labeledSpec3!
+
+  let core = unwrapTrivia(trivia)
+  let minRepeats = 1
+
+  if (core._def.tag === 'oneOrMore') {
+    const min = core._def.min
+    core = core._def.parser
+    minRepeats = min
+  } else if (core._def.tag === 'many') {
+    core = core._def.parser
+    minRepeats = 0
+  }
+
+  const arms: LabeledTriviaSpec['arms'][number][] = []
+
+  if (core._def.tag === 'choice') {
+    for (let i = 0; i < core._def.parsers.length; i++) {
+      const peeled = peelLabel(core._def.parsers[i]!)
+      if (!peeled) {
+        return cacheLabeledTrivia(trivia, null)
+      }
+      arms.push({ label: peeled.label, kindIndex: i, parser: peeled.parser })
+    }
+  } else {
+    const peeled = peelLabel(core)
+    if (!peeled) {
+      return cacheLabeledTrivia(trivia, null)
+    }
+    arms.push({ label: peeled.label, kindIndex: 0, parser: peeled.parser })
+  }
+
+  const spec = {
+    labels: arms.map(a => a.label),
+    arms,
+    minRepeats,
+  }
+  return cacheLabeledTrivia(trivia, spec)
+}
+
+/** Label table on a `trivia()` combinator, if all arms are labeled. */
+export function triviaKindLabels(trivia: Combinator<unknown> | undefined): readonly string[] | undefined {
+  if (!trivia) return undefined
+  const fromMeta = trivia._meta.triviaKindLabels
+  if (fromMeta) return fromMeta
+  return analyzeLabeledTrivia(trivia)?.labels
+}
+
+function matchArmAt(
+  input: string,
+  pos: number,
+  arm: Combinator<unknown>,
+  state: unknown,
+): { end: number } | null {
+  // The first-set check is structural Parseman metadata. It neither assigns
+  // meaning to a label nor recognizes a particular comment form; it avoids
+  // entering arms whose own grammar proves they cannot start at this offset.
+  if (!startsFirstSet(arm, input, pos)) return null
+  const r = arm.parse(input, pos, createDetachedParseContext(false, state))
+  if (!r.ok || r.span.end <= pos) return null
+  return { end: r.span.end }
+}
+
+/**
+ * Scan maximal labeled trivia chunks (PEG `oneOrMore(choice(…))` semantics).
+ * Each successful arm match becomes one entry with that arm's kind index.
+ */
+export function scanLabeledTriviaChunks(
+  input: string,
+  cur: number,
+  spec: LabeledTriviaSpec,
+  state?: unknown,
+): { end: number; chunks: TriviaChunk[] } {
+  const chunks: TriviaChunk[] = []
+  let pos = cur
+
+  while (pos < input.length) {
+    let matched: { end: number; kindIndex: number } | null = null
+    for (const arm of spec.arms) {
+      const m = matchArmAt(input, pos, arm.parser, state)
+      if (m) {
+        matched = { end: m.end, kindIndex: arm.kindIndex }
+        break
+      }
+    }
+    if (!matched) break
+    chunks.push({ start: pos, end: matched.end, kindIndex: matched.kindIndex })
+    pos = matched.end
+  }
+
+  if (chunks.length < spec.minRepeats) {
+    return { end: cur, chunks: [] }
+  }
+  return { end: pos, chunks }
+}
+
+/**
+ * Scan labeled trivia when no caller will retain individual chunks. This is the
+ * ordinary skip path for a classified grammar: labels remain available for an
+ * explicit capture request, but merely having labels must not allocate one
+ * `{ start, end, kindIndex }` object per whitespace/comment run.
+ */
+export function scanLabeledTriviaEnd(
+  input: string,
+  cur: number,
+  spec: LabeledTriviaSpec,
+  state?: unknown,
+): number {
+  // `charArmsFor` only lowers `minRepeats <= 1`, where "no chunk matched" and
+  // "the minimum was not met" are the same position — so an end IS the answer.
+  const chars = charArmsFor(spec)
+  if (chars !== null) return charTriviaEnd(input, cur, chars)
+
+  let pos = cur
+  let count = 0
+
+  while (pos < input.length) {
+    let matched: { end: number } | null = null
+    for (const arm of spec.arms) {
+      matched = matchArmAt(input, pos, arm.parser, state)
+      if (matched) break
+    }
+    if (!matched) break
+    pos = matched.end
+    count++
+  }
+
+  return count < spec.minRepeats ? cur : pos
+}
+
+/**
+ * Visit classified trivia matches without constructing per-match objects. The
+ * visitor is only invoked after one or more arms matched, which is the shape
+ * used by `classifiedTrivia()`; callers with a stronger repeat minimum keep
+ * the buffered scanner so an unsuccessful minimum cannot leak a partial run.
+ */
+export function visitLabeledTrivia(
+  input: string,
+  cur: number,
+  spec: LabeledTriviaSpec,
+  state: unknown | undefined,
+  visit: (start: number, end: number, kindIndex: number) => void,
+): number | undefined {
+  if (spec.minRepeats > 1) return undefined
+  const chars = charArmsFor(spec)
+  if (chars !== null) return charTriviaVisit(input, cur, chars, visit)
+
+  let pos = cur
+  let count = 0
+
+  while (pos < input.length) {
+    let matched: { end: number; kindIndex: number } | null = null
+    for (const arm of spec.arms) {
+      const match = matchArmAt(input, pos, arm.parser, state)
+      if (match) {
+        matched = { end: match.end, kindIndex: arm.kindIndex }
+        break
+      }
+    }
+    if (!matched) break
+    visit(pos, matched.end, matched.kindIndex)
+    pos = matched.end
+    count++
+  }
+
+  return count < spec.minRepeats ? cur : pos
+}
+
+export function recordTriviaChunks(ctx: ParseContext, chunks: readonly TriviaChunk[]): void {
+  const kinds = ctx.triviaKindLabels
+  const mask = ctx._triviaCaptureMask
+  const rootLog = ctx._rootTriviaLog
+  const rootKinds = ctx._rootTriviaKindIndex
+  const rootMark = rootLog?.length ?? 0
+  for (const ch of chunks) {
+    // Global trivia log: always complete (never kind-filtered).
+    pushTriviaLogEntry(ctx, ch.start, ch.end, kinds ? ch.kindIndex : undefined)
+    const rootKindIndex = ctx._rootTriviaCapture === false || rootLog === undefined || rootKinds === undefined || kinds === undefined
+      ? -1
+      : (rootKinds[kinds[ch.kindIndex] ?? ''] ?? -1)
+    if (rootKindIndex >= 0) {
+      // Fill the enclosing committed gap after the scanner has consumed every
+      // chunk. A selected marker therefore carries its exact authored context
+      // without recording any whitespace-only chunk.
+      rootLog!.push(0, 0, ch.start, ch.end, rootKindIndex)
+    }
+    // Per-node CST log: honour the kind mask when both a mask and labels are
+    // present, so a host can capture (e.g.) comments only without logging every
+    // whitespace run. No mask / no labels → capture everything, as before.
+    if (ctx.captureTrivia && (ctx._cstBuf !== undefined || ctx._cstTriviaLog !== undefined)) {
+      if (mask === undefined || kinds === undefined || (mask & (1 << ch.kindIndex)) !== 0) {
+        pushCstTriviaEntry(ctx, ch.start, ch.end, kinds ? ch.kindIndex : undefined)
+      }
+    }
+  }
+  if (rootLog !== undefined && rootLog.length !== rootMark && chunks.length > 0) {
+    const start = chunks[0]!.start
+    const end = chunks[chunks.length - 1]!.end
+    for (let offset = rootMark; offset < rootLog.length; offset += 5) {
+      rootLog[offset] = start
+      rootLog[offset + 1] = end
+    }
+  }
+}
+
+/**
+ * Resolve a per-node trivia capture mask (`ctx._triviaCaptureMask`) from a trivia
+ * label table and the kind names a host wants to keep. Returns `undefined` when
+ * `labels` is absent (nothing to key on → capture everything).
+ *
+ * Names in `keep` that aren't in `labels` are **ignored by design**: `keep` is
+ * often a dialect-independent list (e.g. `['blockComment', 'lineComment']`) applied
+ * to a grammar whose trivia only defines some of them (CSS has no `lineComment`) —
+ * so an unknown name is a normal cross-dialect no-op, not necessarily a typo, and
+ * is not worth a warning that would cry wolf on legitimate superset lists. An empty
+ * `keep` (or one where nothing matches) yields `0`, which means "capture NO trivia
+ * into per-node logs" — an intentional, valid state (the global `_triviaLog` is
+ * unaffected either way). If you expect comments and get an empty per-node log,
+ * check the name against the grammar's `triviaKindLabels`.
+ */
+/**
+ * Resolve an ADJACENCY kind filter against the ACTIVE trivia table — the strict
+ * counterpart of `triviaKindMask` below.
+ *
+ * Deliberately NOT lenient. `triviaKindMask` is a capture preference, where an
+ * unknown name is a legitimate cross-dialect no-op; this is a RECOGNITION
+ * constraint, and a silently-dropped name turns `notAdjacent({kinds:['whitespace']})`
+ * into a bare `notAdjacent()` — i.e. `calc()` quietly accepting a comment where
+ * css-values-4 10.1 demands real whitespace, the exact defect the filter exists to
+ * prevent. Both failure modes are hard errors.
+ */
+export function resolveAdjacencyKindMask(
+  trivia: Combinator<unknown> | undefined,
+  kinds: readonly string[],
+): number {
+  const spec = trivia ? analyzeLabeledTrivia(trivia) : null
+  if (!spec) {
+    throw new TypeError(
+      `notAdjacent({ kinds: [${kinds.map(k => JSON.stringify(k)).join(', ')}] }) requires classified trivia: `
+      + 'the active trivia table has no category labels. Build it with classifiedTrivia({ whitespace: …, comment: … }).',
+    )
+  }
+  let mask = 0
+  for (const name of kinds) {
+    const idx = spec.labels.indexOf(name)
+    if (idx < 0) {
+      throw new TypeError(
+        `notAdjacent(): unknown trivia kind ${JSON.stringify(name)}. `
+        + `The active trivia table declares: ${spec.labels.map(l => JSON.stringify(l)).join(', ')}.`,
+      )
+    }
+    mask |= 1 << idx
+  }
+  return mask
+}
+
+/**
+ * Bitmask of the trivia CATEGORIES occurring in the run starting at `pos`
+ * (`1 << kindIndex` per matched chunk); `0` when no trivia is there at all.
+ * The single source of truth for the interpreter's adjacency kind test — the
+ * compiled probe (`_akN`) mirrors this loop arm for arm.
+ */
+export function triviaKindMaskAt(
+  input: string,
+  pos: number,
+  spec: LabeledTriviaSpec,
+  state?: unknown,
+): number {
+  const chars = charArmsFor(spec)
+  if (chars !== null) return charTriviaKindMask(input, pos, chars)
+
+  let cur = pos
+  let mask = 0
+  while (cur < input.length) {
+    let matched: { end: number; kindIndex: number } | null = null
+    for (const arm of spec.arms) {
+      const m = matchArmAt(input, cur, arm.parser, state)
+      if (m) {
+        matched = { end: m.end, kindIndex: arm.kindIndex }
+        break
+      }
+    }
+    if (!matched) break
+    mask |= 1 << matched.kindIndex
+    cur = matched.end
+  }
+  return mask
+}
+
+export function triviaKindMask(
+  labels: readonly string[] | undefined,
+  keep: readonly string[],
+): number | undefined {
+  if (!labels) return undefined
+  let mask = 0
+  for (const name of keep) {
+    const idx = labels.indexOf(name)
+    if (idx >= 0) mask |= 1 << idx
+  }
+  return mask
+}

package/src/cst/types.ts

@@ -0,0 +1,76 @@
+import type { Span } from '../types.ts'
+
+/**
+ * Minimal interface a node must satisfy for incremental re-parse to navigate and
+ * re-parse the tree. Any object with `_tag: 'node'`, `type`, `span`, `state`,
+ * and `children` works — whether from `node()` build callbacks or custom ASTs.
+ *
+ * `children` only needs items with `_tag` so traversal can distinguish sub-nodes
+ * from leaves. `parseDoc` uses an optional `rebuild` callback (or a
+ * shallow spread) when grafting a re-parsed subtree.
+ */
+export type NodeLike = {
+  readonly _tag: 'node'
+  readonly type: string
+  readonly span: Span
+  readonly state: unknown
+  readonly children: ReadonlyArray<{ readonly _tag: string }>
+}
+
+/**
+ * A named CST node from a `node()` rule (or equivalent build callback).
+ * Children are in parse order: sub-nodes interspersed with CSTLeaf terminals.
+ */
+export type CSTNode = {
+  readonly _tag: 'node'
+  /** Rule name — the method name that produced this node. */
+  readonly type: string
+  /** Optional grammar categories materialized by `cstBuildHost({ tags: true })`. */
+  readonly tags?: readonly string[]
+  readonly span: Span
+  readonly children: CSTChild[]
+  /**
+   * Shallow clone of ctx.state at the moment this node's parse began.
+   * Used as the re-entry point for incremental re-parsing.
+   * Only meaningful when ctx.state is primitives-only (no mutable objects).
+   */
+  readonly state: unknown
+}
+
+/**
+ * A terminal token — the result of a literal() or regex() match inside a node rule.
+ */
+export type CSTLeaf = {
+  readonly _tag: 'leaf'
+  readonly value: string
+  readonly span: Span
+}
+
+/**
+ * A recovered parse error embedded in the tree at a recovery point (tolerant
+ * parsing). Spans exactly the skipped text; `expected` is what the grammar wanted
+ * there. Identical shape to the runtime `ParseError`, so recovery emits ONE value
+ * into both the CST `children` and the flat `ctx._errors` channel. A tree walk
+ * finds every diagnostic, and — because it rides in the tree — an incremental
+ * reuse keeps it attached to the untouched subtree it belongs to.
+ */
+export type CSTError = {
+  readonly _tag: 'parseError'
+  readonly span: Span
+  readonly expected: string[]
+}
+
+export type CSTChild = CSTNode | CSTLeaf | CSTError
+
+/**
+ * A trivia token — whitespace or comment consumed between terms during parsing.
+ * Only present in `rawChildren`; never in the structural `children` array.
+ */
+export type CSTTrivia = {
+  readonly _tag: 'trivia'
+  readonly value: string
+  readonly span: Span
+}
+
+/** Full child union including trivia — used in the `rawChildren` arg of `buildNode`. */
+export type CSTRawChild = CSTNode | CSTLeaf | CSTTrivia | CSTError

package/src/cst/walk.ts

@@ -0,0 +1,101 @@
+/**
+ * Grammar-aware CST traversal. `createVisitor(grammar, handlers)` consumes the
+ * reflection stamped on interpreted `rules()` maps and macro/compiled grammar
+ * maps, precomputes tag dispatch once, and returns a reusable `visit(root)` fn.
+ */
+import type { CSTChild, CSTNode } from './types.ts'
+import type { Combinator } from '../types.ts'
+import {
+  collectGrammarReflection,
+  grammarReflectionOf,
+  type GrammarWithReflection,
+} from './reflection.ts'
+
+export type Walkable = {
+  readonly _tag: string
+  readonly type?: string
+  readonly children?: ReadonlyArray<Walkable>
+}
+
+type GrammarNodeType<G> =
+  G extends GrammarWithReflection<infer NodeType, string>
+    ? NodeType
+    : G extends Record<string, unknown>
+      ? Extract<keyof G, string>
+      : string
+
+type GrammarNodeTag<G> =
+  G extends GrammarWithReflection<string, infer NodeTag> ? NodeTag : never
+
+type NodeForType<N extends Walkable, Type extends string> =
+  Extract<N, { readonly _tag: 'node' }> extends never
+    ? CSTNode & { readonly type: Type }
+    : Extract<N, { readonly _tag: 'node' }> & { readonly type: Type }
+
+export type VisitorHandler<N extends Walkable, Root extends Walkable = CSTChild, C = undefined> =
+  (node: N, parent: Root | null, ctx: C) => void
+
+export type VisitorSpec<G, N extends Walkable = CSTChild, C = undefined> = {
+  enter?(node: N, parent: N | null, ctx: C): boolean | void
+  leave?(node: N, parent: N | null, ctx: C): void
+  type?: {
+    [K in GrammarNodeType<G>]?: VisitorHandler<NodeForType<N, K>, N, C>
+  }
+  tag?: {
+    [K in GrammarNodeTag<G>]?: VisitorHandler<NodeForType<N, GrammarNodeType<G>>, N, C>
+  }
+}
+
+function isCombinator(value: unknown): value is Combinator<unknown> {
+  return !!value && typeof value === 'object'
+    && '_def' in value
+    && '_meta' in value
+    && typeof (value as { parse?: unknown }).parse === 'function'
+}
+
+function reflectionFor(grammar: object) {
+  const stamped = grammarReflectionOf(grammar)
+  if (stamped) return stamped
+  const entries = Object.entries(grammar).filter((entry): entry is [string, Combinator<unknown>] => isCombinator(entry[1]))
+  return collectGrammarReflection(entries)
+}
+
+export function createVisitor<G extends object, N extends Walkable = CSTChild, C = undefined>(
+  grammar: G,
+  spec: VisitorSpec<G, N, C>,
+): (root: N, ctx?: C) => void {
+  const reflection = reflectionFor(grammar)
+  const typeHandlers = spec.type as Record<string, VisitorHandler<N, N, C> | undefined> | undefined
+  const tagSpec = spec.tag as Record<string, VisitorHandler<N, N, C> | undefined> | undefined
+  const tagHandlersByType = new Map<string, Array<VisitorHandler<N, N, C>>>()
+
+  if (tagSpec !== undefined) {
+    for (const node of reflection.nodes) {
+      const handlers: Array<VisitorHandler<N, N, C>> = []
+      for (const tag of node.tags) {
+        const handler = tagSpec[tag]
+        if (handler) handlers.push(handler)
+      }
+      if (handlers.length > 0) tagHandlersByType.set(node.type, handlers)
+    }
+  }
+
+  return (root: N, ctx: C = undefined as C): void => {
+    const go = (node: N, parent: N | null): void => {
+      const descend = spec.enter ? spec.enter(node, parent, ctx) : undefined
+      if (node._tag === 'node' && node.type !== undefined) {
+        typeHandlers?.[node.type]?.(node, parent, ctx)
+        const tagHandlers = tagHandlersByType.get(node.type)
+        if (tagHandlers !== undefined) {
+          for (const handler of tagHandlers) handler(node, parent, ctx)
+        }
+      }
+      const children = node.children as ReadonlyArray<N> | undefined
+      if (descend !== false && Array.isArray(children)) {
+        for (const child of children) go(child, node)
+      }
+      spec.leave?.(node, parent, ctx)
+    }
+    go(root, null)
+  }
+}