meld-ast/dist/index.d.cts

AST parser for Meld

import { MeldNode, NodeType, SourceLocation } from 'meld-spec';
export { CodeFenceNode, CommandDefinition, CommandMetadata, CommentNode, DataVarNode, DirectiveData, DirectiveKind, DirectiveNode, ErrorNode, Example, MeldNode, MultiLineBlock, NodeType, Parser, ParserTestCase, PathVarNode, RiskLevel, SourceLocation, TextNode, TextVarNode, ValidationContext, ValidationError, ValidationResult, VariableNode } from 'meld-spec';

/**
 * Options for configuring the parser behavior
 */
interface ParserOptions {
    /**
     * Whether to stop parsing on the first error (default: true)
     */
    failFast?: boolean;
    /**
     * Whether to track source locations for nodes (default: true)
     */
    trackLocations?: boolean;
    /**
     * Whether to validate nodes against meld-spec types (default: true)
     */
    validateNodes?: boolean;
    /**
     * Whether to preserve the outer code fence markers in code fence content (default: true).
     * When true, the content will include the opening and closing fence markers.
     * When false, only the content between the fences will be included.
     */
    preserveCodeFences?: boolean;
    /**
     * Custom error handler for parsing errors
     */
    onError?: (error: MeldAstError) => void;
}
/**
 * Result of a successful parse operation
 */
interface ParseResult {
    /**
     * The AST nodes produced by parsing
     */
    ast: MeldNode[];
    /**
     * Any non-fatal errors encountered during parsing
     * Only present when failFast is false
     */
    errors?: MeldAstError[];
    /**
     * Warnings encountered during parsing
     * These are non-fatal issues that don't prevent parsing but may indicate potential problems
     */
    warnings?: MeldAstError[];
}
/**
 * Error thrown during parsing operations
 */
declare class MeldAstError extends Error {
    readonly location?: {
        start: {
            line: number;
            column: number;
        };
        end: {
            line: number;
            column: number;
        };
    } | undefined;
    readonly cause?: Error | undefined;
    readonly code?: string | undefined;
    constructor(message: string, location?: {
        start: {
            line: number;
            column: number;
        };
        end: {
            line: number;
            column: number;
        };
    } | undefined, cause?: Error | undefined, code?: string | undefined);
    /**
     * Convert error to JSON format for serialization
     */
    toJSON(): {
        name: string;
        message: string;
        location: {
            start: {
                line: number;
                column: number;
            };
            end: {
                line: number;
                column: number;
            };
        } | undefined;
        cause: string | undefined;
        code: string | undefined;
    };
    /**
     * Get a formatted string representation of the error
     */
    toString(): string;
}
/**
 * Error codes for specific parsing failures
 */
declare enum ParseErrorCode {
    SYNTAX_ERROR = "SYNTAX_ERROR",
    VALIDATION_ERROR = "VALIDATION_ERROR",
    INITIALIZATION_ERROR = "INITIALIZATION_ERROR",
    GRAMMAR_ERROR = "GRAMMAR_ERROR"
}
/**
 * Peggy error location information
 */
interface PeggyLocation {
    startLine: number;
    startColumn: number;
    endLine: number;
    endColumn: number;
    offset: number;
    start: {
        offset: number;
        line: number;
        column: number;
    };
    end: {
        offset: number;
        line: number;
        column: number;
    };
}
/**
 * Peggy error structure
 */
interface PeggyError extends Error {
    location: PeggyLocation;
    expected: Array<{
        type: string;
        text?: string;
        description?: string;
    }>;
    found: string | null;
}

/**
 * Parse a Meld document into an AST that conforms to meld-spec types.
 * Includes source locations and proper error handling.
 *
 * @param input - The Meld document to parse
 * @param options - Parser configuration options
 * @returns ParseResult containing the AST and any non-fatal errors
 * @throws MeldAstError on parsing failures when failFast is true
 */
declare function parse$1(input: string, options?: ParserOptions): Promise<ParseResult>;

declare const SyntaxError: {
    new (message: any, expected: any, found: any, location: any): {
        expected: any;
        found: any;
        location: any;
        name: string;
        message: string;
        stack?: string;
        cause?: unknown;
    };
    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
    stackTraceLimit: number;
};
declare function parse(input: string, options?: any): Promise<ParseResult>;

/**
 * Creates a new AST node that conforms to the meld-spec type definitions.
 *
 * @param type - The type of node to create, must be a valid NodeType from meld-spec
 * @param data - Additional data to include in the node (e.g., content, directive info)
 * @param location - Source location information from the parser
 * @returns A properly structured MeldNode with location information
 *
 * @example
 * ```typescript
 * const node = createNode('Text', { content: 'Hello' }, location());
 * ```
 */
declare function createNode(type: NodeType, data: Record<string, any>, location: any): MeldNode;
/**
 * Extracts location information from a Peggy parser location function.
 * Converts Peggy's location format to meld-spec's SourceLocation format.
 *
 * @param location - Function that returns Peggy location information
 * @returns A SourceLocation object conforming to meld-spec
 *
 * @example
 * ```typescript
 * const loc = getLocation(() => parser.location());
 * ```
 */
declare function getLocation(location: () => any): SourceLocation;
/**
 * Joins an array of text parts into a single string.
 * Used primarily for concatenating text nodes in the parser.
 *
 * @param parts - Array of text strings to join
 * @returns The concatenated text
 *
 * @example
 * ```typescript
 * const text = textJoin(['Hello', ' ', 'world']);
 * // Returns: 'Hello world'
 * ```
 */
declare function textJoin(parts: string[]): string;

export { MeldAstError, ParseErrorCode, type ParseResult, type ParserOptions, type PeggyError, type PeggyLocation, SyntaxError, createNode, getLocation, parse as grammarParse, parse$1 as parse, textJoin };