parseman 0.45.0 → 0.47.0

package/src/combinators/node.ts

@@ -0,0 +1,345 @@
+import type { Combinator, FieldMap, ParseContext, ParseResult, ParserMeta, ParserDef } from '../types.ts'
+import { beginCstNodeCapture, endCstNodeCapture, pushCstChild } from '../cst/capture-buffer.ts'
+import { buildReadsTrivia, buildReadsState, cstOutputHost } from '../compiler/build-arity.ts'
+import { buildFieldMap, buildReadsFields, parserHasOwnFields } from '../compiler/fields.ts'
+import { consumeTrivia } from './trivia-skip.ts'
+import { matchesEmpty, startsFirstSet } from './first-set.ts'
+import { deriveExpected } from './expect.ts'
+import { annotateSpanFromLineContext } from '../line-index.ts'
+import { NODE_TAG, NODE_TYPE } from '../cst/reflection-symbols.ts'
+
+/**
+ * A CST/AST node rule. Runs `combinator` while collecting its terminals into
+ * `children` / `rawChildren` arrays and trivia spans into `triviaLog`, then
+ * calls `build(children, fields, span, rawChildren, triviaLog, state)` to produce the node.
+ *
+ *   - `children`    — structural items in source order: spanned CSTLeaf terminals
+ *                     and sub-nodes (whatever `build` returned for inner nodes).
+ *   - `rawChildren` — structural children only (same items as `children`).
+ *   - `triviaLog`   — flat log of trivia entries: each entry is `[start, end, insertIdx]`
+ *                     consumed between terms. `insertIdx` is the rawChildren index
+ *                     before which the trivia was consumed. Use `buildTriviaIndex`
+ *                     to turn this into a before/after lookup table.
+ *
+ * If `build` returns a non-node value (e.g. a bare string for an unwrapped rule),
+ * the parent records it as a spanned leaf so its source span is still recoverable.
+ */
+export type BuildNode<N> = (
+  children: ReadonlyArray<unknown>,
+  fields: FieldMap | undefined,
+  span: { start: number; end: number },
+  rawChildren: ReadonlyArray<unknown>,
+  triviaLog: readonly number[],
+  state: unknown,
+) => N
+
+/**
+ * Options for `node()`.
+ * - `unwrap` — an AST/value wrapper rule that IS its single child when it
+ *   captured exactly one. A leaf unwraps to its string value; a sub-node is
+ *   returned as-is.
+ * - `collapse` — a structural wrapper rule that returns its single child exactly
+ *   as captured. A leaf stays a CSTLeaf; a node stays a node.
+ * - `project` — return one captured semantic child by index while retaining the
+ *   complete node frame for CST hosts. Leaves unwrap to their string value.
+ * - `captureTrivia` — capture trivia consumed inside this node even when its
+ *   enclosing `parser()` did not opt into document-wide trivia capture. This is
+ *   scoped to the node; sibling and parent nodes retain their own setting.
+ * - `trailingTrivia` — after a successful node body, consume the active grammar
+ *   trivia once into THIS node's log. Intended for a document root whose body is
+ *   a repetition; do not set it on a block that already has a closing delimiter.
+ * - `tags` — grammar-level CST categories for visitor dispatch. Stored once in
+ *   grammar reflection; not copied onto every CST node.
+ * Both skip `build` only for a one-child match; zero or two-plus children go
+ * through `build` normally.
+ */
+type ParserValue<P> = P extends Combinator<infer T> ? T : never
+type ProjectValue<P extends Combinator<unknown>, I extends number> =
+  ParserValue<P> extends readonly unknown[]
+    ? I extends keyof ParserValue<P> ? ParserValue<P>[I] : unknown
+    : I extends 0 ? ParserValue<P> : unknown
+
+export type NodeCombinator<T, NodeType extends string = never, NodeTag extends string = never> =
+  Combinator<T> & {
+    /** Type-only CST node identity carried for grammar-aware visitors. */
+    readonly [NODE_TYPE]?: NodeType
+    /** Type-only CST tags carried for grammar-aware visitors. */
+    readonly [NODE_TAG]?: NodeTag
+  }
+
+export type NodeOptions<Tags extends readonly string[] = readonly never[]> = {
+  unwrap?: boolean
+  collapse?: boolean
+  project?: number
+  captureTrivia?: boolean
+  trailingTrivia?: boolean
+  tags?: Tags
+  /**
+   * Declared positional arity of `build` — the ESCAPE HATCH for a reducer parseman
+   * cannot read.
+   *
+   * Arity gates five capture tiers (`>= 1` children, `>= 2` fields, `>= 4` rawChildren,
+   * `>= 5` triviaLog, `>= 6` a clone of `_ctx.state`), and parseman normally derives it
+   * from the reducer's declaration — including across module boundaries. A few shapes
+   * are genuinely undecidable: a rest parameter (`...args`), a body that reads
+   * `arguments`, a reassigned or dynamically constructed reducer. Those fail OPEN, which
+   * is safe but pays for every tier on every match, forever.
+   *
+   * Declaring the arity here turns "undecidable" into "declared". You are asserting the
+   * highest positional argument the reducer reads; parseman then elides everything above
+   * it exactly as if it had read the parameter list.
+   *
+   * DECLARING TOO LOW UNDER-CAPTURES: the reducer will receive an empty `rawChildren` /
+   * `triviaLog` or an absent `state` rather than a wrong value. Count the parameters.
+   */
+  buildArity?: number
+}
+export type NodeProjectOptions<I extends number = number> =
+  Omit<NodeOptions, 'project' | 'unwrap' | 'collapse'> & { project: I; unwrap?: never; collapse?: never }
+
+/** A captured child's value form: a leaf unwraps to its string value, else as-is. */
+export function unwrapChild(child: unknown): unknown {
+  return child !== null && typeof child === 'object' && (child as { _tag?: string })._tag === 'leaf'
+    ? (child as { value: unknown }).value
+    : child
+}
+
+function isCstChild(value: unknown): boolean {
+  return typeof value === 'object'
+    && value !== null
+    && ((value as { _tag?: string })._tag === 'node'
+      || (value as { _tag?: string })._tag === 'leaf'
+      || (value as { _tag?: string })._tag === 'parseError')
+}
+
+/**
+ * The authoring error for `node()` with no rules() key, raised IDENTICALLY by
+ * every engine. Exported because the table encoder used to answer it with
+ * `UnsupportedConstruct: no opcode for 'node(inferred type)'` — a message that
+ * reads as a table gap and names neither the mistake nor the fix.
+ */
+export function missingInferredType(): never {
+  throw new Error('node(): inferred node type requires a rules() key; pass node("Type", parser) outside rules()')
+}
+
+function normalizeBuildArity(arity: number | undefined): number | undefined {
+  if (arity === undefined) return undefined
+  if (!Number.isInteger(arity) || arity < 0 || arity > 6) {
+    throw new Error('node() buildArity must be an integer 0..6 (children, fields, span, rawChildren, triviaLog, state)')
+  }
+  return arity
+}
+
+function normalizeProject(project: number | undefined): number | undefined {
+  if (project === undefined) return undefined
+  if (!Number.isInteger(project) || project < 0) {
+    throw new Error('node() project child must be a non-negative integer')
+  }
+  return project
+}
+
+export function projectChild(children: ReadonlyArray<unknown>, project: number, type: string): unknown {
+  if (!(project in children)) {
+    throw new Error(`node(${JSON.stringify(type)}) project child ${project} was not captured`)
+  }
+  return unwrapChild(children[project])
+}
+
+export function node<P extends Combinator<unknown>, const I extends number, const Tags extends readonly string[] = readonly never[]>(combinator: P, opts: NodeProjectOptions<I> & { tags?: Tags }): NodeCombinator<ProjectValue<P, I>, never, Tags[number]>
+export function node<N, const Tags extends readonly string[] = readonly never[]>(combinator: Combinator<unknown>, build?: BuildNode<N>, opts?: NodeOptions<Tags>): NodeCombinator<N, never, Tags[number]>
+export function node<N, const Tags extends readonly string[] = readonly never[]>(combinator: Combinator<unknown>, opts?: NodeOptions<Tags>): NodeCombinator<N, never, Tags[number]>
+export function node<const Type extends string, P extends Combinator<unknown>, const I extends number, const Tags extends readonly string[] = readonly never[]>(type: Type, combinator: P, opts: NodeProjectOptions<I> & { tags?: Tags }): NodeCombinator<ProjectValue<P, I>, Type, Tags[number]>
+// `Type` carries a default so that `node<N>('Type', …)` — one explicit type
+// argument, the node value type — still MATCHES these signatures. Without it
+// the arity check rejects them, resolution falls back to the combinator-first
+// overloads above, and the caller gets `TS2345 string is not assignable to
+// Combinator` plus a TS7006 implicit-any reducer from the rejected contextual
+// type. See test/unit/node-type-argument.test.ts.
+//
+// RESIDUAL COST: `= string` is the only shape available. TypeScript fills a
+// missing type argument from its DEFAULT and never infers it (there is no
+// partial type-argument inference), so `node<N>('Type', …)` resolves `Type` to
+// `string` and loses the string literal. Write `node('Type', …)` (no explicit
+// type arguments) or `node<N, 'Type'>('Type', …)` where the literal identity
+// matters to a grammar-aware visitor. The only literal-preserving alternative
+// is a curried call form, which would change the public call surface.
+export function node<N, const Type extends string = string, const Tags extends readonly string[] = readonly never[]>(type: Type, combinator: Combinator<unknown>, build?: BuildNode<N>, opts?: NodeOptions<Tags>): NodeCombinator<N, Type, Tags[number]>
+export function node<N, const Type extends string = string, const Tags extends readonly string[] = readonly never[]>(type: Type, combinator: Combinator<unknown>, opts?: NodeOptions<Tags>): NodeCombinator<N, Type, Tags[number]>
+export function node<N>(
+  typeOrCombinator: string | Combinator<unknown>,
+  combinatorOrBuild?: Combinator<unknown> | BuildNode<N> | NodeOptions,
+  buildOrOpts?: BuildNode<N> | NodeOptions,
+  maybeOpts?: NodeOptions,
+): Combinator<N> {
+  const hasExplicitType = typeof typeOrCombinator === 'string'
+  const type = hasExplicitType ? typeOrCombinator : undefined
+  const combinator = (hasExplicitType ? combinatorOrBuild : typeOrCombinator) as Combinator<unknown>
+  const buildArg = hasExplicitType ? buildOrOpts : combinatorOrBuild
+  const build = typeof buildArg === 'function' ? buildArg as BuildNode<N> : undefined
+  const opts = (typeof buildArg === 'function' ? maybeOpts : buildArg ?? maybeOpts) as NodeOptions | undefined
+  const project = normalizeProject(opts?.project)
+  if (project !== undefined && build !== undefined) {
+    throw new Error('node() options cannot combine project with a build callback')
+  }
+  const baseDef = { tag: 'node' as const, parser: combinator, ...(type === undefined ? {} : { type }), ...(build === undefined ? {} : { build }) }
+  const meta: ParserMeta = {
+    firstSet: combinator._meta.firstSet,
+    canMatchNewline: combinator._meta.canMatchNewline,
+    isTrivia: false,
+  }
+  const unwrap = opts?.unwrap === true
+  const collapse = opts?.collapse === true
+  const captureTrivia = opts?.captureTrivia === true
+  const trailingTrivia = opts?.trailingTrivia === true
+  const tags = opts?.tags
+  const buildArity = normalizeBuildArity(opts?.buildArity)
+  if (unwrap && collapse) {
+    throw new Error('node() options cannot set both unwrap and collapse')
+  }
+  if (project !== undefined && (unwrap || collapse)) {
+    throw new Error('node() options cannot combine project with unwrap or collapse')
+  }
+  const def: Extract<ParserDef, { tag: 'node' }> = unwrap || collapse || project !== undefined || captureTrivia || trailingTrivia || buildArity !== undefined || (tags !== undefined && tags.length > 0)
+    ? { ...baseDef, ...(unwrap ? { unwrap: true } : {}), ...(collapse ? { collapse: true } : {}), ...(project !== undefined ? { project } : {}), ...(captureTrivia ? { captureTrivia: true } : {}), ...(trailingTrivia ? { trailingTrivia: true } : {}), ...(buildArity !== undefined ? { buildArity } : {}), ...(tags !== undefined && tags.length > 0 ? { tags } : {}) }
+    : baseDef
+  // Arity-gated elision — decided once, identically to the compiler (build-arity.ts).
+  // When the build never reads the trivia (4th) arg, disable per-node CST-trivia
+  // capture for the inner scope; when it never reads state (5th), skip the state clone.
+  // A STRUCTURAL node (no own build) defers to `ctx.build` / a default CST, which
+  // may read either, so capture both.
+  // These are the DIRECT builder's own needs, and they are not the whole story. A node
+  // with its own build is re-routed through `ctx.build` when that host marks itself
+  // `_parsemanCstOutput` (see the dispatch below) — and then the HOST, not the builder,
+  // is the consumer. Nearly every AST builder is `children => …`, arity 1, so under a CST
+  // host these nodes handed the host an EMPTY triviaLog and absent fields and state, and
+  // an empty trivia log is indistinguishable from a node that genuinely had none.
+  //
+  // The COMPILED engine settles this at build time (`compile(g, { hostMode: 'cst' })`,
+  // added in 0.37.0), where it costs nothing. The interpreter has no compile step and
+  // stays dynamic, so it re-decides per parse — which is the same answer, reached the
+  // only way this engine can reach it.
+  const capturesTrivia = captureTrivia || trailingTrivia || (build ? buildReadsTrivia(def) : project === undefined)
+  const clonesState = build ? buildReadsState(def) : project === undefined
+  const hasOwnFields = parserHasOwnFields(combinator)
+  const capturesFields = hasOwnFields && (build ? buildReadsFields(def) : project === undefined)
+  // First-set fail-fast (mirrors emitNode's codegen guard): a node whose body can't
+  // match empty and whose first set can't start here can only fail, so reject BEFORE
+  // allocating the CST capture frame. Sound and output-neutral — the failing body
+  // would capture nothing and beginCstNodeCapture saves/restores every buffer, so
+  // skipping returns the same failure the body's start-fail produces. Skipped under a
+  // completions probe / tolerant recovery, where the swallowed failure still feeds the
+  // probe (matching the codegen guard's `!ctx.recovery` gate).
+  const guardable = combinator._meta.firstSet.kind !== 'any' && !matchesEmpty(combinator)
+  let failExpected: string[] | undefined
+  return {
+    _tag: 'node',
+    _meta: meta,
+    _def: def,
+    parse(input: string, pos: number, ctx: ParseContext): ParseResult<N> {
+      if (guardable && ctx._probe === undefined && !ctx._tolerant && !startsFirstSet(combinator, input, pos)) {
+        if (failExpected === undefined) {
+          const e = deriveExpected(combinator)
+          failExpected = e.length > 0 ? e : [combinator._tag]
+        }
+        return { ok: false, expected: failExpected, span: { start: pos, end: pos } }
+      }
+      // Under a positioned-CST host a direct builder is bypassed, so capture must follow
+      // what the HOST reads. Mirrors `hostMode: 'cst'` in the compiled engine, which
+      // captures unconditionally there because it knows the mode at compile time.
+      const hasDirectValue = build !== undefined || project !== undefined
+      const hostCst = hasDirectValue && cstOutputHost(ctx.build)
+      const structural = !hasDirectValue
+      const hostCapturesThisType = structural
+        && def.type !== undefined
+        && ctx.build?._parsemanCaptureTrivia !== undefined
+        ? ctx.build._parsemanCaptureTrivia(def.type)
+        : undefined
+      // Structural nodes capture for their host by default, but the host may
+      // narrow that default by node type. Grammar-owned capture is authoritative:
+      // an explicit `captureTrivia`/`trailingTrivia` request cannot be disabled by
+      // the host. Direct builders (including a CST host that bypasses one) retain
+      // their existing arity/CST-host decision and never consult this predicate.
+      const effTrivia = structural
+        ? captureTrivia || trailingTrivia || hostCapturesThisType !== false
+        : capturesTrivia || hostCst
+      const effFields = capturesFields || (hostCst && hasOwnFields)
+      const saved = beginCstNodeCapture(ctx)
+      const savedFields = ctx._fields
+      ctx._fields = effFields ? [] : undefined
+      // Per-node-type trivia-kind mask: a structural (host-built) node may want
+      // only certain kinds captured (comments for Ruleset, whitespace for
+      // CompoundSelector). Scoped here, restored below — matches the compiled path.
+      const savedMask = ctx._triviaCaptureMask
+      if (build === undefined && project === undefined && ctx.build?._parsemanTriviaKinds !== undefined && def.type !== undefined) {
+        ctx._triviaCaptureMask = ctx.build._parsemanTriviaKinds(def.type)
+      }
+      // Short-circuit the per-node trivia push (scanTrivia gates on captureTrivia)
+      // without touching the global _triviaLog, which is committed independently.
+      if (!effTrivia) ctx.captureTrivia = false
+      let r = combinator.parse(input, pos, ctx)
+      if (r.ok && trailingTrivia && ctx.trivia) {
+        const end = consumeTrivia(input, r.span.end, ctx)
+        r = { ...r, span: { start: r.span.start, end } }
+      }
+      const fields = effFields ? buildFieldMap(ctx._fields) : undefined
+      ctx._fields = savedFields
+      ctx._triviaCaptureMask = savedMask
+      const { children, rawChildren, triviaLog } = endCstNodeCapture(ctx, saved)
+
+      if (!r.ok) return r
+
+      // unwrap/collapse: a single captured child IS the value — skip build.
+      const st = clonesState && ctx.state !== undefined ? Object.assign({}, ctx.state as Record<string, unknown>) : undefined
+      const nodeType = def.type ?? missingInferredType()
+      const cstOutput = cstOutputHost(ctx.build)
+      const span = ctx.trackLines ? annotateSpanFromLineContext(r.span, ctx) : r.span
+      // A direct builder that never declared `state` still owes the host its snapshot.
+      // The clone happens AFTER the body, so unlike trivia it needs no gate up front —
+      // build it here, on a branch the eval-AST path never takes. Matches what
+      // `hostMode: 'cst'` does in the compiled engine.
+      const hostState = clonesState
+        ? st
+        : ctx.state !== undefined ? Object.assign({}, ctx.state as Record<string, unknown>) : undefined
+      const built: unknown = unwrap && children.length === 1
+        ? unwrapChild(children[0])
+        : collapse && children.length === 1
+          ? children[0]
+        // Collapse applies wherever the node's VALUE comes from the host: a structural
+        // node, or ANY node under a positioned-CST host, where the direct builder is
+        // bypassed and the produced thing is a host-owned CST node either way. Gating on
+        // `!build` alone made `cstBuildHost({ collapse })` a documented no-op for every
+        // grammar whose rules carry reducers — silently, in both engines.
+        : (cstOutput || (!build && project === undefined))
+          && ctx.build?._parsemanCstCollapse
+          && children.length === 1
+          && rawChildren.length === 1
+          && ctx.build._parsemanCstCollapse(nodeType, children[0], children, rawChildren)
+          ? children[0]
+        : project !== undefined
+          ? cstOutput && ctx.build
+            ? ctx.build(nodeType, children, fields, span, rawChildren, triviaLog, hostState, tags)
+            : projectChild(children, project, nodeType)
+        : build
+          // A direct builder normally owns its result. The positioned-CST host is
+          // the one exception: it must never receive an arbitrary AST object as a
+          // child of a CST node, so build this grammar node through that host.
+          ? cstOutput && ctx.build
+            ? ctx.build(nodeType, children, fields, span, rawChildren, triviaLog, hostState, tags)
+            : build(children, fields, span, rawChildren, triviaLog, st)
+          // Structural node: a `ctx.build` host if present, else a default CST.
+          : ctx.build
+              ? ctx.build(nodeType, children, fields, span, rawChildren, triviaLog, st, tags)
+              : { _tag: 'node', type: nodeType, span: ctx.trackLines ? { ...span } : { start: r.span.start, end: r.span.end }, state: st ?? null, children }
+      const rawEntry = isCstChild(built)
+        ? built
+        // A direct semantic object is opaque to the raw CST, but its source is
+        // not. Preserve the exact matched span so legacy/structural parents can
+        // retain text and trivia without fabricating an empty token.
+        : { _tag: 'leaf', value: typeof built === 'string' ? built : typeof built === 'object' && built !== null ? input.slice(r.span.start, r.span.end) : '', span }
+      if (saved.buf !== undefined || saved.ch !== undefined) {
+        pushCstChild(ctx, built, rawEntry)
+      }
+      return { ok: true, value: built as N, span }
+    },
+  }
+}

package/src/combinators/not.ts

@@ -0,0 +1,55 @@
+import type { Combinator, ParseContext, ParseResult, ParserMeta } from '../types.ts'
+import { any } from './first-set.ts'
+import { saveLookaheadMark, rollbackLookahead } from './trivia-skip.ts'
+
+/**
+ * Negative lookahead. Succeeds (consuming nothing) when `combinator` fails;
+ * fails when `combinator` succeeds.
+ *
+ * The standard way to match a keyword without also matching the prefix
+ * of a longer identifier:
+ *
+ *   const kwTrue = sequence(literal('true'), not(regex(/\w/)))
+ *   // matches "true" in "true && x" but NOT in "trueish" or "trueness"
+ */
+export function not(combinator: Combinator<unknown>): Combinator<null> {
+  const meta: ParserMeta = {
+    firstSet: any(),     // we don't know what NOT matches
+    canMatchNewline: false,
+    isTrivia: false,
+  }
+
+  return {
+    _tag: 'not',
+    _meta: meta,
+    _def: { tag: 'not', parser: combinator },
+    parse(input: string, pos: number, ctx: ParseContext): ParseResult<null> {
+      // Negative lookahead is a pure predicate: whatever the inner attempt
+      // captured (CST leaves/rawChildren/per-node trivia/fields), recovered (a
+      // ParseError pushed to ctx._errors + embedded via captureError), or committed
+      // to the GLOBAL `_triviaLog` must be rolled back on BOTH outcomes — not()
+      // consumes nothing and so may leave no side effect.
+      //
+      // `rollbackLookahead`, not `rollbackCstCapture`: the latter's mark omits two
+      // further sinks a probe can write.
+      //   - `_triviaLog`, which `scanTrivia().commit()` writes when the probed body
+      //     skips ambient trivia between terms. Missing it duplicates every probed
+      //     span once the region is parsed for real — `_triviaLog` has no dedup
+      //     anywhere (`triviaEntries()` is a positional view over the flat array),
+      //     so the duplicate reaches output.
+      //   - `_probe.best`, the completions tracker, for the same reason `peek()`
+      //     restores it: expectations raised INSIDE a zero-width probe are not
+      //     reachable from the enclosing grammar at the cursor, so leaving them
+      //     offers unreachable tokens as completions.
+      // Using the shared lookahead helper means neither can silently regress the
+      // next time a sink is added.
+      const mark = saveLookaheadMark(ctx)
+      const result = combinator.parse(input, pos, ctx)
+      rollbackLookahead(ctx, mark)
+      if (result.ok) {
+        return { ok: false, expected: [`not(${combinator._tag})`], span: { start: pos, end: pos } }
+      }
+      return { ok: true, value: null, span: { start: pos, end: pos } }
+    },
+  }
+}

package/src/combinators/parser.ts

@@ -0,0 +1,266 @@
+import type { Combinator } from '../types.ts'
+import type { HostMode } from '../cst/host-mode.ts'
+import { ref } from './ref.ts'
+import { markUnusedValues } from '../compiler/value-usage.ts'
+import { parser as grammarParser } from './grammar.ts'
+import { collectGrammarReflection, NODE_TAG, NODE_TYPE, type GrammarWithReflection } from '../cst/reflection.ts'
+import { attachGrammarReflection } from '../cst/reflection-attach.ts'
+
+/**
+ * Non-enumerable key on a `rules()` result holding the factory's declaration
+ * order (the returned object's key order), which differs from the result's own
+ * reference-creation key order. Read by `parseman/spec` for source-order output.
+ */
+export const RULE_ORDER = '__parsemanRuleOrder'
+
+function tagRule(r: Combinator<unknown>, key: string): void {
+  ;(r as unknown as { _ruleName?: string })._ruleName = key
+  if (r._def.tag === 'node' && r._def.type === undefined) r._def.type = key
+}
+
+type DefinableRef = Combinator<unknown> & { define(p: Combinator<unknown>): void }
+
+function isDefinableRef(v: unknown): v is DefinableRef {
+  return !!v
+    && typeof v === 'object'
+    && '_def' in v
+    && (v as { _def: { tag?: string } })._def.tag === 'lazy'
+    && typeof (v as { define?: unknown }).define === 'function'
+}
+
+function ruleNameOf(r: Combinator<unknown>): string | undefined {
+  return (r as unknown as { _ruleName?: string })._ruleName
+}
+
+function isNamedRuleRefForAnotherRule(r: Combinator<unknown>, key: string): boolean {
+  const name = r._def.tag === 'lazy' ? ruleNameOf(r) : undefined
+  return name !== undefined && name !== key
+}
+
+/**
+ * Define named grammar rules without forward declarations.
+ *
+ * Pass a factory that receives all rule names as references (via a Proxy)
+ * and returns a record of combinators. rules() handles creating ref()
+ * placeholders and wiring them up — the user never sees ref() at all.
+ *
+ *   const { value } = rules(g => ({
+ *     value:  choice(g.object, g.array, str, num, bool, nil),
+ *     object: transform(sequence('{', sepBy(g.pair, ','), '}'), Object.fromEntries),
+ *     array:  transform(sequence('[', sepBy(g.value, ','), ']'), ([, items]) => items),
+ *     pair:   transform(sequence(g.key, literal(':'), g.value), ([k,, v]) => [k, v]),
+ *   }))
+ *
+ * Not every name in the factory must appear in the returned object — local helpers
+ * (like `comma`, `key`) can be plain const inside the factory and composed normally.
+ * Only names that OTHER rules reference via `g.xxx` need to be in the returned record.
+ *
+ * TypeScript: use an explicit type parameter for full type safety on `g`:
+ *   rules<{ value: Combinator<JSONValue>; array: Combinator<JSONValue[]> }>(g => ({ ... }))
+ * Without it, `g.*` accesses are typed as `any` but the return is still inferred.
+ */
+/**
+ * Grammar-level options for `rules()`. Parity with `parser({...})`, but declared
+ * ONCE for the whole grammar instead of wrapped around a scope. `trivia` becomes
+ * the ambient trivia for every rule (installed at the parse entry, inherited
+ * everywhere, incremental parse included); `parser({trivia})` / `noTrivia` still
+ * override it locally for a sub-region.
+ */
+export type RulesOptions = {
+  /** Ambient trivia for the whole grammar. See `parser({ trivia })` for the shape
+   * (`null` clears it — equivalent to omitting it at the grammar level). */
+  trivia?: Combinator<unknown> | null
+  /**
+   * Ambient scan-skip for the whole grammar: opaque non-trivia units (strings,
+   * balanced brackets, …) that a `scanTo`/`balanced` with no explicit `skip`
+   * consults so a sentinel hidden inside one is never matched. Declared ONCE here
+   * and inherited everywhere, mirroring `trivia`. `null`/absent = none.
+   */
+  scanSkip?: Combinator<unknown>[] | null
+  /**
+   * Compile-time host mode for this grammar, same meaning as `compile(g, { hostMode })`
+   * and `compose(items, { hostMode })`: `'ast'` (default) emits each direct builder's
+   * own result and NO positioned-CST branch; `'cst'` builds every node through the
+   * `ctx.build` host and captures unconditionally.
+   *
+   * Declaring it HERE is what lets ONE grammar source serve both consumers under the
+   * macro, which cannot take a compile option any other way:
+   *
+   * ```ts
+   * const factory = (g: any) => ({ … })
+   * export const grammar    = rules({ trivia: rw }, factory)
+   * export const cstGrammar = rules({ trivia: rw, hostMode: 'cst' }, factory)
+   * ```
+   *
+   * Two call sites over one factory, so the macro emits two independent top-level
+   * artifacts and each bundle tree-shakes away the one it does not import. Neither
+   * pays the other's cost — which is the whole reason host mode is a compile-time
+   * decision rather than a per-node runtime read.
+   *
+   * The INTERPRETER routes dynamically off the host and does not need this; it is
+   * still recorded, so `run()` can refuse a mismatched host once per parse instead of
+   * quietly producing the wrong tree shape.
+   */
+  hostMode?: HostMode
+  /**
+   * Compile-time line tracking for this grammar. Under the macro this emits a
+   * separate line-aware artifact from the same factory; the default artifact
+   * remains free of line-tracking helpers and branches.
+   */
+  trackLines?: boolean
+}
+
+// Options-first, mirroring `parser({ opts }, combinator)` — set once on the grammar
+// vs scope it locally, same options in the same position. The bare `rules(factory)`
+// form is unchanged. The impl also tolerates the legacy `rules(factory, opts)` order.
+type RuleNodeType<K extends string, C> =
+  C extends { readonly [NODE_TYPE]?: infer T extends string }
+    ? [T] extends [never] ? K : T
+    : K
+
+type RuleNodeTag<C> =
+  C extends { readonly [NODE_TAG]?: infer Tag extends string } ? Tag : never
+
+type RuleMapNodeType<T extends Record<string, Combinator<unknown>>> = {
+  [K in keyof T & string]: RuleNodeType<K, T[K]>
+}[keyof T & string]
+
+type RuleMapNodeTag<T extends Record<string, Combinator<unknown>>> = {
+  [K in keyof T & string]: RuleNodeTag<T[K]>
+}[keyof T & string]
+
+type RulesResult<T extends Record<string, Combinator<unknown>>> =
+  T & GrammarWithReflection<RuleMapNodeType<T>, RuleMapNodeTag<T>>
+
+export function rules<T extends Record<string, Combinator<unknown>>>(factory: (self: any) => T): RulesResult<T>
+export function rules<T extends Record<string, Combinator<unknown>>>(options: RulesOptions, factory: (self: any) => T): RulesResult<T>
+export function rules<T extends Record<string, Combinator<unknown>>>(
+  a: ((self: any) => T) | RulesOptions,
+  b?: (self: any) => T,
+): RulesResult<T> {
+  const factory = (typeof a === 'function' ? a : b) as (self: any) => T
+  const options = (typeof a === 'function' ? b : a) as RulesOptions | undefined
+  const cache: Partial<T> = {}
+
+  // Proxy: accessing any property creates a ref() placeholder on first touch.
+  const proxy = new Proxy(cache, {
+    get(target, key) {
+      if (typeof key !== 'string') return undefined
+      const record = target as Record<string, Combinator<unknown>>
+      if (!(key in record)) {
+        const r = ref()
+        // Tag the placeholder with its rule name so the linkable compiler can
+        // emit a by-name `_r_<key>` call for a reference to a rule defined in
+        // ANOTHER artifact (resolved at fuse time) — see compileLinkable.
+        tagRule(r, key)
+        record[key] = r
+      }
+      return record[key]
+    },
+  })
+
+  // Evaluate all rule definitions. JavaScript evaluates object-literal values
+  // left-to-right, so any `g.ruleName` access inside triggers placeholder creation
+  // before the rule's own parser is built — enabling forward references.
+  const definitions = factory(proxy)
+
+  // Fill each ref with its actual definition, or store directly if never accessed via proxy.
+  for (const key of Object.keys(definitions)) {
+    const placeholder = (cache as Record<string, Combinator<unknown>>)[key]
+    const parser = (definitions as Record<string, Combinator<unknown>>)[key]!
+    if (placeholder === parser) {
+      throw new Error(`rules(): rule "${key}" cannot be a direct alias to itself`)
+    }
+    if (isDefinableRef(placeholder)) {
+      if (!isNamedRuleRefForAnotherRule(parser, key)) tagRule(parser, key)
+      placeholder.define(parser)
+      // Propagate actual first-set so later choices wrapping this ref get correct dispatch.
+      placeholder._meta.firstSet = parser._meta.firstSet
+      placeholder._meta.canMatchNewline = parser._meta.canMatchNewline
+    } else if (isNamedRuleRefForAnotherRule(parser, key)) {
+      const alias = ref()
+      tagRule(alias, key)
+      alias.define(parser)
+      alias._meta.firstSet = parser._meta.firstSet
+      alias._meta.canMatchNewline = parser._meta.canMatchNewline
+      ;(cache as Record<string, Combinator<unknown>>)[key] = alias
+    } else {
+      tagRule(parser, key)
+      ;(cache as Record<string, Combinator<unknown>>)[key] = parser
+    }
+  }
+
+  // Declare the grammar-level ambient trivia on every rule, so parsing ANY rule
+  // as an entry installs it (run()/parse() read this), and the macro can seed the
+  // compiled map. `parser({trivia})` / `noTrivia` still override it locally.
+  // `!= null`: a `trivia: null` grammar clears trivia — same as omitting it at the
+  // grammar level — so store nothing (and never write null, which has no `_meta`).
+  if (options?.trivia != null) {
+    for (const key of Object.keys(definitions)) {
+      const rule = (cache as Record<string, Combinator<unknown>>)[key]
+      // Skip trivia rules (e.g. the grammar's `rw`, returned so the driver can
+      // reach it as `g.rw`): a trivia rule must never carry ambient trivia, or it
+      // would recursively skip trivia within itself. Mirrors the codegen guard.
+      if (rule && !rule._meta.isTrivia) (rule._meta as { grammarTrivia?: Combinator<unknown> }).grammarTrivia = options.trivia
+    }
+  }
+
+  // Grammar-level ambient scan-skip, mirroring the trivia stamp above: every
+  // non-trivia rule carries it so any parse entry installs `ctx.scanSkip` and the
+  // compiled map can seed it. `!= null` so `scanSkip: null` clears (stores nothing).
+  if (options?.scanSkip != null) {
+    for (const key of Object.keys(definitions)) {
+      const rule = (cache as Record<string, Combinator<unknown>>)[key]
+      if (rule && !rule._meta.isTrivia) (rule._meta as { grammarScanSkip?: Combinator<unknown>[] }).grammarScanSkip = options.scanSkip
+    }
+  }
+
+  // Grammar-level host mode, mirroring the two stamps above. Only `'cst'` is recorded:
+  // `'ast'` is the default everywhere, so stamping it would put a field on every rule of
+  // every grammar to say "unchanged". Trivia rules are skipped for the same reason as
+  // above — they build no nodes, so the mode is meaningless on them.
+  if (options?.hostMode === 'cst') {
+    for (const key of Object.keys(definitions)) {
+      const rule = (cache as Record<string, Combinator<unknown>>)[key]
+      if (rule && !rule._meta.isTrivia) (rule._meta as { grammarHostMode?: HostMode }).grammarHostMode = 'cst'
+    }
+  }
+
+  if (options?.trackLines === true) {
+    for (const key of Object.keys(definitions)) {
+      const rule = (cache as Record<string, Combinator<unknown>>)[key]
+      if (rule && !rule._meta.isTrivia) (rule._meta as { grammarTrackLines?: true }).grammarTrackLines = true
+    }
+    for (const key of Object.keys(definitions)) {
+      const rule = (cache as Record<string, Combinator<unknown>>)[key]
+      if (rule && !rule._meta.isTrivia && rule._def.tag !== 'grammar') {
+        const wrapped = grammarParser({ trackLines: true }, rule)
+        tagRule(wrapped, key)
+        ;(wrapped._meta as { grammarTrackLines?: true }).grammarTrackLines = true
+        ;(cache as Record<string, Combinator<unknown>>)[key] = wrapped
+      }
+    }
+  }
+
+  // Dead-value analysis: mark container aggregates that only feed a node()'s
+  // capture so the interpreter (and, via the same flag, the compiled output) skips
+  // building them. Each rule is its own root — refs are boundaries (see value-usage).
+  for (const key of Object.keys(definitions)) {
+    markUnusedValues((cache as Record<string, Combinator<unknown>>)[key]!)
+  }
+
+  // Record the factory's DECLARATION order (the returned object's key order).
+  // `cache`'s own key order is reference-creation order — a Proxy artifact — so
+  // it can lead with an internal rule instead of the entry rule. Consumers that
+  // want the order the author actually wrote (e.g. `parseman/spec`) read this.
+  // Non-enumerable, so Object.keys / spread / for-in over the grammar are
+  // unaffected and every existing consumer sees exactly the rules it did before.
+  Object.defineProperty(cache, RULE_ORDER, {
+    value: Object.keys(definitions),
+    enumerable: false,
+    configurable: true,
+  })
+  attachGrammarReflection(cache, collectGrammarReflection(Object.keys(definitions).map(key => [key, (cache as Record<string, Combinator<unknown>>)[key]!])))
+
+  return cache as RulesResult<T>
+}