import { MeldNode, DirectiveNode } from 'meld-spec';
import * as fsExtra from 'fs-extra';
import { Stats } from 'fs-extra';
import { Stats as Stats$1 } from 'fs';
import * as path from 'path';

/**
 * @package
 * Core event system for state tracking.
 *
 * @remarks
 * Provides event emission and handling for state operations.
 */
/**
 * Core state event types as defined in the instrumentation plan
 */
type StateEventType = 'create' | 'clone' | 'transform' | 'merge' | 'error';
/**
 * Base state event interface
 */
interface StateEvent {
    type: StateEventType;
    stateId: string;
    source: string;
    timestamp: number;
    location?: {
        file?: string;
        line?: number;
        column?: number;
    };
}
/**
 * Event handler function type
 */
type StateEventHandler = (event: StateEvent) => void | Promise<void>;
/**
 * Event filter predicate
 */
type StateEventFilter = (event: StateEvent) => boolean;
/**
 * Handler registration options
 */
interface StateEventHandlerOptions {
    filter?: StateEventFilter;
}
/**
 * Core state event service interface
 */
interface IStateEventService {
    /**
     * Register an event handler with optional filtering
     */
    on(type: StateEventType, handler: StateEventHandler, options?: StateEventHandlerOptions): void;
    /**
     * Remove an event handler
     */
    off(type: StateEventType, handler: StateEventHandler): void;
    /**
     * Emit a state event
     */
    emit(event: StateEvent): Promise<void>;
    /**
     * Get all registered handlers for an event type
     */
    getHandlers(type: StateEventType): Array<{
        handler: StateEventHandler;
        options?: StateEventHandlerOptions;
    }>;
}

/**
 * @package
 * Interface for state tracking service.
 */
interface IStateTrackingService {
    /**
     * Register a state with the tracking service.
     * @param metadata - The state metadata to register
     */
    registerState(metadata: Partial<StateMetadata>): void;
    /**
     * Add a relationship between two states.
     * @param sourceId - The source state ID
     * @param targetId - The target state ID
     * @param type - The type of relationship
     */
    addRelationship(sourceId: string, targetId: string, type: 'parent-child' | 'merge-source' | 'merge-target'): void;
    /**
     * Get the complete lineage of a state from root to the given state.
     * @param stateId - The ID of the state to get lineage for
     * @param visited - Set of visited states to prevent cycles
     * @returns Array of state IDs representing the lineage from root to target state
     */
    getStateLineage(stateId: string, visited?: Set<string>): string[];
    /**
     * Get all descendants of a state.
     * @param stateId - The ID of the state to get descendants for
     * @param visited - Set of visited states to prevent cycles
     * @returns Array of state IDs representing all descendants
     */
    getStateDescendants(stateId: string, visited?: Set<string>): string[];
    /**
     * Get all registered states.
     * @returns Array of state metadata for all registered states
     */
    getAllStates(): StateMetadata[];
    /**
     * Get metadata for a specific state.
     * @param stateId - The ID of the state to get metadata for
     * @returns The state metadata or undefined if not found
     */
    getStateMetadata(stateId: string): StateMetadata | undefined;
    /**
     * Track a context boundary between two states.
     * @param sourceStateId - The source state ID
     * @param targetStateId - The target state ID
     * @param boundaryType - The type of boundary
     * @param filePath - Optional file path associated with the boundary
     */
    trackContextBoundary(sourceStateId: string, targetStateId: string, boundaryType: 'import' | 'embed', filePath?: string): void;
    /**
     * Track a variable crossing between two states.
     * @param sourceStateId - The source state ID
     * @param targetStateId - The target state ID
     * @param variableName - The name of the variable
     * @param variableType - The type of variable
     * @param alias - Optional alias for the variable in the target state
     */
    trackVariableCrossing(sourceStateId: string, targetStateId: string, variableName: string, variableType: 'text' | 'data' | 'path' | 'command', alias?: string): void;
    /**
     * Get all context boundaries.
     * @returns Array of context boundaries
     */
    getContextBoundaries(): ContextBoundary[];
    /**
     * Get variable crossings for a state.
     * @param stateId - The ID of the state to get variable crossings for
     * @returns Array of variable crossings
     */
    getVariableCrossings(stateId: string): VariableCrossing[];
    /**
     * Get the context hierarchy for a state.
     * @param rootStateId - The ID of the root state
     * @returns Context hierarchy information
     */
    getContextHierarchy(rootStateId: string): ContextHierarchyInfo;
}
/**
 * Metadata for a state instance.
 */
interface StateMetadata {
    id: string;
    parentId?: string;
    source: 'new' | 'clone' | 'child' | 'merge' | 'implicit';
    filePath?: string;
    transformationEnabled: boolean;
    createdAt: number;
    lastModified?: number;
    childStates?: string[];
}
/**
 * Represents a relationship between states.
 */
interface StateRelationship {
    sourceId?: string;
    targetId: string;
    type: 'parent-child' | 'merge-source' | 'merge-target';
}
/**
 * Represents a context boundary between states.
 */
interface ContextBoundary {
    sourceStateId: string;
    targetStateId: string;
    boundaryType: 'import' | 'embed';
    timestamp: number;
    filePath?: string;
}
/**
 * Represents a variable crossing between states.
 */
interface VariableCrossing {
    sourceStateId: string;
    targetStateId: string;
    variableName: string;
    variableType: 'text' | 'data' | 'path' | 'command';
    timestamp: number;
    alias?: string;
}
/**
 * Information about the context hierarchy.
 */
interface ContextHierarchyInfo {
    states: StateMetadata[];
    boundaries: ContextBoundary[];
    variableCrossings: VariableCrossing[];
}

/**
 * Options for selective transformation
 */
interface TransformationOptions {
    variables?: boolean;
    directives?: boolean;
    commands?: boolean;
    imports?: boolean;
}
interface IStateService {
    setEventService(eventService: IStateEventService): void;
    setTrackingService(trackingService: IStateTrackingService): void;
    getStateId(): string | undefined;
    getTextVar(name: string): string | undefined;
    setTextVar(name: string, value: string): void;
    getAllTextVars(): Map<string, string>;
    getLocalTextVars(): Map<string, string>;
    getDataVar(name: string): unknown;
    setDataVar(name: string, value: unknown): void;
    getAllDataVars(): Map<string, unknown>;
    getLocalDataVars(): Map<string, unknown>;
    getPathVar(name: string): string | undefined;
    setPathVar(name: string, value: string): void;
    getAllPathVars(): Map<string, string>;
    getCommand(name: string): {
        command: string;
        options?: Record<string, unknown>;
    } | undefined;
    setCommand(name: string, command: string | {
        command: string;
        options?: Record<string, unknown>;
    }): void;
    getAllCommands(): Map<string, {
        command: string;
        options?: Record<string, unknown>;
    }>;
    getNodes(): MeldNode[];
    addNode(node: MeldNode): void;
    appendContent(content: string): void;
    getTransformedNodes(): MeldNode[];
    setTransformedNodes(nodes: MeldNode[]): void;
    transformNode(original: MeldNode, transformed: MeldNode): void;
    isTransformationEnabled(): boolean;
    enableTransformation(options?: TransformationOptions | boolean): void;
    shouldTransform(type: keyof TransformationOptions): boolean;
    getTransformationOptions(): TransformationOptions;
    getCommandOutput(command: string): string | undefined;
    hasTransformationSupport(): boolean;
    addImport(path: string): void;
    removeImport(path: string): void;
    hasImport(path: string): boolean;
    getImports(): Set<string>;
    getCurrentFilePath(): string | null;
    setCurrentFilePath(path: string): void;
    hasLocalChanges(): boolean;
    getLocalChanges(): string[];
    setImmutable(): void;
    readonly isImmutable: boolean;
    createChildState(): IStateService;
    mergeChildState(childState: IStateService): void;
    clone(): IStateService;
}

interface IValidationService {
    /**
     * Validate a directive node against its schema and constraints
     * @throws {MeldDirectiveError} If validation fails
     */
    validate(node: DirectiveNode): Promise<void>;
    /**
     * Register a validator function for a specific directive kind
     */
    registerValidator(kind: string, validator: (node: DirectiveNode) => Promise<void>): void;
    /**
     * Remove a validator for a specific directive kind
     */
    removeValidator(kind: string): void;
    /**
     * Check if a validator exists for a specific directive kind
     */
    hasValidator(kind: string): boolean;
    /**
     * Get all registered directive kinds that can be validated
     */
    getRegisteredDirectiveKinds(): string[];
}

interface IFileSystem {
    readFile(path: string): Promise<string>;
    writeFile(path: string, content: string): Promise<void>;
    exists(path: string): Promise<boolean>;
    stat(path: string): Promise<Stats>;
    readDir(path: string): Promise<string[]>;
    mkdir(path: string): Promise<void>;
    isDirectory(path: string): Promise<boolean>;
    isFile(path: string): Promise<boolean>;
    watch(path: string, options?: {
        recursive?: boolean;
    }): AsyncIterableIterator<{
        filename: string;
        eventType: string;
    }>;
    executeCommand(command: string, options?: {
        cwd?: string;
    }): Promise<{
        stdout: string;
        stderr: string;
    }>;
    isTestEnvironment?: boolean;
}

interface IFileSystemService {
    readFile(filePath: string): Promise<string>;
    writeFile(filePath: string, content: string): Promise<void>;
    exists(filePath: string): Promise<boolean>;
    stat(filePath: string): Promise<Stats>;
    isFile(filePath: string): Promise<boolean>;
    readDir(dirPath: string): Promise<string[]>;
    ensureDir(dirPath: string): Promise<void>;
    isDirectory(filePath: string): Promise<boolean>;
    watch(path: string, options?: {
        recursive?: boolean;
    }): AsyncIterableIterator<{
        filename: string;
        eventType: string;
    }>;
    getCwd(): string;
    dirname(filePath: string): string;
    executeCommand(command: string, options?: {
        cwd?: string;
    }): Promise<{
        stdout: string;
        stderr: string;
    }>;
    setFileSystem(fileSystem: IFileSystem): void;
    getFileSystem(): IFileSystem;
}

/**
 * Adapter to use Node's fs-extra as our IFileSystem implementation
 */
declare class NodeFileSystem implements IFileSystem {
    isTestEnvironment: boolean;
    readFile(path: string): Promise<string>;
    writeFile(path: string, content: string): Promise<void>;
    exists(path: string): Promise<boolean>;
    stat(path: string): Promise<Stats$1>;
    readDir(path: string): Promise<string[]>;
    mkdir(path: string): Promise<void>;
    isDirectory(path: string): Promise<boolean>;
    isFile(path: string): Promise<boolean>;
    watch(path: string, options?: {
        recursive?: boolean;
    }): AsyncIterableIterator<{
        filename: string;
        eventType: string;
    }>;
    executeCommand(command: string, options?: {
        cwd?: string;
    }): Promise<{
        stdout: string;
        stderr: string;
    }>;
}

type OutputFormat = 'markdown' | 'xml';
interface OutputOptions {
    /**
     * Whether to include state variables in the output
     * @default false
     */
    includeState?: boolean;
    /**
     * Whether to preserve original formatting (whitespace, newlines)
     * @default true
     */
    preserveFormatting?: boolean;
    /**
     * Custom format-specific options
     */
    formatOptions?: Record<string, unknown>;
}
interface IOutputService {
    /**
     * Check if this service can access transformed nodes
     * @returns true if transformed nodes can be accessed
     */
    canAccessTransformedNodes(): boolean;
    /**
     * Convert Meld nodes and state to the specified output format.
     * If state.isTransformationEnabled() is true and state.getTransformedNodes() is available,
     * the transformed nodes will be used instead of the input nodes.
     *
     * In non-transformation mode:
     * - Definition directives (@text, @data, @path, @import, @define) are omitted
     * - Execution directives (@run, @embed) show placeholders
     *
     * In transformation mode:
     * - All directives are replaced with their transformed results
     * - Plain text and code fences are preserved as-is
     *
     * @throws {MeldOutputError} If conversion fails
     */
    convert(nodes: MeldNode[], state: IStateService, format: OutputFormat, options?: OutputOptions): Promise<string>;
    /**
     * Register a custom format converter
     */
    registerFormat(format: string, converter: (nodes: MeldNode[], state: IStateService, options?: OutputOptions) => Promise<string>): void;
    /**
     * Check if a format is supported
     */
    supportsFormat(format: string): boolean;
    /**
     * Get a list of all supported formats
     */
    getSupportedFormats(): string[];
}

interface IParserService {
    /**
     * Parse Meld content into an AST using meld-ast.
     * @param content The Meld content to parse
     * @returns A promise that resolves to an array of MeldNodes representing the AST
     * @throws {MeldParseError} If the content cannot be parsed
     */
    parse(content: string): Promise<MeldNode[]>;
    /**
     * Parse Meld content and provide location information for each node.
     * This is useful for error reporting and source mapping.
     * @param content The Meld content to parse
     * @param filePath Optional file path for better error messages
     * @returns A promise that resolves to an array of MeldNodes with location information
     * @throws {MeldParseError} If the content cannot be parsed
     */
    parseWithLocations(content: string, filePath?: string): Promise<MeldNode[]>;
}

/**
 * @package
 * Lightweight tracking for variable resolution attempts
 *
 * Provides tracking capability to monitor variable resolution attempts
 * with minimal performance impact when disabled
 */
/**
 * Resolution attempt information
 */
interface ResolutionAttempt {
    variableName: string;
    context: string;
    timestamp: number;
    success: boolean;
    value?: any;
    source?: string;
    contextBoundary?: {
        type: 'parent-to-child' | 'child-to-parent';
        sourceId?: string;
        targetId?: string;
    };
}
/**
 * Variable resolution tracking configuration
 */
interface ResolutionTrackingConfig {
    enabled: boolean;
    samplingRate?: number;
    maxAttempts?: number;
    watchVariables?: string[];
}
/**
 * Tracks variable resolution attempts with minimal performance impact when disabled
 */
declare class VariableResolutionTracker {
    private config;
    private attempts;
    /**
     * Enables or disables tracking
     */
    configure(config: Partial<ResolutionTrackingConfig>): void;
    /**
     * Track a variable resolution attempt with minimal overhead when disabled
     */
    trackResolutionAttempt(variableName: string, context: string, success: boolean, value?: any, source?: string, contextBoundary?: {
        type: 'parent-to-child' | 'child-to-parent';
        sourceId?: string;
        targetId?: string;
    }): void;
    /**
     * Get all tracked resolution attempts
     */
    getAttempts(): ResolutionAttempt[];
    /**
     * Get resolution attempts for a specific variable
     */
    getAttemptsForVariable(variableName: string): ResolutionAttempt[];
    /**
     * Clear all tracked attempts
     */
    clearAttempts(): void;
    /**
     * Check if tracking is enabled
     */
    isEnabled(): boolean;
}

/**
 * Interface matching the StructuredPath expected from meld-spec
 */
interface StructuredPath$2 {
    raw: string;
    structured: {
        segments: string[];
        variables?: {
            special?: string[];
            path?: string[];
        };
        cwd?: boolean;
    };
    normalized?: string;
    isVariableReference?: boolean;
}
/**
 * Context for variable resolution, specifying what types of variables and operations are allowed
 */
interface ResolutionContext {
    /** Current file being processed, for error reporting */
    currentFilePath?: string;
    /** What types of variables are allowed in this context */
    allowedVariableTypes: {
        text: boolean;
        data: boolean;
        path: boolean;
        command: boolean;
    };
    /** Path validation rules when resolving paths */
    pathValidation?: {
        requireAbsolute: boolean;
        allowedRoots: string[];
    };
    /** Whether field access is allowed for data variables */
    allowDataFields?: boolean;
    /** Whether to throw errors on resolution failures (true) or attempt to recover (false) */
    strict?: boolean;
    /** The state service to use for variable resolution */
    state: IStateService;
}
/**
 * Service responsible for resolving variables, commands, and paths in different contexts
 */
interface IResolutionService {
    /**
     * Resolve text variables ({{var}}) in a string
     * Formerly used ${var} syntax, now unified with data variables to use {{var}}
     */
    resolveText(text: string, context: ResolutionContext): Promise<string>;
    /**
     * Resolve data variables and fields (#{data.field}) to their values
     */
    resolveData(ref: string, context: ResolutionContext): Promise<any>;
    /**
     * Resolve path variables ($path) to absolute paths.
     * This includes $HOMEPATH/$~ and $PROJECTPATH/$. resolution.
     */
    resolvePath(path: string, context: ResolutionContext): Promise<string>;
    /**
     * Resolve command references ($command(args)) to their results
     */
    resolveCommand(cmd: string, args: string[], context: ResolutionContext): Promise<string>;
    /**
     * Resolve content from a file path
     */
    resolveFile(path: string): Promise<string>;
    /**
     * Resolve raw content nodes, preserving formatting but skipping comments
     */
    resolveContent(nodes: MeldNode[], context: ResolutionContext): Promise<string>;
    /**
     * Resolve any value based on the provided context rules
     */
    resolveInContext(value: string | StructuredPath$2, context: ResolutionContext): Promise<string>;
    /**
     * Validate that resolution is allowed in the given context
     */
    validateResolution(value: string | StructuredPath$2, context: ResolutionContext): Promise<void>;
    /**
     * Extract a section from content by its heading
     * @param content The content to extract the section from
     * @param section The heading text to search for
     * @param fuzzy Optional fuzzy matching threshold (0-1, where 1 is exact match, defaults to 0.7)
     */
    extractSection(content: string, section: string, fuzzy?: number): Promise<string>;
    /**
     * Check for circular variable references
     */
    detectCircularReferences(value: string): Promise<void>;
    /**
     * Enable tracking of variable resolution attempts
     * @param config Configuration for the resolution tracker
     */
    enableResolutionTracking(config: Partial<ResolutionTrackingConfig>): void;
    /**
     * Get the resolution tracker for debugging
     * @returns The current resolution tracker or undefined if not enabled
     */
    getResolutionTracker(): VariableResolutionTracker | undefined;
}

declare class ParserService implements IParserService {
    private resolutionService?;
    constructor(resolutionService?: IResolutionService);
    setResolutionService(resolutionService: IResolutionService): void;
    private parseContent;
    parse(content: string, filePath?: string): Promise<MeldNode[]>;
    parseWithLocations(content: string, filePath?: string): Promise<MeldNode[]>;
    private isParseError;
    private validateCodeFences;
    /**
     * Transform a variable node to its resolved value
     * Used for preview and transformation mode to resolve values
     * @param node The node to transform
     * @param state The state service to use for lookup
     * @returns A text node with the resolved value if transformation is enabled
     */
    transformVariableNode(node: MeldNode, state: IStateService): Promise<MeldNode>;
}

/**
 * Command definition with optional configuration
 */
interface CommandDefinition {
    readonly command: string;
    readonly options?: Readonly<Record<string, unknown>>;
}

declare class StateService implements IStateService {
    private stateFactory;
    private currentState;
    private _isImmutable;
    private _transformationEnabled;
    private _transformationOptions;
    private eventService?;
    private trackingService?;
    constructor(parentState?: IStateService);
    setEventService(eventService: IStateEventService): void;
    private emitEvent;
    getTextVar(name: string): string | undefined;
    setTextVar(name: string, value: string): void;
    getAllTextVars(): Map<string, string>;
    getLocalTextVars(): Map<string, string>;
    getDataVar(name: string): unknown;
    setDataVar(name: string, value: unknown): void;
    getAllDataVars(): Map<string, unknown>;
    getLocalDataVars(): Map<string, unknown>;
    getPathVar(name: string): string | undefined;
    setPathVar(name: string, value: string): void;
    getAllPathVars(): Map<string, string>;
    getCommand(name: string): CommandDefinition | undefined;
    setCommand(name: string, command: string | CommandDefinition): void;
    getAllCommands(): Map<string, CommandDefinition>;
    getNodes(): MeldNode[];
    getTransformedNodes(): MeldNode[];
    setTransformedNodes(nodes: MeldNode[]): void;
    addNode(node: MeldNode): void;
    transformNode(original: MeldNode, transformed: MeldNode): void;
    isTransformationEnabled(): boolean;
    /**
     * Check if a specific transformation type is enabled
     * @param type The transformation type to check (variables, directives, commands, imports)
     * @returns Whether the specified transformation type is enabled
     */
    shouldTransform(type: keyof TransformationOptions): boolean;
    /**
     * Enable transformation with specific options
     * @param options Options for selective transformation, or true/false for all
     */
    enableTransformation(options?: TransformationOptions | boolean): void;
    /**
     * Get the current transformation options
     * @returns The current transformation options
     */
    getTransformationOptions(): TransformationOptions;
    appendContent(content: string): void;
    addImport(path: string): void;
    removeImport(path: string): void;
    hasImport(path: string): boolean;
    getImports(): Set<string>;
    getCurrentFilePath(): string | null;
    setCurrentFilePath(path: string): void;
    /**
     * In the immutable state model, any non-empty state is considered to have local changes.
     * This is a deliberate design choice - each state represents a complete snapshot,
     * so the entire state is considered "changed" from its creation.
     *
     * @returns Always returns true to indicate the state has changes
     */
    hasLocalChanges(): boolean;
    /**
     * Returns a list of changed elements in the state. In the immutable state model,
     * the entire state is considered changed from creation, so this always returns
     * ['state'] to indicate the complete state has changed.
     *
     * This is a deliberate design choice that aligns with the immutable state model
     * where each state is a complete snapshot.
     *
     * @returns Always returns ['state'] to indicate the entire state has changed
     */
    getLocalChanges(): string[];
    setImmutable(): void;
    get isImmutable(): boolean;
    createChildState(): IStateService;
    mergeChildState(childState: IStateService): void;
    clone(): IStateService;
    private checkMutable;
    /**
     * Deep clones a value, handling objects, arrays, Maps, Sets, and circular references.
     * @param value The value to clone
     * @param seen A WeakMap to track circular references
     * @returns A deep clone of the value
     */
    private deepCloneValue;
    private updateState;
    setTrackingService(trackingService: IStateTrackingService): void;
    getStateId(): string | undefined;
    getCommandOutput(command: string): string | undefined;
    hasTransformationSupport(): boolean;
}

/**
 * Handles resolution of variable references ({{var}})
 * Previously used ${var} for text and #{var} for data, now unified as {{var}}
 */
declare class VariableReferenceResolver {
    private readonly stateService;
    private readonly resolutionService?;
    private readonly parserService?;
    private readonly MAX_RESOLUTION_DEPTH;
    private readonly MAX_ITERATIONS;
    private resolutionTracker?;
    constructor(stateService: IStateService, resolutionService?: IResolutionService | undefined, parserService?: IParserService | undefined);
    /**
     * Set the resolution tracker for debugging
     * @internal
     */
    setResolutionTracker(tracker: VariableResolutionTracker): void;
    /**
     * Resolves all variable references in the given text
     * @param text Text containing variable references like {{varName}}
     * @param context Resolution context
     * @returns Resolved text with all variables replaced with their values
     */
    resolve(content: string, context: ResolutionContext): Promise<string>;
    /**
     * Resolves a list of nodes, handling variable references
     * @param nodes The nodes to resolve
     * @param context The resolution context
     * @returns The resolved content
     */
    resolveNodes(nodes: MeldNode[], context: ResolutionContext): Promise<string>;
    /**
     * Extract the actual value from a node, not just its string representation
     */
    private getNodeValue;
    /**
     * Convert a node to string representation
     * @deprecated Use getNodeValue instead for actual variable values
     */
    private nodeToString;
    /**
     * Resolve text with variable references
     */
    private resolveText;
    /**
     * Resolves a variable node (TextVar or DataVar)
     * @param node The variable node to resolve
     * @param context The resolution context
     * @param resolutionPath Path to detect circular references
     * @returns The resolved value
     */
    private resolveVarNode;
    /**
     * Normalizes a variable node to a common format regardless of node type
     */
    private normalizeVarNode;
    /**
     * Handles the resolution of standard text variables using a simpler approach
     * @param text Text containing variable references
     * @param context Resolution context
     * @returns Text with variables resolved
     */
    private resolveSimpleVariables;
    /**
     * Extract variable nodes from the AST
     * @param nodes AST nodes
     * @returns Array of variable reference nodes
     */
    private extractVariableNodesFromAst;
    /**
     * Extract references using AST - now properly handles async
     */
    private extractReferencesAst;
    /**
     * Extract references from AST nodes
     */
    private extractReferencesFromNodes;
    /**
     * Extract references from text content (helper method)
     */
    private extractReferencesFromText;
    /**
     * Extract references using regex pattern matching - now delegates to async method
     * This is kept for backward compatibility
     */
    private extractReferencesRegex;
    private getSafeTextVars;
    private getSafeDataVars;
    private resolveWithAst;
    /**
     * Check if text contains variable references
     */
    private hasVariableReferences;
    /**
     * Extract variable references from a string - now properly uses parser when available
     * @param text The text to search for references
     * @returns Array of unique variable names
     */
    extractReferences(text: string): string[];
    /**
     * Extract variable references from text (async version)
     * Note: This is needed for proper async handling with the parser.
     * @param text Text to extract references from
     * @returns Promise resolving to array of variable names
     */
    extractReferencesAsync(text: string): Promise<string[]>;
    /**
     * Debug helper to trace field access resolution
     * @param obj The object to access fields on
     * @param fields Array of field names to access
     * @param context Resolution context
     * @returns Detailed debug information about field access
     */
    private debugFieldAccess;
    /**
     * Gets a variable from the state service
     * @param name The variable name
     * @param context The resolution context
     * @returns The variable value
     */
    private getVariable;
    /**
     * Track a variable resolution attempt if tracker is available
     * @private
     */
    private trackResolutionAttempt;
    resolveFieldAccess(variableName: string, fieldPath: string, context: ResolutionContext): Promise<any>;
}

/**
 * Interface matching the StructuredPath expected from meld-spec
 */
interface StructuredPath$1 {
    raw: string;
    structured: {
        segments: string[];
        variables?: {
            special?: string[];
            path?: string[];
        };
        cwd?: boolean;
    };
    normalized?: string;
}
/**
 * Service responsible for resolving variables, commands, and paths in different contexts
 */
declare class ResolutionService implements IResolutionService {
    private stateService;
    private fileSystemService;
    private parserService;
    private pathService;
    private textResolver;
    private dataResolver;
    private pathResolver;
    private commandResolver;
    private contentResolver;
    private variableReferenceResolver;
    private resolutionTracker?;
    constructor(stateService: IStateService, fileSystemService: IFileSystemService, parserService: IParserService, pathService: IPathService);
    /**
     * Parse a string into AST nodes for resolution
     */
    private parseForResolution;
    /**
     * Resolve text variables in a string
     */
    resolveText(text: string, context: ResolutionContext): Promise<string>;
    /**
     * Resolve data variables and fields
     */
    resolveData(ref: string, context: ResolutionContext): Promise<any>;
    /**
     * Resolve path variables
     */
    resolvePath(path: string, context: ResolutionContext): Promise<string>;
    /**
     * Resolve command references
     */
    resolveCommand(cmd: string, args: string[], context: ResolutionContext): Promise<string>;
    /**
     * Resolve content from a file path
     */
    resolveFile(path: string): Promise<string>;
    /**
     * Resolve raw content nodes, preserving formatting but skipping comments
     */
    resolveContent(nodes: MeldNode[], context: ResolutionContext): Promise<string>;
    /**
     * Resolve any value based on the provided context rules
     */
    resolveInContext(value: string | StructuredPath$1, context: ResolutionContext): Promise<string>;
    /**
     * Resolve variables within a string value
     * @internal Used by resolveInContext
     */
    private resolveVariables;
    /**
     * Validate that resolution is allowed in the given context
     */
    validateResolution(value: string | StructuredPath$1, context: ResolutionContext): Promise<void>;
    /**
     * Check for circular variable references
     */
    detectCircularReferences(value: string): Promise<void>;
    /**
     * Extract a section from content by its heading
     * @param content The content to extract the section from
     * @param heading The heading text to search for
     * @param fuzzy Optional fuzzy matching threshold (0-1, where 1 is exact match, defaults to 0.7)
     *
     * NOTE: This implementation contains workarounds for limitations in the llmxml library.
     * See dev/LLMXML-IMPROVEMENTS.md for details about planned improvements to the library
     * instead of maintaining these workarounds.
     *
     * Current workarounds include:
     * 1. Manual section extraction when llmxml fails
     * 2. Error reporting with available headings
     * 3. Configurable fuzzy matching threshold
     */
    extractSection(content: string, heading: string, fuzzy?: number): Promise<string>;
    /**
     * Extract all headings from content for error reporting
     * This functionality should ideally be provided by the llmxml library
     * @private
     * @todo Move this functionality into llmxml
     */
    private extractHeadings;
    /**
     * Manual section extraction as a fallback when llmxml fails
     * This is a workaround for limitations in the llmxml library
     * @private
     * @todo Remove once llmxml reliability is improved
     */
    private manualSectionExtraction;
    private calculateSimilarity;
    private nodesToString;
    /**
     * Resolve a structured path to an absolute path
     * @private
     */
    private resolveStructuredPath;
    /**
     * Get the variable reference resolver
     */
    getVariableResolver(): VariableReferenceResolver;
    /**
     * Enable tracking of variable resolution attempts
     * @param config Configuration for the resolution tracker
     */
    enableResolutionTracking(config: Partial<ResolutionTrackingConfig>): void;
    /**
     * Get the resolution tracker for debugging
     * @returns The current resolution tracker or undefined if not enabled
     */
    getResolutionTracker(): VariableResolutionTracker | undefined;
}

/**
 * Service for validating and normalizing paths
 */
declare class PathService implements IPathService {
    private fs;
    private parser;
    private testMode;
    private homePath;
    private projectPath;
    private projectPathResolver;
    private projectPathResolved;
    constructor();
    /**
     * Initialize the path service with a file system service
     */
    initialize(fileSystem: IFileSystemService, parser?: IParserService): void;
    /**
     * Enable test mode for path operations
     */
    enableTestMode(): void;
    /**
     * Disable test mode for path operations
     */
    disableTestMode(): void;
    /**
     * Check if test mode is enabled
     */
    isTestMode(): boolean;
    /**
     * Set home path for testing
     */
    setHomePath(path: string): void;
    /**
     * Set project path for testing
     */
    setProjectPath(path: string): void;
    /**
     * Get the home path
     */
    getHomePath(): string;
    /**
     * Get the project path
     */
    getProjectPath(): string;
    /**
     * Resolve the project path using the ProjectPathResolver
     */
    resolveProjectPath(): Promise<string>;
    /**
     * Convert a string path to a structured path using the parser service
     * @private
     */
    private parsePathToStructured;
    /**
     * Validate a structured path according to Meld's path rules
     * @private
     */
    private validateStructuredPath;
    /**
     * Resolve a structured path to its absolute form
     * @private
     */
    private resolveStructuredPath;
    /**
     * Resolve a path to its absolute form
     */
    resolvePath(filePath: string | StructuredPath, baseDir?: string): string;
    /**
     * Synchronous version of validateStructuredPath
     * @private
     */
    private validateStructuredPathSync;
    /**
     * Validate a path against a set of constraints
     */
    validatePath(filePath: string | StructuredPath, options?: PathOptions): Promise<string>;
    /**
     * Normalize a path by resolving '..' and '.' segments
     */
    normalizePath(filePath: string): string;
    /**
     * Join multiple path segments together
     */
    join(...paths: string[]): string;
    /**
     * Get the directory name of a path
     */
    dirname(pathStr: string): string;
    /**
     * Get the base name of a path
     */
    basename(pathStr: string): string;
    /**
     * Validate a path string that follows Meld path syntax rules
     * This is a convenience method that passes the location information to validatePath
     */
    validateMeldPath(path: string, location?: Location): void;
    /**
     * Normalize a path string (replace backslashes with forward slashes)
     */
    normalizePathString(path: string): string;
}

declare enum ErrorSeverity {
    Fatal = "fatal",
    Recoverable = "recoverable",
    Warning = "warning"
}
interface MeldErrorOptions {
    cause?: Error;
    code?: string;
    filePath?: string;
    severity?: ErrorSeverity;
    context?: any;
}
interface SerializedMeldError {
    name: string;
    message: string;
    code?: string;
    filePath?: string;
    cause?: string;
    severity: ErrorSeverity;
    context?: any;
}
/**
 * Base class for all Meld errors
 */
declare class MeldError extends Error {
    readonly code?: string;
    readonly filePath?: string;
    private readonly errorCause?;
    readonly severity: ErrorSeverity;
    readonly context?: any;
    constructor(message: string, options?: MeldErrorOptions);
    /**
     * Custom serialization to avoid circular references and include only essential info
     */
    toJSON(): SerializedMeldError;
    /**
     * Check if this error can be treated as a warning in permissive mode
     */
    canBeWarning(): boolean;
    /**
     * Wrap an unknown error in a MeldError
     */
    static wrap(error: unknown, message?: string, severity?: ErrorSeverity): MeldError;
}

interface DirectiveLocation {
    line: number;
    column: number;
    filePath?: string;
}
interface MeldDirectiveErrorOptions {
    location?: DirectiveLocation;
    code?: string;
    cause?: Error;
    severity?: ErrorSeverity;
    context?: any;
}
declare class MeldDirectiveError extends MeldError {
    readonly directiveKind: string;
    readonly location?: DirectiveLocation;
    constructor(message: string, directiveKind: string, options?: MeldDirectiveErrorOptions);
}

/**
 * Error codes for directive failures
 */
declare enum DirectiveErrorCode {
    VALIDATION_FAILED = "VALIDATION_FAILED",
    RESOLUTION_FAILED = "RESOLUTION_FAILED",
    EXECUTION_FAILED = "EXECUTION_FAILED",
    HANDLER_NOT_FOUND = "HANDLER_NOT_FOUND",
    FILE_NOT_FOUND = "FILE_NOT_FOUND",
    CIRCULAR_REFERENCE = "CIRCULAR_REFERENCE",
    VARIABLE_NOT_FOUND = "VARIABLE_NOT_FOUND",
    STATE_ERROR = "STATE_ERROR",
    INVALID_CONTEXT = "INVALID_CONTEXT",
    SECTION_NOT_FOUND = "SECTION_NOT_FOUND"
}

/**
 * Map of directive error codes to severity levels
 */
declare const ValidationErrorSeverity: Record<DirectiveErrorCode, ErrorSeverity>;
declare class ValidationService implements IValidationService {
    private validators;
    constructor();
    /**
     * Validate a directive node against its schema and constraints
     * @throws {MeldDirectiveError} If validation fails
     */
    validate(node: DirectiveNode): Promise<void>;
    /**
     * Register a validator for a directive kind
     */
    registerValidator(kind: string, validator: (node: DirectiveNode) => Promise<void>): void;
    /**
     * Remove a validator for a directive kind
     */
    removeValidator(kind: string): void;
    /**
     * Check if a validator exists for a directive kind
     */
    hasValidator(kind: string): boolean;
    /**
     * Get all registered directive kinds
     */
    getRegisteredDirectiveKinds(): string[];
}

/**
 * Service for tracking and detecting circular imports in Meld files.
 */
interface ICircularityService {
    /**
     * Called at the start of an import operation.
     * @throws {MeldImportError} If a circular import is detected
     */
    beginImport(filePath: string): void;
    /**
     * Called after import is finished (success or failure).
     * Removes filePath from the import stack.
     */
    endImport(filePath: string): void;
    /**
     * Check if a file is currently in the import stack.
     */
    isInStack(filePath: string): boolean;
    /**
     * Get the current import stack.
     */
    getImportStack(): string[];
    /**
     * Clear the import stack.
     */
    reset(): void;
}

declare class CircularityService implements ICircularityService {
    private importStack;
    beginImport(filePath: string): void;
    endImport(filePath: string): void;
    isInStack(filePath: string): boolean;
    getImportStack(): string[];
    reset(): void;
}

/**
 * Result of directive execution
 */
interface DirectiveResult {
    /** The updated state after directive execution */
    state: IStateService;
    /** Optional replacement node for transformation */
    replacement?: MeldNode;
}

interface ILogger {
    debug: (message: string, ...args: any[]) => void;
    info: (message: string, ...args: any[]) => void;
    warn: (message: string, ...args: any[]) => void;
    error: (message: string, ...args: any[]) => void;
}

declare class MeldLLMXMLError extends Error {
    readonly code: string;
    readonly details?: any | undefined;
    constructor(message: string, code: string, details?: any | undefined);
}
/**
 * Service responsible for handling directives
 */
declare class DirectiveService implements IDirectiveService {
    private validationService?;
    private stateService?;
    private pathService?;
    private fileSystemService?;
    private parserService?;
    private interpreterService?;
    private circularityService?;
    private resolutionService?;
    private initialized;
    private logger;
    private handlers;
    constructor(logger?: ILogger);
    initialize(validationService: IValidationService, stateService: IStateService, pathService: IPathService, fileSystemService: IFileSystemService, parserService: IParserService, interpreterService: IInterpreterService, circularityService: ICircularityService, resolutionService: IResolutionService): void;
    /**
     * Register all default directive handlers
     */
    registerDefaultHandlers(): void;
    /**
     * Register a new directive handler
     */
    registerHandler(handler: IDirectiveHandler): void;
    /**
     * Handle a directive node
     */
    handleDirective(node: DirectiveNode, context: DirectiveContext): Promise<IStateService>;
    /**
     * Process multiple directives in sequence
     */
    processDirectives(nodes: DirectiveNode[], parentContext?: DirectiveContext): Promise<IStateService>;
    /**
     * Create execution context for a directive
     */
    private createContext;
    /**
     * Update the interpreter service reference
     */
    updateInterpreterService(interpreterService: IInterpreterService): void;
    /**
     * Check if a handler exists for a directive kind
     */
    hasHandler(kind: string): boolean;
    /**
     * Validate a directive node
     */
    validateDirective(node: DirectiveNode): Promise<void>;
    /**
     * Create a child context for nested directives
     */
    createChildContext(parentContext: DirectiveContext, filePath: string): DirectiveContext;
    supportsDirective(kind: string): boolean;
    getSupportedDirectives(): string[];
    private ensureInitialized;
    private handleTextDirective;
    private handleDataDirective;
    private handleImportDirective;
    private extractSection;
    private calculateSimilarity;
    private handleEmbedDirective;
    /**
     * Process a directive node, validating and executing it
     * Values in the directive will already be interpolated by meld-ast
     * @returns The updated state after directive execution
     * @throws {MeldDirectiveError} If directive processing fails
     */
    processDirective(node: DirectiveNode, context: DirectiveContext): Promise<IStateService>;
}

type FormatConverter = (nodes: MeldNode[], state: IStateService, options?: OutputOptions) => Promise<string>;
declare class OutputService implements IOutputService {
    private formatters;
    private state;
    private resolutionService;
    canAccessTransformedNodes(): boolean;
    constructor();
    initialize(state: IStateService, resolutionService?: IResolutionService): void;
    convert(nodes: MeldNode[], state: IStateService, format: OutputFormat, options?: OutputOptions): Promise<string>;
    registerFormat(format: string, converter: FormatConverter): void;
    supportsFormat(format: string): boolean;
    getSupportedFormats(): string[];
    /**
     * Helper method to safely extract string content from various node types
     * ensuring proper type safety
     */
    private getTextContentFromNode;
    private convertToMarkdown;
    private convertToXML;
    private formatStateVariables;
    private nodeToMarkdown;
    private nodeToXML;
    private codeFenceToMarkdown;
    private codeFenceToXML;
    private directiveToMarkdown;
    private directiveToXML;
}

/**
 * @package
 * Interface for state visualization service.
 *
 * @remarks
 * Provides visualization capabilities for state hierarchies,
 * transitions, relationships, and metrics. Supports multiple
 * output formats for different use cases (e.g., debug, analysis).
 */

/**
 * Supported visualization formats
 */
type VisualizationFormat = 'mermaid' | 'dot' | 'json';
/**
 * Node styling options for visualizations
 */
interface NodeStyle {
    shape?: 'box' | 'circle' | 'diamond';
    color?: string;
    label?: string;
    tooltip?: string;
}
/**
 * Edge styling options for visualizations
 */
interface EdgeStyle {
    style?: 'solid' | 'dashed' | 'dotted';
    color?: string;
    label?: string;
    tooltip?: string;
}
/**
 * Configuration for generating visualizations
 */
interface VisualizationConfig {
    format: VisualizationFormat;
    includeMetadata?: boolean;
    includeTimestamps?: boolean;
    styleNodes?: (metadata: StateMetadata) => NodeStyle;
    styleEdges?: (relationship: StateRelationship) => EdgeStyle;
    timeRange?: {
        start?: number;
        end?: number;
    };
}
/**
 * Configuration for context visualizations
 */
interface ContextVisualizationConfig extends VisualizationConfig {
    includeVars?: boolean;
    filterToRelevantVars?: boolean;
    highlightBoundaries?: boolean;
    includeBoundaryTypes?: boolean;
    includeFilePaths?: boolean;
}
/**
 * Basic metrics about the state system
 */
interface StateMetrics {
    totalStates: number;
    statesByType: Record<string, number>;
    averageTransformationsPerState: number;
    maxTransformationChainLength: number;
    averageChildrenPerState: number;
    maxTreeDepth: number;
    operationFrequency: Record<string, number>;
}
/**
 * Core state visualization service interface
 */
interface IStateVisualizationService {
    /**
     * Generate a hierarchical view of state relationships
     * @param rootStateId - The root state to start visualization from
     * @param config - Visualization configuration
     * @returns Visualization in the specified format
     */
    generateHierarchyView(rootStateId: string, config: VisualizationConfig): string;
    /**
     * Generate a transition diagram showing state transformations
     * @param stateId - The state to show transitions for
     * @param config - Visualization configuration
     * @returns Visualization in the specified format
     */
    generateTransitionDiagram(stateId: string, config: VisualizationConfig): string;
    /**
     * Generate a relationship graph showing state connections
     * @param stateIds - The states to include in the graph
     * @param config - Visualization configuration
     * @returns Visualization in the specified format
     */
    generateRelationshipGraph(stateIds: string[], config: VisualizationConfig): string;
    /**
     * Generate a timeline view of state operations
     * @param stateIds - The states to include in the timeline
     * @param config - Visualization configuration
     * @returns Visualization in the specified format
     */
    generateTimeline(stateIds: string[], config: VisualizationConfig): string;
    /**
     * Calculate and return metrics about the state system
     * @param timeRange - Optional time range to limit metrics to
     * @returns Object containing various metrics
     */
    getMetrics(timeRange?: {
        start: number;
        end: number;
    }): StateMetrics;
    /**
     * Export the complete state graph in the specified format
     * @param config - Visualization configuration
     * @returns Complete state graph visualization
     */
    exportStateGraph(config: VisualizationConfig): string;
    /**
     * Generate a context hierarchy visualization showing context boundaries
     * @param rootStateId - The root state to start visualization from
     * @param config - Context visualization configuration
     * @returns Context hierarchy visualization in the specified format
     */
    visualizeContextHierarchy(rootStateId: string, config: ContextVisualizationConfig): string;
    /**
     * Generate a variable propagation visualization showing how variables move across contexts
     * @param variableName - The name of the variable to track propagation for
     * @param rootStateId - Optional root state to limit visualization scope
     * @param config - Context visualization configuration
     * @returns Variable propagation visualization in the specified format
     */
    visualizeVariablePropagation(variableName: string, rootStateId?: string, config?: ContextVisualizationConfig): string;
    /**
     * Generate a combined context and variable flow visualization
     * @param rootStateId - The root state to start visualization from
     * @param config - Context visualization configuration
     * @returns Combined context and variable flow visualization
     */
    visualizeContextsAndVariableFlow(rootStateId: string, config: ContextVisualizationConfig): string;
    /**
     * Generate a resolution path timeline visualization for a specific variable
     * @param variableName - The name of the variable to track resolution for
     * @param rootStateId - Optional root state to limit visualization scope
     * @param config - Context visualization configuration
     * @returns Resolution path timeline visualization
     */
    visualizeResolutionPathTimeline(variableName: string, rootStateId?: string, config?: ContextVisualizationConfig): string;
}

/**
 * @package
 * Interface for state history tracking service.
 *
 * @remarks
 * Provides chronological tracking of state operations, transformations,
 * and relationships. Supports debugging and analysis of state transitions
 * through history querying capabilities.
 */

/**
 * Represents a recorded state operation
 */
interface StateOperation {
    type: StateEventType;
    stateId: string;
    source: string;
    timestamp: number;
    parentId?: string;
    metadata?: Partial<StateMetadata>;
    details?: {
        operation?: string;
        key?: string;
        value?: unknown;
    };
}
/**
 * Represents a state transformation record
 */
interface StateTransformation {
    stateId: string;
    timestamp: number;
    operation: string;
    source: string;
    before?: unknown;
    after?: unknown;
}
/**
 * Filter criteria for querying history
 */
interface HistoryFilter {
    stateIds?: string[];
    types?: StateEventType[];
    timeRange?: {
        start?: number;
        end?: number;
    };
    source?: string;
}
/**
 * Core state history service interface
 */
interface IStateHistoryService {
    /**
     * Record a state operation in history
     * @param operation - The operation details to record
     */
    recordOperation(operation: StateOperation): void;
    /**
     * Get the complete operation history for a state
     * @param stateId - The ID of the state to get history for
     * @returns Array of operations in chronological order
     */
    getOperationHistory(stateId: string): StateOperation[];
    /**
     * Get the transformation chain for a state
     * @param stateId - The ID of the state to get transformations for
     * @returns Array of transformations in chronological order
     */
    getTransformationChain(stateId: string): StateTransformation[];
    /**
     * Query history using filter criteria
     * @param filter - The filter criteria to apply
     * @returns Array of matching operations
     */
    queryHistory(filter: HistoryFilter): StateOperation[];
    /**
     * Get related operations that occurred within a time window
     * @param operation - The reference operation
     * @param windowMs - Time window in milliseconds
     * @returns Array of related operations
     */
    getRelatedOperations(operation: StateOperation, windowMs: number): StateOperation[];
    /**
     * Clear history older than specified timestamp
     * @param beforeTimestamp - Clear history before this timestamp
     */
    clearHistoryBefore(beforeTimestamp: number): void;
    /**
     * Get the complete state history including operations and transformations
     * @param stateId - The ID of the state to get history for
     * @returns Combined history of operations and transformations or undefined if state not found
     */
    getStateHistory(stateId: string): Promise<{
        operations: StateOperation[];
        transformations: StateTransformation[];
    } | undefined>;
}

/**
 * @package
 * Interface for state debugging service.
 *
 * @remarks
 * Provides debugging capabilities by integrating state tracking,
 * history, and visualization services. Supports automated diagnostics
 * for failing tests and CLI-based state analysis.
 */

/**
 * Configuration for state capture points
 */
interface StateCaptureConfig {
    capturePoints: Array<'pre-transform' | 'post-transform' | 'pre-merge' | 'error'>;
    includeFields: Array<'nodes' | 'transformedNodes' | 'variables'>;
    format: 'full' | 'summary';
}
/**
 * Diagnostic result from state analysis
 */
interface StateDiagnostic {
    stateId: string;
    timestamp: number;
    type: 'error' | 'warning' | 'info';
    message: string;
    context?: {
        operation?: StateOperation;
        metadata?: StateMetadata;
        location?: string;
    };
}
/**
 * Debug session configuration
 */
interface DebugSessionConfig {
    captureConfig: StateCaptureConfig;
    visualization?: VisualizationConfig;
    traceOperations?: boolean;
    collectMetrics?: boolean;
}
/**
 * Debug session result
 */
interface DebugSessionResult {
    sessionId: string;
    startTime: number;
    endTime: number;
    diagnostics: StateDiagnostic[];
    snapshots: Map<string, any>;
    metrics?: Record<string, number>;
    visualization?: string;
}
/**
 * Core state debugging service interface
 */
interface IStateDebuggerService {
    /**
     * Start a new debug session
     * @param config - Debug session configuration
     * @returns Session ID
     */
    startSession(config: DebugSessionConfig): string;
    /**
     * End the current debug session and get results
     * @param sessionId - The session to end
     * @returns Debug session results
     */
    endSession(sessionId: string): Promise<DebugSessionResult>;
    /**
     * Analyze a state for potential issues
     * @param stateId - The state to analyze
     * @returns Array of diagnostics
     */
    analyzeState(stateId: string): Promise<StateDiagnostic[]>;
    /**
     * Trace a state operation and capture debug info
     * @param stateId - The state being operated on
     * @param operation - Function performing the operation
     * @returns Operation result and debug info
     */
    traceOperation<T>(stateId: string, operation: () => Promise<T>): Promise<{
        result: T;
        diagnostics: StateDiagnostic[];
    }>;
    /**
     * Get a snapshot of state at a specific point
     * @param stateId - The state to snapshot
     * @param format - Snapshot format ('full' | 'summary')
     * @returns State snapshot
     */
    getStateSnapshot(stateId: string, format: 'full' | 'summary'): Promise<any>;
    /**
     * Generate a CLI-friendly debug report
     * @param sessionId - Debug session to report on
     * @returns Formatted debug report
     */
    generateDebugReport(sessionId: string): Promise<string>;
    /**
     * Register a custom diagnostic analyzer
     * @param analyzer - Function to analyze state and return diagnostics
     */
    registerAnalyzer(analyzer: (stateId: string) => Promise<StateDiagnostic[]>): void;
    /**
     * Clear all debug data for a session
     * @param sessionId - Session to clear
     */
    clearSession(sessionId: string): void;
}

/**
 * @package
 * Implementation of state debugging service.
 */

/**
 * Implements debugging capabilities by integrating state tracking,
 * history, and visualization services.
 */
declare class StateDebuggerService implements IStateDebuggerService {
    private visualizationService;
    private historyService;
    private trackingService;
    private sessions;
    private analyzers;
    constructor(visualizationService: IStateVisualizationService, historyService: IStateHistoryService, trackingService: IStateTrackingService);
    startSession(config: DebugSessionConfig): string;
    endSession(sessionId: string): Promise<DebugSessionResult>;
    analyzeState(stateId: string): Promise<StateDiagnostic[]>;
    traceOperation<T>(stateId: string, operation: () => Promise<T>): Promise<{
        result: T;
        diagnostics: StateDiagnostic[];
    }>;
    getStateSnapshot(stateId: string, format: 'full' | 'summary'): Promise<any>;
    generateDebugReport(sessionId: string): Promise<string>;
    registerAnalyzer(analyzer: (stateId: string) => Promise<StateDiagnostic[]>): void;
    clearSession(sessionId: string): void;
    private analyzeStateChanges;
}

/**
 * Represents a position in a file
 */
interface Position {
    /** The line number (1-based) */
    line: number;
    /** The column number (1-based) */
    column: number;
}
/**
 * Represents a location in a file
 */
interface Location {
    /** Start position */
    start: Position;
    /** End position */
    end: Position;
    /** Optional file path */
    filePath?: string;
}
/**
 * Represents a range in a file with start and end positions
 * @deprecated Use Location instead as it already includes start/end positions
 */
interface Range {
    start: Position;
    end: Position;
    filePath?: string;
}
interface Services {
    parser: ParserService;
    interpreter: InterpreterService;
    state: StateService;
    resolution: ResolutionService;
    path: PathService;
    validation: ValidationService;
    circularity: CircularityService;
    directive: DirectiveService;
    output: OutputService;
    debug?: StateDebuggerService;
}
interface ProcessOptions {
    /**
     * Controls whether directives should be transformed
     * Can be a boolean for all-or-nothing transformation, or an object with selective options
     */
    transformation?: boolean | TransformationOptions;
    /** Controls output format */
    format?: OutputFormat;
    /** Enables/disables debugging */
    debug?: boolean;
    /** Optional custom filesystem */
    fs?: NodeFileSystem;
    /** Optional service overrides */
    services?: Partial<Services>;
}

interface StructuredPath {
    raw: string;
    structured: {
        segments: string[];
        variables?: {
            special?: string[];
            path?: string[];
        };
        cwd?: boolean;
    };
    normalized?: string;
}
/**
 * Options for path validation and operations
 */
interface PathOptions {
    /**
     * Base directory to resolve relative paths against.
     * For paths without slashes, this is used as the base directory.
     * For paths with $. or $~, this is ignored.
     */
    baseDir?: string;
    /**
     * Whether to allow paths outside the base directory.
     * If false, paths must be within the base directory.
     * Default is true.
     */
    allowOutsideBaseDir?: boolean;
    /**
     * Whether the path must exist on disk.
     * @default true
     */
    mustExist?: boolean;
    /**
     * Whether the path must be a file (not a directory).
     * Only checked if mustExist is true.
     * @default false
     */
    mustBeFile?: boolean;
    /**
     * Whether the path must be a directory (not a file).
     * Only checked if mustExist is true.
     * @default false
     */
    mustBeDirectory?: boolean;
    location?: Location;
}
/**
 * Service for validating and normalizing paths according to Meld's strict rules:
 *
 * 1. Simple paths (no slashes):
 *    - Allowed only when path contains no slashes
 *    - Example: file.mld
 *
 * 2. Paths with slashes:
 *    - Must start with $. (alias for $PROJECTPATH) or $~ (alias for $HOMEPATH)
 *    - Example: $./path/to/file.mld or $~/path/to/file.mld
 *
 * 3. Forbidden:
 *    - Parent directory references (..)
 *    - Current directory references (.)
 *    - Raw absolute paths
 *    - Paths with slashes not using $. or $~
 */
interface IPathService {
    /**
     * Initialize the path service with a file system service.
     * Optionally initialize with a parser service for AST-based path handling.
     * Must be called before using any other methods.
     */
    initialize(fileSystem: IFileSystemService, parser?: IParserService): void;
    /**
     * Enable test mode for path operations.
     * In test mode, certain validations may be relaxed or mocked.
     */
    enableTestMode(): void;
    /**
     * Disable test mode for path operations.
     */
    disableTestMode(): void;
    /**
     * Check if test mode is enabled.
     */
    isTestMode(): boolean;
    /**
     * Set the home path for testing.
     */
    setHomePath(path: string): void;
    /**
     * Set the project path for testing.
     */
    setProjectPath(path: string): void;
    /**
     * Get the home path.
     */
    getHomePath(): string;
    /**
     * Get the project path.
     */
    getProjectPath(): string;
    /**
     * Resolve the project path using auto-detection or configuration.
     * This method will:
     * 1. Look for meld.json and use its projectRoot setting if valid
     * 2. Auto-detect using common project markers
     * 3. Fall back to current directory
     */
    resolveProjectPath(): Promise<string>;
    /**
     * Resolve a path to its absolute form according to Meld's path rules:
     * - Simple paths are resolved relative to baseDir or cwd
     * - $. paths are resolved relative to project root
     * - $~ paths are resolved relative to home directory
     *
     * @param filePath The path to resolve (string or StructuredPath)
     * @param baseDir Optional base directory for simple paths
     * @returns The resolved absolute path
     * @throws PathValidationError if path format is invalid
     */
    resolvePath(filePath: string | StructuredPath, baseDir?: string): string;
    /**
     * Validate a path according to Meld's rules and the specified options.
     *
     * @param filePath The path to validate (string or StructuredPath)
     * @param options Options for validation
     * @throws PathValidationError if validation fails
     */
    validatePath(filePath: string | StructuredPath, options?: PathOptions): Promise<string>;
    /**
     * Join multiple path segments together.
     * Note: This is a low-level utility and does not enforce Meld path rules.
     *
     * @param paths The path segments to join
     * @returns The joined path
     */
    join(...paths: string[]): string;
    /**
     * Get the directory name of a path.
     * Note: This is a low-level utility and does not enforce Meld path rules.
     *
     * @param filePath The path to get the directory from
     * @returns The directory name
     */
    dirname(filePath: string): string;
    /**
     * Get the base name of a path.
     * Note: This is a low-level utility and does not enforce Meld path rules.
     *
     * @param filePath The path to get the base name from
     * @returns The base name
     */
    basename(filePath: string): string;
}

/**
 * Context for directive execution
 */
interface DirectiveContext {
    /** Current file being processed */
    currentFilePath?: string;
    /** Parent state for nested contexts */
    parentState?: IStateService;
    /** Current state for this directive */
    state: IStateService;
    /** Working directory for command execution */
    workingDirectory?: string;
}
/**
 * Interface for directive handlers
 */
interface IDirectiveHandler {
    /** The directive kind this handler processes */
    readonly kind: string;
    /**
     * Execute the directive
     * @returns The updated state after directive execution, or a DirectiveResult containing both state and optional replacement node
     */
    execute(node: DirectiveNode, context: DirectiveContext): Promise<DirectiveResult | IStateService>;
}
/**
 * Service responsible for handling directives
 */
interface IDirectiveService {
    /**
     * Initialize the DirectiveService with required dependencies
     */
    initialize(validationService: IValidationService, stateService: IStateService, pathService: IPathService, fileSystemService: IFileSystemService, parserService: IParserService, interpreterService: IInterpreterService, circularityService: ICircularityService, resolutionService: IResolutionService): void;
    /**
     * Update the interpreter service reference
     * This is needed to handle circular dependencies in initialization
     */
    updateInterpreterService(interpreterService: IInterpreterService): void;
    /**
     * Handle a directive node
     * @returns The updated state after directive execution
     */
    handleDirective(node: DirectiveNode, context: DirectiveContext): Promise<IStateService>;
    /**
     * Register a new directive handler
     */
    registerHandler(handler: IDirectiveHandler): void;
    /**
     * Check if a handler exists for a directive kind
     */
    hasHandler(kind: string): boolean;
    /**
     * Validate a directive node
     */
    validateDirective(node: DirectiveNode): Promise<void>;
    /**
     * Create a child context for nested directives
     */
    createChildContext(parentContext: DirectiveContext, filePath: string): DirectiveContext;
    /**
     * Process a directive node, validating and executing it
     * Values in the directive will already be interpolated by meld-ast
     * @returns The updated state after directive execution
     * @throws {MeldDirectiveError} If directive processing fails
     */
    processDirective(node: DirectiveNode, parentContext?: DirectiveContext): Promise<IStateService>;
    /**
     * Process multiple directive nodes in sequence
     * @returns The final state after processing all directives
     * @throws {MeldDirectiveError} If any directive processing fails
     */
    processDirectives(nodes: DirectiveNode[], parentContext?: DirectiveContext): Promise<IStateService>;
    /**
     * Check if a directive kind is supported
     */
    supportsDirective(kind: string): boolean;
    /**
     * Get a list of all supported directive kinds
     */
    getSupportedDirectives(): string[];
}

interface ErrorHandler {
    (error: MeldError): void;
}
interface InterpreterOptions {
    /**
     * Initial state to use for interpretation
     * If not provided, a new state will be created
     */
    initialState?: IStateService;
    /**
     * Current file path for error reporting
     */
    filePath?: string;
    /**
     * Whether to merge the final state back to the parent
     * @default true
     */
    mergeState?: boolean;
    /**
     * List of variables to import
     * If undefined, all variables are imported
     * If empty array, no variables are imported
     */
    importFilter?: string[];
    /**
     * Whether to run in strict mode
     * In strict mode, all errors throw
     * In permissive mode, recoverable errors become warnings
     * @default true
     */
    strict?: boolean;
    /**
     * Custom error handler
     * If provided, will be called for all errors
     * In permissive mode, recoverable errors will be passed to this handler instead of throwing
     */
    errorHandler?: ErrorHandler;
}
interface IInterpreterService {
    /**
     * Check if this service can handle transformations
     * @returns true if transformations are supported
     */
    canHandleTransformations(): boolean;
    /**
     * Initialize the InterpreterService with required dependencies
     */
    initialize(directiveService: IDirectiveService, stateService: IStateService): void;
    /**
     * Interpret a sequence of Meld nodes
     * @returns The final state after interpretation
     * @throws {MeldInterpreterError} If interpretation fails
     */
    interpret(nodes: MeldNode[], options?: InterpreterOptions): Promise<IStateService>;
    /**
     * Interpret a single Meld node
     * @returns The state after interpretation
     * @throws {MeldInterpreterError} If interpretation fails
     */
    interpretNode(node: MeldNode, state: IStateService, options?: InterpreterOptions): Promise<IStateService>;
    /**
     * Create a new interpreter context with a child state
     * Useful for nested interpretation (import/embed)
     */
    createChildContext(parentState: IStateService, filePath?: string, options?: InterpreterOptions): Promise<IStateService>;
}

declare class InterpreterService implements IInterpreterService {
    private directiveService?;
    private stateService?;
    private initialized;
    private stateVariableCopier;
    canHandleTransformations(): boolean;
    initialize(directiveService: IDirectiveService, stateService: IStateService): void;
    /**
     * Handle errors based on severity and options
     * In strict mode, all errors throw
     * In permissive mode, recoverable errors become warnings
     */
    private handleError;
    interpret(nodes: MeldNode[], options?: InterpreterOptions): Promise<IStateService>;
    interpretNode(node: MeldNode, state: IStateService, options?: InterpreterOptions): Promise<IStateService>;
    createChildContext(parentState: IStateService, filePath?: string, options?: InterpreterOptions): Promise<IStateService>;
    private ensureInitialized;
}

interface IPathOperationsService {
    /**
     * Join all arguments together and normalize the resulting path
     */
    join(...paths: string[]): string;
    /**
     * Resolves a sequence of paths or path segments into an absolute path
     */
    resolve(...paths: string[]): string;
    /**
     * Returns the directory name of a path
     */
    dirname(filePath: string): string;
    /**
     * Returns the last portion of a path
     */
    basename(filePath: string): string;
    /**
     * Normalize a string path, reducing '..' and '.' parts
     */
    normalize(filePath: string): string;
    /**
     * Determines if path is an absolute path
     */
    isAbsolute(filePath: string): boolean;
    /**
     * Returns the relative path from 'from' to 'to'
     */
    relative(from: string, to: string): string;
    /**
     * Returns an object whose properties represent significant elements of the path
     */
    parse(filePath: string): path.ParsedPath;
}

declare class FileSystemService implements IFileSystemService {
    private readonly pathOps;
    private fs;
    private pathService?;
    constructor(pathOps: IPathOperationsService, fileSystem?: IFileSystem);
    setFileSystem(fileSystem: IFileSystem): void;
    getFileSystem(): IFileSystem;
    setPathService(pathService: IPathService): void;
    private resolvePath;
    readFile(filePath: string): Promise<string>;
    writeFile(filePath: string, content: string): Promise<void>;
    exists(filePath: string): Promise<boolean>;
    stat(filePath: string): Promise<fsExtra.Stats>;
    readDir(dirPath: string): Promise<string[]>;
    ensureDir(dirPath: string): Promise<void>;
    isDirectory(filePath: string): Promise<boolean>;
    isFile(filePath: string): Promise<boolean>;
    getCwd(): string;
    dirname(filePath: string): string;
    watch(path: string, options?: {
        recursive?: boolean;
    }): AsyncIterableIterator<{
        filename: string;
        eventType: string;
    }>;
    executeCommand(command: string, options?: {
        cwd?: string;
    }): Promise<{
        stdout: string;
        stderr: string;
    }>;
}

declare class PathOperationsService implements IPathOperationsService {
    join(...paths: string[]): string;
    resolve(...paths: string[]): string;
    dirname(filePath: string): string;
    basename(filePath: string): string;
    normalize(filePath: string): string;
    isAbsolute(filePath: string): boolean;
    relative(from: string, to: string): string;
    parse(filePath: string): path.ParsedPath;
}

interface InterpreterLocation {
    line: number;
    column: number;
    filePath?: string;
}
interface SerializedInterpreterError {
    name: string;
    message: string;
    nodeType: string;
    location?: InterpreterLocation;
    filePath?: string;
    cause?: string;
    fullCauseMessage?: string;
    severity: ErrorSeverity;
    code?: string;
    context?: {
        filePath?: string;
        nodeType?: string;
        nodeCount?: number;
    };
}
interface InterpreterErrorContext {
    filePath?: string;
    nodeType?: string;
    location?: InterpreterLocation;
    parentFilePath?: string;
    childFilePath?: string;
    state?: {
        filePath?: string;
        nodeCount?: number;
    };
}
interface MeldInterpreterErrorOptions {
    cause?: Error;
    context?: InterpreterErrorContext;
    severity?: ErrorSeverity;
    code?: string;
}
/**
 * Error thrown during interpretation of Meld content
 */
declare class MeldInterpreterError extends MeldError {
    readonly nodeType: string;
    readonly location?: InterpreterLocation;
    readonly context?: InterpreterErrorContext;
    constructor(message: string, nodeType: string, location?: InterpreterLocation, options?: MeldInterpreterErrorOptions);
    /**
     * Access to the cause property of this error
     */
    get cause(): Error | undefined;
    /**
     * Custom serialization to avoid circular references and include only essential info
     */
    toJSON(): SerializedInterpreterError;
    /**
     * Get the full cause message chain
     */
    private getFullCauseMessage;
}

interface SerializedParseError {
    name: string;
    message: string;
    location?: Location;
    filePath?: string;
    cause?: string;
    severity: ErrorSeverity;
    context?: any;
}
interface MeldParseErrorOptions {
    cause?: Error;
    severity?: ErrorSeverity;
    context?: any;
    filePath?: string;
}
/**
 * Error thrown when parsing Meld content fails
 */
declare class MeldParseError extends MeldError {
    /**
     * Location information for where the error occurred
     */
    readonly location?: Location;
    constructor(message: string, position?: Position | Location, options?: MeldParseErrorOptions);
    /**
     * Custom serialization to avoid circular references and include only essential info
     */
    toJSON(): SerializedParseError;
}

/**
 * Simple in-memory file system implementation for use with the runMeld API.
 * This allows processing meld content without touching the real file system.
 */
declare class MemoryFileSystem implements IFileSystem {
    private files;
    private dirs;
    isTestEnvironment: boolean;
    constructor();
    /**
     * Read a file from memory
     */
    readFile(filePath: string): Promise<string>;
    /**
     * Write a file to memory
     */
    writeFile(filePath: string, content: string): Promise<void>;
    /**
     * Check if a file exists in memory
     */
    exists(filePath: string): Promise<boolean>;
    /**
     * Create a directory in memory
     */
    mkdir(dirPath: string, options?: {
        recursive?: boolean;
    }): Promise<void>;
    /**
     * Check if a path is a file
     */
    isFile(filePath: string): Promise<boolean>;
    /**
     * Check if a path is a directory
     */
    isDirectory(filePath: string): Promise<boolean>;
    /**
     * List directory contents
     */
    readDir(dirPath: string): Promise<string[]>;
    /**
     * Get file stats
     */
    stat(filePath: string): Promise<Stats>;
    /**
     * Watch a file or directory for changes
     * This is a minimal implementation that doesn't actually watch anything
     * since it's for the runMeld API which doesn't need watching
     */
    watch(path: string, options?: {
        recursive?: boolean;
    }): AsyncIterableIterator<{
        filename: string;
        eventType: string;
    }>;
    /**
     * Execute a command
     * This is a minimal implementation that doesn't actually execute anything
     * but returns empty stdout/stderr
     */
    executeCommand(command: string, options?: {
        cwd?: string;
    }): Promise<{
        stdout: string;
        stderr: string;
    }>;
    /**
     * Rename a file or directory
     */
    rename(oldPath: string, newPath: string): Promise<void>;
    /**
     * Delete a file
     */
    unlink(filePath: string): Promise<void>;
    /**
     * Delete a directory
     */
    rmdir(dirPath: string): Promise<void>;
    /**
     * Helper method to normalize a path
     */
    private normalizePath;
    /**
     * Required by interface but no-op for in-memory FS
     */
    setFileSystem(fileSystem: IFileSystem): void;
}

/**
 * Process meld content directly from a string
 *
 * @param content - The meld content to process
 * @param options - Optional processing options
 * @returns Processed content as a string
 *
 * @example
 * ```typescript
 * import { runMeld } from 'meld';
 *
 * const meldContent = `
 *   @text greeting = "Hello"
 *   @text name = "World"
 *
 *   ${greeting}, ${name}!
 * `;
 *
 * const result = await runMeld(meldContent);
 * console.log(result); // "Hello, World!"
 * ```
 */
declare function runMeld(content: string, options?: Partial<ProcessOptions>): Promise<string>;

/**
 * @package
 * Core event system implementation for state tracking.
 *
 * @remarks
 * Provides event emission and handling for state operations.
 * Implements filtering and async event handling.
 */
declare class StateEventService implements IStateEventService {
    private handlers;
    constructor();
    /**
     * Register an event handler with optional filtering
     */
    on(type: StateEventType, handler: StateEventHandler, options?: StateEventHandlerOptions): void;
    /**
     * Remove an event handler
     */
    off(type: StateEventType, handler: StateEventHandler): void;
    /**
     * Emit a state event
     */
    emit(event: StateEvent): Promise<void>;
    /**
     * Get all registered handlers for an event type
     */
    getHandlers(type: StateEventType): Array<{
        handler: StateEventHandler;
        options?: StateEventHandlerOptions;
    }>;
}

declare const version: any;

type RequiredServices = {
    filesystem: FileSystemService;
    parser: ParserService;
    interpreter: InterpreterService;
    directive: DirectiveService;
    state: StateService;
    output: OutputService;
    eventService: StateEventService;
    path: PathService;
    validation: ValidationService;
    circularity: CircularityService;
    resolution: ResolutionService;
    debug?: StateDebuggerService;
};
declare function createDefaultServices(options: ProcessOptions): Services & RequiredServices;
declare function main(filePath: string, options?: ProcessOptions): Promise<string>;

export { CircularityService, type DirectiveLocation, DirectiveService, FileSystemService, type InterpreterErrorContext, type InterpreterLocation, InterpreterService, type Location, MeldDirectiveError, type MeldDirectiveErrorOptions, MeldInterpreterError, type MeldInterpreterErrorOptions, MeldLLMXMLError, MeldParseError, type MeldParseErrorOptions, MemoryFileSystem, OutputService, ParserService, PathOperationsService, PathService, type Position, type ProcessOptions, type Range, ResolutionService, type Services, StateService, ValidationErrorSeverity, ValidationService, createDefaultServices, runMeld as default, main, runMeld, version };