import type { Combinator, FieldMap } from '../types.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 declare function unwrapChild(child: unknown): unknown;
/**
 * 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 declare function missingInferredType(): never;
export declare function projectChild(children: ReadonlyArray<unknown>, project: number, type: string): unknown;
export declare 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 declare 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 declare function node<N, const Tags extends readonly string[] = readonly never[]>(combinator: Combinator<unknown>, opts?: NodeOptions<Tags>): NodeCombinator<N, never, Tags[number]>;
export declare 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]>;
export declare 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 declare 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 {};
//# sourceMappingURL=node.d.ts.map