parseman 0.36.0 → 0.37.0

package/README.md

@@ -4,16 +4,37 @@
 
 # Parséman (PAR-zə-mahn)
 
-Write parsers as TypeScript functions. Ship them like hand-written parsers.
+Write parsers as ordinary functions. Ship them like hand-written parsers.
 
 Parser combinators are pleasant to write and usually slow. Parser generators are fast and
-usually mean grammar files, generated code, and extra tooling. Parséman is a TypeScript
-combinator library with an optional compiler: write ordinary TypeScript, and a build-time
-macro turns it into flat JavaScript that behaves like a parser you wrote by hand.
+usually mean grammar files, generated code, and extra tooling. Parséman is a combinator
+library with an optional compiler, and it gives you both.
 
-Reach for it when you want normal TypeScript instead of grammar files, CST/AST nodes with
-spans and trivia, error recovery and incremental re-parsing for editor tooling, or simply
-a fast parser for a DSL, config language, formatter, or linter.
+**Parsing to JS values, the macro build is the fastest general-purpose JS parser in the
+suite** — ahead of every other library measured, at every grammar and every input size.
+Every parser in the suite builds real output: objects, row arrays, AST nodes. On a 7.7 kB
+GraphQL document Parséman takes **131 µs**; Peggy takes 328 µs. Only a purpose-built native
+edges it out, `JSON.parse` on JSON.
+
+![GraphQL parsing benchmarks](https://raw.githubusercontent.com/matthew-dean/parseman/main/assets/bench-graphql.svg)
+
+Two more results. The compiled CST path beats Lezer on the JSON CST fixture — **174 µs** vs
+594 µs at 11.9 kB — while producing a richer tree carrying spans and trivia. And `parseDoc`
+stores parent-relative spans, so an in-place edit costs a fraction of a full reparse rather
+than a multiple of it. Results move with grammar shape, input size and runtime — which is
+why [the suite](#benchmarks) ships with the library rather than only its conclusions.
+
+You get there by writing normal code. Add the bundler plugin, mark one import, and the
+combinators you already wrote compile to flat JavaScript — the compiler computes the first
+sets and left-factors the choices for you.
+
+Grammars work the same in plain JavaScript: the macro compiles a `.js` grammar to the same
+output as a `.ts` one, and the package ships both ESM and CJS. Write in TypeScript and result
+types are inferred across the whole combinator chain — types you didn't have to write out.
+
+Reach for it when you want CST/AST nodes with spans and trivia, error recovery and
+incremental re-parsing for editor tooling, or simply a fast parser for a DSL, config
+language, formatter, or linter.
 
 > **📖 Full documentation: [matthew-dean.github.io/parseman](https://matthew-dean.github.io/parseman/)**
 
@@ -123,24 +144,18 @@ hand-written parsers in
 Benchmarked against [Peggy](https://peggyjs.org/),
 [Parsimmon](https://github.com/jneen/parsimmon), [Chevrotain](https://chevrotain.io/),
 [Nearley](https://nearley.js.org/), [Jison](https://github.com/zaach/jison) and
-[Lezer](https://lezer.codemirror.net/) on JSON, CSV and GraphQL — each building real output
-(objects, row arrays, AST nodes), not validating syntax.
-
-**Parsing to JS values, the macro build is the fastest general-purpose JS parser in the
-suite** — ahead of every library above at every grammar and size (GraphQL large: **142 µs**
-vs Peggy's 339 µs). Only a purpose-built native edges it out, `JSON.parse` on JSON.
+[Lezer](https://lezer.codemirror.net/) on JSON, CSV and GraphQL, at three input sizes each.
+Each chart's legend names the libraries measured for that grammar.
 
-Two more results worth calling out: the compiled CST path beats Lezer on the JSON CST
-fixture while producing a richer tree carrying spans and trivia, and `parseDoc` stores
-parent-relative spans so an in-place edit costs a fraction of a full reparse rather than a
-multiple of it.
+Largest fixture of each, macro build against the fastest other library on that chart:
+GraphQL **131 µs** vs Peggy's 328 µs, JSON **133 µs** vs Chevrotain's 241 µs, CSV
+**75.3 µs** vs Peggy's 420 µs. Native `JSON.parse` does JSON large in 51.6 µs. On the CST
+chart, macro build runs 174 µs against Lezer's 594 µs parse-only.
 
 ![JSON parsing benchmarks](https://raw.githubusercontent.com/matthew-dean/parseman/main/assets/bench-json.svg)
 
 ![CSV parsing benchmarks](https://raw.githubusercontent.com/matthew-dean/parseman/main/assets/bench-csv.svg)
 
-![GraphQL parsing benchmarks](https://raw.githubusercontent.com/matthew-dean/parseman/main/assets/bench-graphql.svg)
-
 ![JSON CST parsing benchmarks](https://raw.githubusercontent.com/matthew-dean/parseman/main/assets/bench-cst-json.svg)
 
 Per-fixture figures, initialization costs, hardware, grammar provenance and how to reproduce

package/dist/analysis/duplication.d.ts

@@ -0,0 +1,421 @@
+/**
+ * Static grammar-duplication / overlap / rewrite diagnostic.
+ *
+ * A parseman grammar is a COMBINATOR TREE, not source text — so the question
+ * "did I write this production twice?" is a structural one a machine answers
+ * exactly, and a reviewer answers badly. A few hundred productions is tens of
+ * thousands of pairs; nobody reads that. This module walks the same tree
+ * `analyzeGating` walks and reports nine families:
+ *
+ *   1. `duplicates`     — subtrees that are structurally IDENTICAL, in ≥2 places.
+ *   2. `nearDuplicates` — subtrees identical except at ONE slot. This is the
+ *                          high-value case: a general rule cloned with one term
+ *                          swapped, where the fix is one production whose varying
+ *                          slot is a `choice`, not N copies of the scaffolding.
+ *   3. `regexFragments` — alternation runs re-spelled across several `regex()`
+ *                          terminals. Structural hashing cannot see inside a
+ *                          regex, so this is its own pass.
+ *   4. `regexClasses`   — character classes re-spelled across terminals, and, more
+ *                          usefully, NEAR-identical ones with the drift shown side
+ *                          by side.
+ *   5. `overlaps`       — `choice` arms whose first-sets intersect, reported as
+ *                          "these two arms, on these chars, sharing these leading
+ *                          terms" rather than gating's "dispatch failed".
+ *   6. `rewrites`       — ALGEBRAIC simplifications: mechanically-derived exact
+ *                          rewrites (`choice(sequence(A,B), B)` → `sequence(
+ *                          optional(A), B)`), plus the dead-arm cases that are
+ *                          outright bugs.
+ *   7. `divergentNodes` — ONE `node()` type built by several structurally different
+ *                          productions that are nonetheless variants of one shape.
+ *   8. `structureLoss`  — an earlier `choice` arm that FLATTENS what a later arm
+ *                          would have structured: same `node()` type, overlapping
+ *                          first-sets, and the earlier body contains no `node()`
+ *                          at all. The parse succeeds either way, so nothing else
+ *                          — not a test suite, not an output diff — reports it.
+ *                          The ordered, consequential half of `divergentNodes`.
+ *   9. `keywordRegexes` — hand-rolled keyword regexes (`regex(/not(?![-\w])/i)`)
+ *                          that should be `word()`/`keywords()`. Not a style note:
+ *                          `/i` without `/u` gets non-ASCII case folding wrong,
+ *                          and the fix that lives inside `keywords()` (see
+ *                          `combinators/case-fold.ts`) never reached the copies.
+ *
+ * ## What this CANNOT see
+ *
+ * Structural hashing is exactly that: STRUCTURAL. Two productions that accept the
+ * same language but are shaped differently — `many(x)` vs `optional(oneOrMore(x))`,
+ * a `regex` spelling of what another rule builds from combinators, a rule inlined
+ * once and referenced once — are invisible to `duplicates`/`nearDuplicates` unless
+ * they happen to fall into the `rewrites` algebra below. Equally, two subtrees that
+ * differ only in a `transform`/`node` CALLBACK are reported as distinct when the
+ * callbacks' source text differs, even if the functions are equivalent. This finds
+ * COPY-PASTE and mechanical redundancy. It does not find semantic redundancy, and a
+ * clean report is not a proof that a grammar has none.
+ *
+ * `analyzeDuplication()` / `analyzeDuplicationRules()` are the programmatic
+ * surface, mirroring `analyzeGating` / `analyzeGatingRules`. The compile-time
+ * wiring is OPT-IN (`compile(g, { duplication: 'warn' })` /
+ * `PARSEMAN_DUPLICATION=warn`) and runs on ALL THREE lowering paths — `compile`,
+ * `compileRuleMap` and `compileLinkable` — because the macro build takes the
+ * latter two and a diagnostic that only runs on the first is a diagnostic that
+ * reports zero findings forever.
+ */
+import type { Combinator, FirstSet } from '../types.ts';
+import { type RefResolver } from '../combinators/first-set.ts';
+/** Where a combinator sits: its owning rule, and the accessor path within it. */
+export type Site = {
+    /** Nearest enclosing `_ruleName`, or the seed name it was reached under. */
+    rule: string;
+    /** Structural path inside that rule, e.g. `choice[0] › node(Declaration) › seq[4]`. */
+    path: string;
+};
+export declare const siteToString: (s: Site) => string;
+/** N structurally identical copies of one subtree. */
+export type DuplicateFinding = {
+    kind: 'exact-duplicate';
+    id: string;
+    /** Node count of the repeated subtree. */
+    size: number;
+    /** How many DISTINCT combinator instances share the shape (shared-by-reference
+     *  reuse is not duplication and is never counted here). */
+    count: number;
+    /** Nodes removed by hoisting the shape to one shared const: `(count - 1) * size`. */
+    savings: number;
+    /** One-line rendering of the repeated shape. */
+    shape: string;
+    sites: Site[];
+    suggestion: string;
+};
+/** N subtrees identical except at ONE slot. */
+export type NearDuplicateFinding = {
+    kind: 'near-duplicate';
+    id: string;
+    /** Node count shared by every member (the scaffolding). */
+    sharedSize: number;
+    count: number;
+    savings: number;
+    /** The scaffolding with the varying slot rendered as `‹slot›`. */
+    shape: string;
+    /** Path to the varying slot, relative to the members' root. */
+    slotPath: string;
+    /** What each member puts in that slot, aligned with `sites`. */
+    variants: string[];
+    sites: Site[];
+    suggestion: string;
+};
+/** An alternation run re-spelled across several `regex()` terminals. */
+export type RegexFragmentFinding = {
+    kind: 'regex-fragment';
+    id: string;
+    /** The shared run, as it appears in the sources (`>=|<=|=>|=<|=~|[<>=]`). */
+    fragment: string;
+    /** Number of alternation branches in the run. */
+    branches: number;
+    count: number;
+    /** Characters removed by hoisting: `(count - 1) * fragment.length`. */
+    savings: number;
+    /** The full source of each regex that carries it, aligned with `sites`. */
+    sources: string[];
+    sites: Site[];
+    suggestion: string;
+};
+/** One spelling of a character class, and where it appears. */
+export type RegexClassVariant = {
+    /** The class as written, including any `^`: `-_a-zA-Z0-9€-￿`. */
+    source: string;
+    /** Members this spelling has that the cluster's most common spelling does not,
+     *  and vice versa — the DRIFT, rendered `+a-f / -0-9`. */
+    delta: string;
+    count: number;
+    sites: Site[];
+};
+/**
+ * A character class (or boundary lookahead class) re-spelled across several
+ * `regex()` terminals — and, when the spellings are not identical, the drift
+ * between them.
+ */
+export type RegexClassFinding = {
+    kind: 'regex-class';
+    id: string;
+    /** The cluster's most common spelling. */
+    canonical: string;
+    /** Every spelling in the cluster, most common first. Two variants side by side
+     *  IS the finding: one of them is wrong and reading cannot tell you which. */
+    variants: RegexClassVariant[];
+    /** Distinct `regex()` terminals across the whole cluster. */
+    count: number;
+    /** True when the cluster holds more than one spelling. */
+    drifted: boolean;
+    /** The class's highest code point is U+FFFF and it was written as an explicit
+     *  range — astral-plane characters fall outside it. */
+    bmpCeiling: boolean;
+    suggestion: string;
+};
+/** Two arms of one `choice` whose first-sets intersect. */
+export type ArmOverlapFinding = {
+    kind: 'arm-overlap';
+    id: string;
+    site: Site;
+    a: number;
+    b: number;
+    /** The SHARED first characters (not the union). */
+    on: FirstSet;
+    /** How many leading terms the two arms spell identically. */
+    sharedLeadingTerms: number;
+    /** Rendering of those shared leading terms, when there are any. */
+    sharedPrefix: string | null;
+    /** True when parseman's `sharedPrefix` choice strategy already recognizes the
+     *  common prefix once at runtime — the finding is then about READABILITY, not
+     *  speed. */
+    handledByStrategy: boolean;
+    /** Both arms lead with a `regex()` whose character classes intersect — usually
+     *  a sign the two arms want to be one terminal. */
+    regexPair: boolean;
+    suggestion: string;
+};
+export type RewriteKind = 'optional-prefix' | 'optional-suffix' | 'left-factor' | 'hand-rolled-sepby' | 'idempotent-nesting' | 'single-element' | 'duplicate-arm' | 'shadowed-arm';
+/** A mechanically-derived rewrite. */
+export type RewriteFinding = {
+    kind: 'rewrite';
+    id: string;
+    rewrite: RewriteKind;
+    site: Site;
+    /** What is there now. */
+    from: string;
+    /** What it is equal to. */
+    to: string;
+    /**
+     * `true` only when the rewrite provably cannot move the parse VALUE — which,
+     * here, means it only deletes an arm that can never be selected. Every other
+     * rewrite in this family changes the child arity or nesting of the value the
+     * site produces, so a `node()` build / `transform` / downstream consumer that
+     * reads positionally WILL see a different tree. Those are reported as
+     * CANDIDATES to verify, never as "fix this".
+     */
+    astNeutral: boolean;
+    /** Non-empty when the rewrite removes speculative work at parse time. */
+    perf: string;
+    /** Only on `hand-rolled-sepby`: whether this SITE can actually take `sepBy`. A
+     *  count of matches is not a worklist — in a real grammar most matches are
+     *  blocked, and reporting them all as convertible generates false work. */
+    sepByVerdict?: SepByVerdict;
+    /** True when this is a latent BUG (an unreachable arm), not a verbosity smell. */
+    bug: boolean;
+    suggestion: string;
+};
+/**
+ * One AST node type built by two or more STRUCTURALLY DIFFERENT productions that
+ * are nonetheless variants of a single shape (they spell several of the same
+ * terms). This is the clone family near-duplicate detection cannot see: the copies
+ * diverge in more than one slot — extra scaffolding, a hand-rolled whitespace run,
+ * a terminal guard — so no single hole explains them, yet every edit to "the
+ * declaration shape" still has to land in all of them, and nothing checks that it did.
+ */
+export type DivergentNodeFinding = {
+    kind: 'divergent-node';
+    id: string;
+    /** The `node()` type every member produces. */
+    nodeType: string;
+    /** Number of structurally distinct productions building it. */
+    count: number;
+    /** Terms every member spells identically — the evidence they are one shape. */
+    sharedTerms: string[];
+    productions: {
+        shape: string;
+        site: Site;
+        /** Terms this production has that at least one sibling does not. */
+        distinctTerms: string[];
+    }[];
+    suggestion: string;
+};
+/**
+ * An earlier `choice` arm that FLATTENS what a later arm would have STRUCTURED.
+ *
+ * Both arms build the same `node()` type and can start on the same character, so
+ * on the inputs both accept the earlier one wins — and its body contains no
+ * `node()` at all, so the tree it produces is that node over bare leaves. The
+ * later arm, on those same inputs, would have produced child nodes. Nothing about
+ * this is visible in a parse that succeeds: `ok` is true, the span is right, the
+ * text round-trips. Only the SHAPE moved, and only on the subset of inputs the
+ * flattening arm happens to accept — which is why it survives a test suite that
+ * checks "does it parse" and a corpus diff that checks emitted output. It shows
+ * up in whatever consumes the tree: a language service that lints number tokens,
+ * a formatter, a refactor.
+ *
+ * This is the ordered, consequential half of `divergent-node`. That finding says
+ * two productions build one type and nothing keeps them in sync, and it expressly
+ * allows "the variants exist for a parse-order reason (a fast path tried first)".
+ * This one is the case where that excuse is the bug: the fast path is not
+ * tree-neutral, and here is the list of node types it deletes.
+ */
+export type StructureLossFinding = {
+    kind: 'structure-loss';
+    id: string;
+    /** The `choice` that orders the two arms. */
+    site: Site;
+    /** The `node()` type BOTH arms build. */
+    nodeType: string;
+    /** Index of the flattening arm (the earlier one). */
+    earlier: number;
+    /** Index of the structuring arm it shadows. */
+    later: number;
+    /** The characters on which both arms can start — where the shadowing bites. */
+    on: FirstSet;
+    /** Node types the later arm builds under `nodeType` and the earlier cannot. */
+    lostNodeTypes: string[];
+    earlierShape: string;
+    laterShape: string;
+    suggestion: string;
+};
+/** A `regex()` that hand-rolls a keyword + word boundary. */
+export type KeywordRegexFinding = {
+    kind: 'keyword-regex';
+    id: string;
+    site: Site;
+    source: string;
+    flags: string;
+    words: string[];
+    /** The boundary character class, as a `word()`/`keywords()` `boundary` argument.
+     *  `null` when the regex enumerates a vocabulary with no guard at all. */
+    boundary: string | null;
+    /** `/i` without `/u`: the fold class is NOT `{c, upper(c), lower(c)}`. */
+    caseFoldRisk: boolean;
+    /** Sibling arm indices in the same `choice` that are also hand-rolled keywords. */
+    siblingArms: number[];
+    /**
+     * >= 3 literal alternatives: a fixed VOCABULARY enumerated by hand rather than a
+     * keyword with a guard. The interesting sub-case, because ordering starts to matter
+     * and the list is usually long enough that nobody re-reads it.
+     */
+    vocabulary: boolean;
+    /**
+     * Alternatives are in non-increasing length order. `keywords()` sorts longest-first
+     * by construction; a hand-written alternation does not, and nothing checks it.
+     */
+    longestFirst: boolean;
+    /**
+     * Earlier alternatives that are strict PREFIXES of later ones. Regex alternation is
+     * first-match, so the longer branch is reachable only when a trailing boundary guard
+     * rejects the following character and forces a backtrack (`rescuedByBoundary`).
+     */
+    hazards: {
+        shorter: string;
+        longer: string;
+        at: string;
+        rescuedByBoundary: boolean;
+    }[];
+    /**
+     * At least one hazard is NOT rescued by a boundary guard — a later alternative can
+     * never match. That is a live bug, not a cleanup.
+     */
+    bug: boolean;
+    suggestion: string;
+};
+export type DuplicationReport = {
+    duplicates: DuplicateFinding[];
+    nearDuplicates: NearDuplicateFinding[];
+    regexFragments: RegexFragmentFinding[];
+    regexClasses: RegexClassFinding[];
+    overlaps: ArmOverlapFinding[];
+    rewrites: RewriteFinding[];
+    divergentNodes: DivergentNodeFinding[];
+    structureLoss: StructureLossFinding[];
+    keywordRegexes: KeywordRegexFinding[];
+    /** Ids listed in `accept` that matched no finding — stale entries to prune. */
+    acceptedUnused: string[];
+    stats: {
+        rules: number;
+        /** Distinct combinator INSTANCES reached. */
+        nodes: number;
+        /** Distinct structural shapes among them. */
+        shapes: number;
+    };
+};
+export type AnalyzeDuplicationOptions = {
+    /** Smallest repeated subtree worth reporting, in nodes. Default 3 — which is
+     *  what keeps `optional(ws)` (2 nodes) out of the ranking. */
+    minSize?: number;
+    /** Cap per category, applied AFTER ranking. Default 25. */
+    maxFindings?: number;
+    /** Finding `id`s to suppress — the single per-finding acknowledgement channel,
+     *  mirroring the gating snapshot allowlist. */
+    accept?: Iterable<string>;
+    /** Bind cross-artifact `g.Foo` holes when computing first-sets for `overlaps`. */
+    resolveRef?: RefResolver;
+    /** Name to attribute an unnamed entry to, instead of `<entry>`. */
+    entryName?: string;
+};
+/**
+ * Every alternation branch list in a regex source, at ANY nesting depth. Depth
+ * matters: `/a|b/` and `/x(?:a|b)y/` re-spell the same run, and only one of them
+ * has it at top level.
+ */
+export declare function alternationGroups(src: string): string[][];
+/**
+ * Recognize a `regex()` that hand-rolls what `word()`/`keywords()` owns.
+ *
+ * TWO shapes, because they fail differently:
+ *
+ *  - a word (or word alternation) plus a trailing word-boundary guard —
+ *    `regex(/not(?![-\w])/i)`;
+ *  - a bare alternation of >= 3 literal words with NO guard — a fixed vocabulary
+ *    enumerated by hand. A regex enumerating a fixed vocabulary is a keyword set
+ *    written the hard way: it loses first-set gating, it hand-maintains an ordering
+ *    the combinator guarantees, and with `/i` and no `/u` it inherits the non-ASCII
+ *    case-folding bug `keywords()` fixes internally. The no-guard form is also where
+ *    ordering is load-bearing, since nothing backtracks past a shorter match.
+ *
+ * Returns the words and the boundary CLASS in the exact form `word(str, boundary)` /
+ * `keywords(words, { boundary })` take, so the suggestion names a real call rather
+ * than describing one.
+ */
+export declare function keywordRegexShape(source: string): {
+    words: string[];
+    boundary: string | null;
+} | null;
+/**
+ * Ordering hazards in a hand-written alternation: an EARLIER alternative that is a
+ * strict prefix of a LATER one. Regex alternation is first-match, not longest-match,
+ * so `red|redish` matches only `red` — unless a trailing boundary guard rejects the
+ * character that follows, which makes the engine backtrack into the longer branch.
+ *
+ * That distinction is the whole point of reporting this: without a rescuing guard the
+ * longer word is UNREACHABLE, which is a live bug, not a style finding. `keywords()`
+ * sorts longest-first by construction and the hazard cannot exist there at all.
+ */
+export declare function keywordAlternationHazards(words: readonly string[], boundary: string | null): {
+    shorter: string;
+    longer: string;
+    at: string;
+    rescuedByBoundary: boolean;
+}[];
+export declare function analyzeDuplication(entry: Combinator<unknown>, opts?: AnalyzeDuplicationOptions): DuplicationReport;
+export declare function analyzeDuplicationRules(ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>, opts?: AnalyzeDuplicationOptions): DuplicationReport;
+/**
+ * Every `[...]` in a regex source, INCLUDING the ones inside boundary lookaheads
+ * (`(?![-\w])` yields `-\w`) — those are the same duplication in a different
+ * costume, and the same drift risk.
+ */
+export declare function extractCharClasses(src: string): string[];
+/**
+ * Split a class body into normalized MEMBERS (`a-z`, `\w`, `-`, `€-￿`).
+ * Non-ASCII literals are rewritten to `\uXXXX` so a class typed with a raw `￿`
+ * and one typed with `￿` compare equal — otherwise the diagnostic reports
+ * drift that is only an editor's.
+ */
+export declare function charClassMembers(body: string): string[];
+/**
+ * Whether a hand-rolled separated list can ACTUALLY become `sepBy` — a verdict per
+ * site, not a count. Reporting every match as convertible generates false work: on
+ * the reference Less grammar only a minority are, and the rest are blocked for two
+ * concrete, detectable reasons.
+ */
+export type SepByVerdict = 'convertible' | 'blocked-by-capture' | 'reducer-stride-review';
+export type DuplicationWarnLevel = 'off' | 'warn' | 'error';
+/**
+ * Ranked, actionable lines — same tone and shape as `formatGatingWarnings`: what
+ * it is, where it is, and one concrete thing to do about it.
+ */
+export declare function formatDuplicationFindings(report: DuplicationReport): string[];
+/** Total findings across every category — the number the `'error'` gate keys on. */
+export declare function duplicationFindingCount(report: DuplicationReport): number;
+//# sourceMappingURL=duplication.d.ts.map

package/dist/analysis/duplication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duplication.d.ts","sourceRoot":"","sources":["../../src/analysis/duplication.ts"],"names":[],"mappings":"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"}

package/dist/analysis/gating.d.ts

@@ -134,10 +134,35 @@ export type AnalyzeGatingOptions = {
      */
     resolveRef?: RefResolver;
 };
+/**
+ * A rule the walk could NOT introspect. Its choices were never examined, so no
+ * verdict about it — clean or otherwise — is available.
+ *
+ * This exists because the alternative is silence. A `compose()` result is a map of
+ * FUSED rule functions with no `_def` combinator graph; walking one used to throw a
+ * bare `TypeError: Cannot read properties of undefined (reading 'tag')`, and the
+ * default-on diagnostic swallowed that throw and returned `undefined` — a failed
+ * analysis and a clean grammar were indistinguishable. Every unanalysable input is
+ * now counted and named here, and `formatGatingWarnings` always reports it.
+ */
+export type Unanalysable = {
+    /** The rule name (or seed name) whose walk stopped. */
+    rule: string;
+    /** Why it could not be walked, in terms the caller can act on. */
+    reason: string;
+    kind: 'fused-rule' | 'opaque-artifact' | 'not-a-combinator';
+};
 export type GatingReport = {
     totalChoices: number;
     gated: number;
     recoverable: number;
+    /**
+     * Rules the walk could not introspect (see `Unanalysable`). NON-EMPTY MEANS THE
+     * REPORT IS PARTIAL: `totalChoices === 0` with a non-empty `unanalysable` is a
+     * blind walk, not a clean grammar. Callers that treat an empty `ungated` as a pass
+     * MUST also assert this is empty.
+     */
+    unanalysable: Unanalysable[];
     /** Genuinely-ungated choices NOT in the accepted allowlist — warned + gate-failing. */
     ungated: ChoiceGating[];
     /** Ungated choices whose id was in the accepted allowlist — silent, accepted with intent. */

package/dist/analysis/gating.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gating.d.ts","sourceRoot":"","sources":["../../src/analysis/gating.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gating.d.ts","sourceRoot":"","sources":["../../src/analysis/gating.ts"],"names":[],"mappings":"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"}

package/dist/analysis/grammar.d.ts

@@ -0,0 +1,12 @@
+import { type AnalyzeGatingOptions, type GatingReport } from './gating.ts';
+/** A `rules()` map, a `compose()` result, or any rule-name → value record. */
+export type AnalysableGrammar = Record<string, unknown>;
+/**
+ * Analyze a grammar's choices, resolving a composed grammar back to its carried IR
+ * first. Accepts a `rules()` map (walked directly) or a `compose()` result (recovered).
+ *
+ * The returned report's `unanalysable` is authoritative: non-empty means part of the
+ * grammar was never examined, and a clean `ungated` must NOT be read as a pass.
+ */
+export declare function analyzeGrammarGating(grammar: AnalysableGrammar, opts?: AnalyzeGatingOptions): GatingReport;
+//# sourceMappingURL=grammar.d.ts.map

package/dist/analysis/grammar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../src/analysis/grammar.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAsB,KAAK,oBAAoB,EAAE,KAAK,YAAY,EAAqB,MAAM,aAAa,CAAA;AAGjH,8EAA8E;AAC9E,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEvD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,iBAAiB,EAC1B,IAAI,CAAC,EAAE,oBAAoB,GAC1B,YAAY,CAkBd"}

package/dist/combinators/parser.d.ts

@@ -1,4 +1,5 @@
 import type { Combinator } from '../types.ts';
+import type { HostMode } from '../compiler/codegen.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
@@ -45,6 +46,31 @@ export type RulesOptions = {
      * 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;
 };
 export declare function rules<T extends Record<string, Combinator<unknown>>>(factory: (self: any) => T): T;
 export declare function rules<T extends Record<string, Combinator<unknown>>>(options: RulesOptions, factory: (self: any) => T): T;

package/dist/combinators/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/combinators/parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAI7C;;;;GAIG;AACH,eAAO,MAAM,UAAU,wBAAwB,CAAA;AAO/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;8EAC0E;IAC1E,MAAM,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,CAAA;CACxC,CAAA;AAKD,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA;AAClG,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/combinators/parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAItD;;;;GAIG;AACH,eAAO,MAAM,UAAU,wBAAwB,CAAA;AAO/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;8EAC0E;IAC1E,MAAM,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,CAAA;IACvC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB,CAAA;AAKD,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA;AAClG,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA"}

package/dist/compiler/build-arity.d.ts

@@ -13,6 +13,18 @@ import type { ParserDef } from '../types.ts';
 type NodeDef = Extract<ParserDef, {
     tag: 'node';
 }>;
+/**
+ * Is a positioned-CST host installed for this parse?
+ *
+ * `cstBuildHost` (and the language-service hosts) mark themselves with
+ * `_parsemanCstOutput`. That flag is what re-routes a node with its OWN direct builder
+ * through the host — and therefore what makes the direct builder's formal arity the
+ * WRONG basis for eliding capture, since the consumer is no longer that builder.
+ *
+ * The COMPILED engine answers this at compile time (`hostMode`, 0.37.0). The interpreter
+ * has no compile step, so it asks per parse.
+ */
+export declare function cstOutputHost(build: unknown): boolean;
 /**
  * Confirmed count of simple formal parameters the build declares, or `null` when the
  * source can't be parsed into a plain identifier list (→ caller keeps full capture).

package/dist/compiler/build-arity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-arity.d.ts","sourceRoot":"","sources":["../../src/compiler/build-arity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C;;;;;;;;;;GAUG;AAEH,KAAK,OAAO,GAAG,OAAO,CAAC,SAAS,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAkBlD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuB9D;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAMxD;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAMnD;AAED,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAMtD;AAED,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAMrD"}
+{"version":3,"file":"build-arity.d.ts","sourceRoot":"","sources":["../../src/compiler/build-arity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C;;;;;;;;;;GAUG;AAEH,KAAK,OAAO,GAAG,OAAO,CAAC,SAAS,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAElD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAErD;AAkBD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuB9D;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAMxD;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAMnD;AAED,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAMtD;AAED,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAMrD"}