@rcrsr/rill 0.7.1 → 0.8.0

package/dist/types.d.ts

@@ -2,887 +2,15 @@
  * Rill AST Types
  * Based on docs/grammar.ebnf
  */
-export interface SourceLocation {
-    readonly line: number;
-    readonly column: number;
-    readonly offset: number;
-}
-export interface SourceSpan {
-    readonly start: SourceLocation;
-    readonly end: SourceLocation;
-}
-/** Error category determining error ID prefix */
-export type ErrorCategory = 'lexer' | 'parse' | 'runtime' | 'check';
-/** Error severity level */
-export type ErrorSeverity = 'error' | 'warning';
-/**
- * Call stack frame information for error reporting.
- * Represents a single frame in the call stack with location and context.
- */
-export interface CallFrame {
-    /** Source location of the call */
-    readonly location: SourceSpan;
-    /** Name of the function (closure or host function) */
-    readonly functionName?: string | undefined;
-    /** Additional context (e.g., "in each body") */
-    readonly context?: string | undefined;
-}
-/**
- * Example demonstrating an error condition.
- * Used in error documentation to show common scenarios.
- */
-export interface ErrorExample {
-    /** Description of the example scenario (max 100 characters) */
-    readonly description: string;
-    /** Example code demonstrating the error (max 500 characters) */
-    readonly code: string;
-}
-/** Error registry entry containing all metadata for a single error condition */
-export interface ErrorDefinition {
-    /** Format: RILL-{category}{3-digit} (e.g., RILL-R001) */
-    readonly errorId: string;
-    /** Error category (determines ID prefix) */
-    readonly category: ErrorCategory;
-    /** Severity level (defaults to 'error' when omitted) */
-    readonly severity?: ErrorSeverity | undefined;
-    /** Human-readable description (max 50 characters) */
-    readonly description: string;
-    /** Message template with {placeholder} syntax */
-    readonly messageTemplate: string;
-    /** What causes this error (max 200 characters) */
-    readonly cause?: string | undefined;
-    /** How to resolve this error (max 300 characters) */
-    readonly resolution?: string | undefined;
-    /** Example scenarios demonstrating this error (max 3 entries) */
-    readonly examples?: ErrorExample[] | undefined;
-}
-/**
- * Central registry for all error definitions with O(1) lookup.
- * Immutable after initialization.
- */
-export interface ErrorRegistry {
-    get(errorId: string): ErrorDefinition | undefined;
-    has(errorId: string): boolean;
-    readonly size: number;
-    entries(): IterableIterator<[string, ErrorDefinition]>;
-}
-/**
- * Global error registry instance.
- * Read-only singleton initialized at module load.
- */
-export declare const ERROR_REGISTRY: ErrorRegistry;
-/**
- * Renders a message template by replacing placeholders with context values.
- *
- * Placeholder format: {varName}
- * Missing context values render as empty string.
- * Non-string values are coerced via String().
- * Invalid templates (unclosed braces) return template unchanged.
- *
- * @param template - Template string with {placeholder} syntax
- * @param context - Key-value pairs for placeholder replacement
- * @returns Rendered message with placeholders replaced
- *
- * @example
- * renderMessage("Expected {expected}, got {actual}", {expected: "string", actual: "number"})
- * // Returns: "Expected string, got number"
- *
- * @example
- * renderMessage("Hello {name}", {})
- * // Returns: "Hello "
- */
-export declare function renderMessage(template: string, context: Record<string, unknown>): string;
-/**
- * Generates documentation URL for an error ID.
- *
- * Format: https://github.com/rcrsr/rill/blob/v{version}/docs/ref-errors.md#{errorId}
- * Error ID is lowercased in anchor.
- *
- * @param errorId - Error identifier (format: RILL-{category}{3-digit}, e.g., RILL-R001)
- * @param version - Semver version (format: X.Y.Z)
- * @returns Documentation URL, or empty string if inputs are invalid
- *
- * @example
- * getHelpUrl("RILL-R001", "0.4.1")
- * // Returns: "https://github.com/rcrsr/rill/blob/v0.4.1/docs/ref-errors.md#rill-r001"
- *
- * @example
- * getHelpUrl("invalid", "0.4.1")
- * // Returns: ""
- */
-export declare function getHelpUrl(errorId: string, version: string): string;
-/**
- * Factory function for creating errors from registry.
- *
- * Looks up error definition from registry, renders message template with context,
- * and creates RillError with structured metadata.
- *
- * @param errorId - Error identifier (format: RILL-{category}{3-digit})
- * @param context - Key-value pairs for template placeholder replacement
- * @param location - Source location where error occurred (optional)
- * @returns RillError instance with rendered message
- * @throws TypeError if errorId is not found in registry
- *
- * @example
- * createError("RILL-R005", { name: "foo" }, location)
- * // Creates RuntimeError: "Variable foo is not defined at 1:5"
- *
- * @example
- * createError("RILL-X999", {})
- * // Throws: TypeError("Unknown error ID: RILL-X999")
- */
-export declare function createError(errorId: string, context: Record<string, unknown>, location?: SourceLocation | undefined): RillError;
-/** Structured error data for host applications */
-export interface RillErrorData {
-    readonly errorId: string;
-    readonly helpUrl?: string | undefined;
-    readonly message: string;
-    readonly location?: SourceLocation | undefined;
-    readonly context?: Record<string, unknown> | undefined;
-}
-/**
- * Base error class for all Rill errors.
- * Provides structured data for host applications to format as needed.
- */
-export declare class RillError extends Error {
-    readonly errorId: string;
-    readonly helpUrl: string | undefined;
-    readonly location?: SourceLocation | undefined;
-    readonly context?: Record<string, unknown> | undefined;
-    constructor(data: RillErrorData);
-    /** Get structured error data for custom formatting */
-    toData(): RillErrorData;
-    /** Format error for display (can be overridden by host) */
-    format(formatter?: (data: RillErrorData) => string): string;
-}
-/** Parse-time errors */
-export declare class ParseError extends RillError {
-    constructor(errorId: string, message: string, location: SourceLocation, context?: Record<string, unknown>);
-}
-/** Runtime execution errors */
-export declare class RuntimeError extends RillError {
-    constructor(errorId: string, message: string, location?: SourceLocation, context?: Record<string, unknown>);
-    /** Create from an AST node */
-    static fromNode(errorId: string, message: string, node?: {
-        span: SourceSpan;
-    }, context?: Record<string, unknown>): RuntimeError;
-}
-/** Timeout errors */
-export declare class TimeoutError extends RuntimeError {
-    readonly functionName: string;
-    readonly timeoutMs: number;
-    constructor(functionName: string, timeoutMs: number, location?: SourceLocation);
-}
-/** Auto-exception errors (when $_ matches a pattern) */
-export declare class AutoExceptionError extends RuntimeError {
-    readonly pattern: string;
-    readonly matchedValue: string;
-    constructor(pattern: string, matchedValue: string, location?: SourceLocation);
-}
-/** Abort errors (when execution is cancelled via AbortSignal) */
-export declare class AbortError extends RuntimeError {
-    constructor(location?: SourceLocation);
-}
-export declare const TOKEN_TYPES: {
-    readonly STRING: "STRING";
-    readonly NUMBER: "NUMBER";
-    readonly TRUE: "TRUE";
-    readonly FALSE: "FALSE";
-    readonly IDENTIFIER: "IDENTIFIER";
-    readonly DOLLAR: "DOLLAR";
-    readonly PIPE_VAR: "PIPE_VAR";
-    readonly ARROW: "ARROW";
-    readonly CAPTURE_ARROW: "CAPTURE_ARROW";
-    readonly DOT: "DOT";
-    readonly QUESTION: "QUESTION";
-    readonly AT: "AT";
-    readonly CARET: "CARET";
-    readonly COLON: "COLON";
-    readonly DOUBLE_COLON: "DOUBLE_COLON";
-    readonly COMMA: "COMMA";
-    readonly BANG: "BANG";
-    readonly AND: "AND";
-    readonly OR: "OR";
-    readonly NULLISH_COALESCE: "NULLISH_COALESCE";
-    readonly DOT_QUESTION: "DOT_QUESTION";
-    readonly AMPERSAND: "AMPERSAND";
-    readonly ASSIGN: "ASSIGN";
-    readonly EQ: "EQ";
-    readonly NE: "NE";
-    readonly LT: "LT";
-    readonly GT: "GT";
-    readonly LE: "LE";
-    readonly GE: "GE";
-    readonly STAR_LT: "STAR_LT";
-    readonly SLASH_LT: "SLASH_LT";
-    readonly UNDERSCORE: "UNDERSCORE";
-    readonly ELLIPSIS: "ELLIPSIS";
-    readonly PIPE_BAR: "PIPE_BAR";
-    readonly PLUS: "PLUS";
-    readonly MINUS: "MINUS";
-    readonly STAR: "STAR";
-    readonly SLASH: "SLASH";
-    readonly PERCENT: "PERCENT";
-    readonly LPAREN: "LPAREN";
-    readonly RPAREN: "RPAREN";
-    readonly LBRACE: "LBRACE";
-    readonly RBRACE: "RBRACE";
-    readonly LBRACKET: "LBRACKET";
-    readonly RBRACKET: "RBRACKET";
-    readonly BREAK: "BREAK";
-    readonly RETURN: "RETURN";
-    readonly PASS: "PASS";
-    readonly ASSERT: "ASSERT";
-    readonly ERROR: "ERROR";
-    readonly EACH: "EACH";
-    readonly MAP: "MAP";
-    readonly FOLD: "FOLD";
-    readonly FILTER: "FILTER";
-    readonly FRONTMATTER_DELIM: "FRONTMATTER_DELIM";
-    readonly NEWLINE: "NEWLINE";
-    readonly COMMENT: "COMMENT";
-    readonly EOF: "EOF";
-};
-export type TokenType = (typeof TOKEN_TYPES)[keyof typeof TOKEN_TYPES];
-export interface Token {
-    readonly type: TokenType;
-    readonly value: string;
-    readonly span: SourceSpan;
-}
-export type NodeType = 'Script' | 'Frontmatter' | 'Closure' | 'ClosureParam' | 'Statement' | 'PipeChain' | 'PostfixExpr' | 'MethodCall' | 'Invoke' | 'HostCall' | 'ClosureCall' | 'PipeInvoke' | 'Variable' | 'Capture' | 'Conditional' | 'WhileLoop' | 'DoWhileLoop' | 'Block' | 'StringLiteral' | 'Interpolation' | 'NumberLiteral' | 'BoolLiteral' | 'Tuple' | 'ListSpread' | 'Dict' | 'DictEntry' | 'Break' | 'Return' | 'Pass' | 'Assert' | 'BinaryExpr' | 'UnaryExpr' | 'InnerExpr' | 'GroupedExpr' | 'ClosureChain' | 'Destructure' | 'DestructPattern' | 'Slice' | 'Enumerate' | 'Spread' | 'TypeAssertion' | 'TypeCheck' | 'AnnotatedStatement' | 'NamedArg' | 'SpreadArg' | 'EachExpr' | 'MapExpr' | 'FoldExpr' | 'FilterExpr' | 'RecoveryError' | 'Error';
-interface BaseNode {
-    readonly span: SourceSpan;
-}
-export interface ScriptNode extends BaseNode {
-    readonly type: 'Script';
-    readonly frontmatter: FrontmatterNode | null;
-    /** Statements in the script. May include RecoveryErrorNode when parsed with recoveryMode. */
-    readonly statements: (StatementNode | AnnotatedStatementNode | RecoveryErrorNode)[];
-}
-export interface FrontmatterNode extends BaseNode {
-    readonly type: 'Frontmatter';
-    readonly content: string;
-}
-/**
- * Closure: |params| body
- * First-class closure with optional typed parameters and defaults.
- * Scope rules: captures outer (read-only), local mutable.
- *
- * Body can be:
- * - Simple: |x| $x (postfix-expr)
- * - Grouped: |x| ($x * 2) (compound expression)
- * - Block: |x| { $a ↵ $b } (multiple statements)
- */
-export interface ClosureNode extends BaseNode {
-    readonly type: 'Closure';
-    readonly params: ClosureParamNode[];
-    readonly body: BodyNode;
-}
-/**
- * Function parameter with optional type and default value.
- * - (x) { }           -- untyped
- * - (x: string) { }   -- typed
- * - (x: string = "hi") { }  -- typed with default
- * - ^(key: value) (x) { }  -- with parameter annotations
- */
-export interface ClosureParamNode extends BaseNode {
-    readonly type: 'ClosureParam';
-    readonly name: string;
-    readonly typeName: 'string' | 'number' | 'bool' | null;
-    readonly defaultValue: LiteralNode | null;
-    readonly annotations?: AnnotationArg[] | undefined;
-}
-/**
- * Statement: a pipe chain expression.
- * Termination (capture/break/return) is now part of PipeChainNode.
- */
-export interface StatementNode extends BaseNode {
-    readonly type: 'Statement';
-    readonly expression: PipeChainNode;
-}
-/**
- * Recovery error node for parse error recovery mode.
- * Represents unparseable content that was skipped during error recovery.
- * Only appears in ASTs when parsing with `recoveryMode: true`.
- */
-export interface RecoveryErrorNode extends BaseNode {
-    readonly type: 'RecoveryError';
-    /** The error message describing what went wrong */
-    readonly message: string;
-    /** The raw source text that could not be parsed */
-    readonly text: string;
-}
-/**
- * Annotated statement: ^(key: value, ...) statement
- * Annotations modify operational parameters for statements.
- * They prefix statements and bind to the immediately following construct.
- *
- * Examples:
- *   ^(limit: 100) $items @ process()
- *   ^(timeout: 30) fetch($url)
- *   ^(retry: 3, backoff: 1.5) api_call()
- */
-export interface AnnotatedStatementNode extends BaseNode {
-    readonly type: 'AnnotatedStatement';
-    readonly annotations: AnnotationArg[];
-    readonly statement: StatementNode;
-}
-/**
- * Annotation argument: named or spread
- * Reuses similar structure to dict entries but with spread support.
- */
-export type AnnotationArg = NamedArgNode | SpreadArgNode;
-/**
- * Named annotation argument: key: value
- * Example: limit: 100, timeout: 30
- */
-export interface NamedArgNode extends BaseNode {
-    readonly type: 'NamedArg';
-    readonly name: string;
-    readonly value: ExpressionNode;
-}
-/**
- * Spread annotation argument: *expr
- * Example: *$opts spreads tuple keys as annotations
- */
-export interface SpreadArgNode extends BaseNode {
-    readonly type: 'SpreadArg';
-    readonly expression: ExpressionNode;
-}
-/** Rill type names for type annotations */
-export type RillTypeName = 'string' | 'number' | 'bool' | 'closure' | 'list' | 'dict' | 'tuple';
-export interface CaptureNode extends BaseNode {
-    readonly type: 'Capture';
-    readonly name: string;
-    /** Optional explicit type annotation: $name:string */
-    readonly typeName: RillTypeName | null;
-}
-/**
- * Break: exit loop with current pipe value.
- * Used as chain terminator: $x -> break
- * Or bare: break (implicit $ -> break)
- */
-export interface BreakNode extends BaseNode {
-    readonly type: 'Break';
-}
-/**
- * Return: exit closure with current pipe value.
- * Used as chain terminator: $x -> return
- * Or bare: return (implicit $ -> return)
- */
-export interface ReturnNode extends BaseNode {
-    readonly type: 'Return';
-}
-/**
- * Pass: pass through pipe value unchanged.
- * Used as chain terminator: $x -> pass
- * Or bare: pass (implicit $ -> pass)
- */
-export interface PassNode extends BaseNode {
-    readonly type: 'Pass';
-}
-/**
- * Assert: halt execution if condition is false.
- * Syntax: assert condition
- * Or: assert condition "custom error message"
- */
-export interface AssertNode extends BaseNode {
-    readonly type: 'Assert';
-    readonly condition: ExpressionNode;
-    readonly message: StringLiteralNode | null;
-}
-/**
- * Error: explicitly raise an error with a message.
- * Syntax: error "message"
- * Or: error "interpolated {$var} message"
- */
-export interface ErrorNode extends BaseNode {
-    readonly type: 'Error';
-    readonly message: StringLiteralNode | null;
-}
-export type ExpressionNode = PipeChainNode;
-/** Chain terminator: capture, break, or return */
-export type ChainTerminator = CaptureNode | BreakNode | ReturnNode;
-export interface PipeChainNode extends BaseNode {
-    readonly type: 'PipeChain';
-    readonly head: ArithHead;
-    /**
-     * Pipe targets and inline captures.
-     * Inline captures act as implicit .set() — store value and return unchanged.
-     * Semantically: "-> $a ->" ≡ "-> $a.set($) ->"
-     */
-    readonly pipes: (PipeTargetNode | CaptureNode)[];
-    /**
-     * Chain terminator: final capture, break, or return.
-     * Examples:
-     *   $x -> $y         terminator = Capture($y)
-     *   $x -> break      terminator = Break
-     *   $x -> return     terminator = Return
-     *   $x -> .method    terminator = null
-     */
-    readonly terminator: ChainTerminator | null;
-}
-export interface PostfixExprNode extends BaseNode {
-    readonly type: 'PostfixExpr';
-    readonly primary: PrimaryNode;
-    readonly methods: (MethodCallNode | InvokeNode)[];
-    readonly defaultValue: BodyNode | null;
-}
-export type PrimaryNode = LiteralNode | VariableNode | HostCallNode | ClosureCallNode | MethodCallNode | ConditionalNode | WhileLoopNode | DoWhileLoopNode | BlockNode | AssertNode | ErrorNode | PassNode | GroupedExprNode | SpreadNode | TypeAssertionNode | TypeCheckNode;
-export type PipeTargetNode = HostCallNode | ClosureCallNode | MethodCallNode | PipeInvokeNode | ConditionalNode | WhileLoopNode | DoWhileLoopNode | BlockNode | ClosureNode | StringLiteralNode | DictNode | TupleNode | GroupedExprNode | ClosureChainNode | DestructureNode | SliceNode | SpreadNode | TypeAssertionNode | TypeCheckNode | EachExprNode | MapExprNode | FoldExprNode | FilterExprNode | PostfixExprNode | VariableNode | AssertNode | ErrorNode;
-/** Invoke pipe value as a closure: -> $() or -> $(arg1, arg2) */
-export interface PipeInvokeNode extends BaseNode {
-    readonly type: 'PipeInvoke';
-    readonly args: ExpressionNode[];
-}
-export type LiteralNode = StringLiteralNode | NumberLiteralNode | BoolLiteralNode | TupleNode | DictNode | ClosureNode;
-export interface StringLiteralNode extends BaseNode {
-    readonly type: 'StringLiteral';
-    readonly parts: (string | InterpolationNode)[];
-    readonly isMultiline: boolean;
-}
-export interface InterpolationNode extends BaseNode {
-    readonly type: 'Interpolation';
-    readonly expression: ExpressionNode;
-}
-export interface NumberLiteralNode extends BaseNode {
-    readonly type: 'NumberLiteral';
-    readonly value: number;
-}
-export interface BoolLiteralNode extends BaseNode {
-    readonly type: 'BoolLiteral';
-    readonly value: boolean;
-}
-export interface TupleNode extends BaseNode {
-    readonly type: 'Tuple';
-    readonly elements: (ExpressionNode | ListSpreadNode)[];
-    readonly defaultValue: BodyNode | null;
-}
-export interface ListSpreadNode extends BaseNode {
-    readonly type: 'ListSpread';
-    readonly expression: ExpressionNode;
-}
-export interface DictNode extends BaseNode {
-    readonly type: 'Dict';
-    readonly entries: DictEntryNode[];
-    readonly defaultValue: BodyNode | null;
-}
-export interface DictKeyVariable {
-    readonly kind: 'variable';
-    readonly variableName: string;
-}
-export interface DictKeyComputed {
-    readonly kind: 'computed';
-    readonly expression: ExpressionNode;
-}
-export interface DictEntryNode extends BaseNode {
-    readonly type: 'DictEntry';
-    readonly key: string | number | boolean | TupleNode | DictKeyVariable | DictKeyComputed;
-    readonly value: ExpressionNode;
-}
-export type BinaryOp = '+' | '-' | '*' | '/' | '%' | '&&' | '||' | '==' | '!=' | '<' | '>' | '<=' | '>=';
-/**
- * Expression head types for binary/unary expressions.
- * Includes arithmetic (+, -, *, /, %) and logical (&&, ||, !) operators.
- */
-export type ArithHead = BinaryExprNode | UnaryExprNode | PostfixExprNode;
-/**
- * Binary expression: left op right
- * Arithmetic: ($x + 5), ($a * $b), (2 + 3 * 4)
- * Logical: ($a && $b), ($x || $y)
- */
-export interface BinaryExprNode extends BaseNode {
-    readonly type: 'BinaryExpr';
-    readonly op: BinaryOp;
-    readonly left: ArithHead;
-    readonly right: ArithHead;
-}
-/**
- * Unary expression: -operand or !operand
- * Examples: (-5), (-$x), (!$ready)
- */
-export interface UnaryExprNode extends BaseNode {
-    readonly type: 'UnaryExpr';
-    readonly op: '-' | '!';
-    readonly operand: UnaryExprNode | PostfixExprNode;
-}
-/**
- * Grouped expression: ( expression )
- * Single-expression block with () delimiters.
- * Provides scoping — captures inside are local and not visible outside.
- *
- * Scoping rules identical to blocks:
- *   ("hello" -> $local)  — $local is scoped to group, returns "hello"
- */
-export interface GroupedExprNode extends BaseNode {
-    readonly type: 'GroupedExpr';
-    readonly expression: PipeChainNode;
-}
-/**
- * Simple body: expression that can follow closure params, conditionals, or loops.
- * No naked compound expressions — arithmetic/pipes/booleans must be grouped.
- *
- * Valid: block, grouped, or postfix-expr (variable, literal, method, function call)
- * Examples:
- *   |x| $x           — postfix-expr
- *   |x| ($x * 2)     — grouped (compound)
- *   |x| { $a ↵ $b }  — block (multiple statements)
- */
-export type BodyNode = BlockNode | GroupedExprNode | PostfixExprNode | PipeChainNode;
-export interface VariableNode extends BaseNode {
-    readonly type: 'Variable';
-    readonly name: string | null;
-    readonly isPipeVar: boolean;
-    /** Ordered chain of property accesses: .name, [0], .$var, etc. */
-    readonly accessChain: PropertyAccess[];
-    /**
-     * Default value for null-coalescing: $data.path ?? default
-     * If property access returns null/missing, use this value instead.
-     */
-    readonly defaultValue: BodyNode | null;
-    /**
-     * Existence check on final path element: $data.?path
-     * Returns boolean (true if path exists).
-     * When set, implies safe traversal (no error on missing intermediate paths).
-     */
-    readonly existenceCheck: ExistenceCheck | null;
-}
-/**
- * Existence check configuration.
- * For .?path (just exists) or .?path&type (exists AND type matches).
- */
-export interface ExistenceCheck {
-    /** The final field/index being checked for existence */
-    readonly finalAccess: FieldAccess;
-    /** Optional type check: returns true only if exists AND matches type */
-    readonly typeName: RillTypeName | null;
-}
-/**
- * Field access element in a property access chain (dot-based).
- *
- * Access forms:
- * - literal: .identifier (string key)
- * - variable: .$var (variable as key)
- * - computed: .(expr) (computed expression)
- * - block: .{block} (block returning key)
- * - alternatives: .(a || b) (try keys left-to-right)
- *
- * Note: Numeric indices use bracket syntax [0], [-1] instead of dot.
- */
-export type FieldAccess = FieldAccessLiteral | FieldAccessVariable | FieldAccessComputed | FieldAccessBlock | FieldAccessAlternatives | FieldAccessAnnotation;
-/** Literal field access: .identifier */
-export interface FieldAccessLiteral {
-    readonly kind: 'literal';
-    readonly field: string;
-}
-/** Variable as key: .$var or .$ (pipe variable) */
-export interface FieldAccessVariable {
-    readonly kind: 'variable';
-    readonly variableName: string | null;
-}
-/** Computed expression: .(expr) */
-export interface FieldAccessComputed {
-    readonly kind: 'computed';
-    readonly expression: ExpressionNode;
-}
-/** Block returning key: .{block} */
-export interface FieldAccessBlock {
-    readonly kind: 'block';
-    readonly block: BlockNode;
-}
-/** Alternatives (try keys left-to-right): .(a || b) */
-export interface FieldAccessAlternatives {
-    readonly kind: 'alternatives';
-    readonly alternatives: string[];
-}
-/** Annotation reflection: .^key */
-export interface FieldAccessAnnotation {
-    readonly kind: 'annotation';
-    readonly key: string;
-}
-/**
- * Bracket index access: [expr]
- * Used for numeric indexing into lists/strings.
- * Expression can be positive (from start) or negative (from end).
- */
-export interface BracketAccess {
-    /** Discriminator for the unified PropertyAccess type */
-    readonly accessKind: 'bracket';
-    /** The index expression (evaluates to number) */
-    readonly expression: ExpressionNode;
-    /** Source span from opening [ to closing ] (inclusive) */
-    readonly span: SourceSpan;
-}
-/**
- * Unified property access type.
- * Used to maintain order of mixed dot and bracket accesses.
- * e.g., $data[0].name[1] has accesses: [bracket(0), field(name), bracket(1)]
- */
-export type PropertyAccess = FieldAccess | BracketAccess;
-export interface HostCallNode extends BaseNode {
-    readonly type: 'HostCall';
-    readonly name: string;
-    readonly args: ExpressionNode[];
-}
-export interface MethodCallNode extends BaseNode {
-    readonly type: 'MethodCall';
-    readonly name: string;
-    readonly args: ExpressionNode[];
-    readonly receiverSpan: SourceSpan | null;
-}
-/** Postfix invocation: expr(args) - calls the result of expr as a closure */
-export interface InvokeNode extends BaseNode {
-    readonly type: 'Invoke';
-    readonly args: ExpressionNode[];
-}
-/** Call a closure stored in a variable: $fn(args) or $obj.method(args) */
-export interface ClosureCallNode extends BaseNode {
-    readonly type: 'ClosureCall';
-    readonly name: string;
-    readonly accessChain: string[];
-    readonly args: ExpressionNode[];
-}
-/**
- * Conditional: ?($cond) body : else
- * Body can be any simple-body (block, grouped, or postfix-expr).
- *
- * Examples:
- *   ?($x > 0) "positive" : "negative"    — literals
- *   ?($x > 0) ($x * 2) : ($x / 2)        — grouped
- *   ?($x > 0) { complex } : { other }    — blocks
- */
-export interface ConditionalNode extends BaseNode {
-    readonly type: 'Conditional';
-    readonly input: ExpressionNode | null;
-    readonly condition: BodyNode | null;
-    readonly thenBranch: BodyNode;
-    readonly elseBranch: BodyNode | ConditionalNode | null;
-}
-export interface WhileLoopNode extends BaseNode {
-    readonly type: 'WhileLoop';
-    readonly condition: ExpressionNode;
-    readonly body: BodyNode;
-}
-export interface DoWhileLoopNode extends BaseNode {
-    readonly type: 'DoWhileLoop';
-    readonly input: ExpressionNode | null;
-    readonly body: BodyNode;
-    readonly condition: BodyNode;
-}
-export interface BlockNode extends BaseNode {
-    readonly type: 'Block';
-    readonly statements: (StatementNode | AnnotatedStatementNode)[];
-}
-/**
- * Collection operator body types.
- * These are the valid forms for the body of each/map/fold operators.
- */
-export type IteratorBody = ClosureNode | BlockNode | GroupedExprNode | VariableNode | PostfixExprNode | SpreadNode | HostCallNode;
-/**
- * Each expression: sequential iteration returning list of all results.
- *
- * Syntax forms:
- *   collection -> each |x| body
- *   collection -> each { body }
- *   collection -> each (expr)
- *   collection -> each $fn
- *   collection -> each $
- *
- * With accumulator:
- *   collection -> each(init) { body }         -- $@ is accumulator
- *   collection -> each |x, acc = init| body   -- $acc is accumulator
- *
- * Returns: list of all body results (or scan results if accumulator)
- */
-export interface EachExprNode extends BaseNode {
-    readonly type: 'EachExpr';
-    /** The body to execute for each element */
-    readonly body: IteratorBody;
-    /**
-     * Optional accumulator initial value (for block form with $@ access).
-     * null when using inline closure with accumulator (it's in the closure params)
-     * or when no accumulator is used.
-     */
-    readonly accumulator: ExpressionNode | null;
-}
-/**
- * Map expression: parallel iteration returning list of all results.
- *
- * Syntax forms:
- *   collection -> map |x| body
- *   collection -> map { body }
- *   collection -> map (expr)
- *   collection -> map $fn
- *   collection -> map $
- *
- * No accumulator (parallel execution has no "previous").
- * Concurrency limit via ^(limit: N) annotation.
- *
- * Returns: list of all body results (order preserved)
- */
-export interface MapExprNode extends BaseNode {
-    readonly type: 'MapExpr';
-    /** The body to execute for each element (in parallel) */
-    readonly body: IteratorBody;
-}
-/**
- * Fold expression: sequential reduction returning final result only.
- *
- * Syntax forms:
- *   collection -> fold |x, acc = init| body   -- $acc is accumulator
- *   collection -> fold(init) { body }         -- $@ is accumulator
- *   collection -> fold $fn                    -- fn must have accumulator param
- *
- * Accumulator is required.
- *
- * Returns: final accumulated value only
- */
-export interface FoldExprNode extends BaseNode {
-    readonly type: 'FoldExpr';
-    /** The body to execute for each element */
-    readonly body: IteratorBody;
-    /**
-     * Accumulator initial value (for block form with $@ access).
-     * null when using inline closure (accumulator is in closure params).
-     */
-    readonly accumulator: ExpressionNode | null;
-}
-/**
- * Filter expression: parallel filtering returning elements where predicate is truthy.
- *
- * Syntax forms:
- *   collection -> filter |x| body
- *   collection -> filter { body }
- *   collection -> filter (expr)
- *   collection -> filter $fn
- *
- * Predicate returns truthy/falsy. Elements where predicate is truthy are kept.
- *
- * Returns: list of elements where body was truthy
- */
-export interface FilterExprNode extends BaseNode {
-    readonly type: 'FilterExpr';
-    /** The predicate body to evaluate for each element */
-    readonly body: IteratorBody;
-}
-/**
- * Sequential spread: $input -> @$closures
- * Chains closures where each receives the previous result.
- *
- * Equivalent to a fold: $input -> [$f, $g, $h] -> @ { $() }
- * - With stored closures: the $ is the current closure, $() invokes it
- * - With inline blocks: $ is the accumulated value directly
- */
-export interface ClosureChainNode extends BaseNode {
-    readonly type: 'ClosureChain';
-    readonly target: ExpressionNode;
-}
-/**
- * Destructure operator: *<...>
- * Extracts elements from tuples/dicts into variables.
- *
- * Tuple: [1, 2, 3] -> *<$a, $b, $c>
- * Dict:  [name: "x"] -> *<name: $n>
- * Nested: [[1, 2], 3] -> *<*<$a, $b>, $c>
- */
-export interface DestructureNode extends BaseNode {
-    readonly type: 'Destructure';
-    readonly elements: DestructPatternNode[];
-}
-/**
- * Element in a destructure pattern.
- * Can be: typed variable, key-variable pair, skip placeholder, or nested destructure.
- */
-export interface DestructPatternNode extends BaseNode {
-    readonly type: 'DestructPattern';
-    readonly kind: 'variable' | 'keyValue' | 'skip' | 'nested';
-    /** Variable name (for 'variable' and 'keyValue' kinds) */
-    readonly name: string | null;
-    /** Key name (for 'keyValue' kind - dict destructuring) */
-    readonly key: string | null;
-    /** Type annotation (for 'variable' and 'keyValue' kinds) */
-    readonly typeName: RillTypeName | null;
-    /** Nested destructure pattern (for 'nested' kind) */
-    readonly nested: DestructureNode | null;
-}
-/**
- * Slice operator: /<start:stop:step>
- * Extracts a portion of a tuple or string using Python-style slicing.
- *
- * Examples:
- *   $tuple -> /<0:3>       # elements 0, 1, 2
- *   $tuple -> /<::-1>      # reversed
- *   "hello" -> /<1:4>      # "ell"
- */
-export interface SliceNode extends BaseNode {
-    readonly type: 'Slice';
-    /** Start index (null = from beginning) */
-    readonly start: SliceBoundNode | null;
-    /** Stop index (null = to end) */
-    readonly stop: SliceBoundNode | null;
-    /** Step (null = 1) */
-    readonly step: SliceBoundNode | null;
-}
-/** A slice bound: number, variable, or grouped expression */
-export type SliceBoundNode = NumberLiteralNode | VariableNode | GroupedExprNode;
-/**
- * Spread operator: *expr or -> *
- * Converts tuple or dict to args type for unpacking at closure invocation.
- *
- * Prefix form: *[1, 2, 3], *$tuple, *[x: 1, y: 2]
- * Pipe target form: [1, 2, 3] -> *
- *
- * Creates an args value that unpacks into separate arguments when passed to a closure.
- */
-export interface SpreadNode extends BaseNode {
-    readonly type: 'Spread';
-    /** The expression to spread (null when used as pipe target: -> *) */
-    readonly operand: ExpressionNode | null;
-}
-/**
- * Type assertion: expr:type
- * Asserts that the expression evaluates to the specified type.
- * Returns the value unchanged if assertion passes, errors on mismatch.
- *
- * Examples:
- *   fetchData():string                # assert result is string
- *   $val -> :number -> process()      # assert pipe value is number
- *   "hello":string                    # "hello" (pass)
- *   "hello":number                    # Error: expected number, got string
- *
- * When operand is null, it acts on the implicit $:
- *   :string ≡ $:string
- */
-export interface TypeAssertionNode extends BaseNode {
-    readonly type: 'TypeAssertion';
-    /** The expression to assert (null for bare :type which uses $) */
-    readonly operand: PostfixExprNode | null;
-    /** The expected type */
-    readonly typeName: RillTypeName;
-}
-/**
- * Type check: expr:?type
- * Checks if the expression evaluates to the specified type.
- * Returns true if types match, false otherwise.
- *
- * Examples:
- *   fetchData():?string               # is result a string?
- *   $val -> :?number -> process()     # is pipe value a number?
- *   "hello":?string                   # true
- *   "hello":?number                   # false
- *
- * When operand is null, it checks the implicit $:
- *   :?string ≡ $:?string
- */
-export interface TypeCheckNode extends BaseNode {
-    readonly type: 'TypeCheck';
-    /** The expression to check (null for bare :?type which uses $) */
-    readonly operand: PostfixExprNode | null;
-    /** The type to check for */
-    readonly typeName: RillTypeName;
-}
-export type SimplePrimaryNode = LiteralNode | VariableNode | HostCallNode | MethodCallNode | BlockNode | BinaryExprNode | UnaryExprNode | GroupedExprNode | PostfixExprNode | TypeAssertionNode | TypeCheckNode;
-export type ASTNode = ScriptNode | FrontmatterNode | ClosureNode | ClosureParamNode | StatementNode | CaptureNode | BreakNode | ReturnNode | PassNode | AssertNode | PipeChainNode | PostfixExprNode | MethodCallNode | InvokeNode | HostCallNode | ClosureCallNode | PipeInvokeNode | VariableNode | ConditionalNode | WhileLoopNode | DoWhileLoopNode | BlockNode | StringLiteralNode | InterpolationNode | NumberLiteralNode | BoolLiteralNode | TupleNode | ListSpreadNode | DictNode | DictEntryNode | BinaryExprNode | UnaryExprNode | GroupedExprNode | ClosureChainNode | DestructureNode | DestructPatternNode | SliceNode | SpreadNode | TypeAssertionNode | TypeCheckNode | AnnotatedStatementNode | NamedArgNode | SpreadArgNode | EachExprNode | MapExprNode | FoldExprNode | FilterExprNode | RecoveryErrorNode | ErrorNode;
+export * from './source-location.js';
+export * from './error-registry.js';
+export * from './value-types.js';
+export * from './token-types.js';
+export * from './ast-nodes.js';
+export * from './ast-unions.js';
+export * from './error-classes.js';
+import type { ScriptNode } from './ast-nodes.js';
+import type { ParseError } from './error-classes.js';
 /**
  * Options for the parser.
  */
@@ -907,5 +35,4 @@ export interface ParseResult {
     /** True if parsing completed without errors */
     readonly success: boolean;
 }
-export {};
 //# sourceMappingURL=types.d.ts.map