import { AutoCompleter } from './AutoCompleter/AutoCompleter';
import type { DvalaModule } from './builtin/modules/interface';
import type { FileResolver } from './evaluator/ContextStack';
import type { DvalaBundle } from './bundler/interface';
import type { Handlers, RunResult, SnapshotState } from './evaluator/effectTypes';
import { type TypeDiagnostic, type TypecheckResult } from './typechecker/typecheck';
export interface CreateDvalaOptions {
    /** Built-in modules to register (e.g. `allBuiltinModules`). */
    modules?: DvalaModule[];
    /** Factory-level effect handlers, checked after per-call handlers. */
    effectHandlers?: Handlers;
    /** Maximum number of cached ASTs. Default: 100. */
    cache?: number;
    /** Enable debug tokenization: captures source positions for better error messages. */
    debug?: boolean;
    /** Disable time travel features (auto-checkpointing and terminal snapshots). Enabled by default. */
    disableAutoCheckpoint?: boolean;
    /**
     * Callback to resolve file imports (`import("./path")`) at runtime.
     * Receives `(importPath, fromDir)` where `importPath` is the string from the
     * import expression and `fromDir` is the directory of the importing file.
     * Must return the file's source code as a string.
     *
     * Without a resolver, file imports throw a TypeError.
     * The `.dvala` extension is optional in import paths — the resolver should
     * try the exact path first, then append `.dvala`.
     *
     * Results are cached automatically: the same import path is only resolved once.
     * Circular imports are detected and reported as errors.
     *
     * @example
     * ```typescript
     * createDvala({
     *   fileResolver: (importPath, fromDir) => {
     *     const resolved = path.resolve(fromDir, importPath)
     *     if (fs.existsSync(resolved)) return fs.readFileSync(resolved, 'utf-8')
     *     const withExt = resolved + '.dvala'
     *     if (fs.existsSync(withExt)) return fs.readFileSync(withExt, 'utf-8')
     *     throw new Error(`File not found: ${importPath}`)
     *   },
     *   fileResolverBaseDir: './my-project',
     * })
     * ```
     */
    fileResolver?: FileResolver;
    /**
     * Base directory for the first file import resolution.
     * Nested imports resolve relative to their own file's directory automatically.
     * Default: `'.'`
     */
    fileResolverBaseDir?: string;
    /**
     * Enable type checking (default: true). Source code is type-checked after parsing.
     * Type errors are reported via `onTypeDiagnostic` but do NOT block evaluation.
     * Set to `false` to skip type checking for performance.
     */
    typecheck?: boolean;
    /**
     * Callback invoked with type diagnostics after type checking.
     * Only called when `typecheck: true`.
     */
    onTypeDiagnostic?: (diagnostic: TypeDiagnostic) => void;
}
/**
 * Options for `run()`. When `pure` is `true`, `effectHandlers` cannot be provided.
 */
export type DvalaRunOptions = {
    scope?: Record<string, unknown>;
    pure: true;
    effectHandlers?: never;
    filePath?: string;
} | {
    scope?: Record<string, unknown>;
    pure?: false;
    effectHandlers?: Handlers;
    filePath?: string;
};
/**
 * Options for `runAsync()`. When `pure` is `true`, `effectHandlers` cannot be provided.
 * Time travel (auto-checkpointing and terminal snapshots) is enabled by default.
 * Set `disableAutoCheckpoint: true` to opt out.
 */
export type DvalaRunAsyncOptions = {
    scope?: Record<string, unknown>;
    pure: true;
    effectHandlers?: never;
    maxSnapshots?: number;
    disableAutoCheckpoint?: boolean;
    terminalSnapshot?: boolean;
    onNodeEval?: SnapshotState['onNodeEval'];
    filePath?: string;
} | {
    scope?: Record<string, unknown>;
    pure?: false;
    effectHandlers?: Handlers;
    maxSnapshots?: number;
    disableAutoCheckpoint?: boolean;
    terminalSnapshot?: boolean;
    onNodeEval?: SnapshotState['onNodeEval'];
    filePath?: string;
};
export interface DvalaRunner {
    run: (source: string | DvalaBundle, options?: DvalaRunOptions) => unknown;
    runAsync: (source: string | DvalaBundle, options?: DvalaRunAsyncOptions) => Promise<RunResult>;
    getUndefinedSymbols: (source: string, symbolsOptions?: {
        scope?: Record<string, unknown>;
    }) => Set<string>;
    getAutoCompleter: (program: string, position: number) => AutoCompleter;
    /** Typecheck source code and return diagnostics + type map. */
    typecheck: (source: string, options?: {
        fileResolverBaseDir?: string;
        filePath?: string;
        fold?: boolean;
    }) => TypecheckResult;
}
export declare function createDvala(options?: CreateDvalaOptions): DvalaRunner;