import { type BuildSpiOptions } from './build.js';
import type { SemanticProgramIndex } from './types.js';
export interface SpiCacheIndex {
    format_version: number;
    cache_key: string;
    generated_at: string;
    file_count: number;
    extractor_version: string;
}
export interface SpiCacheStats {
    hit: boolean;
    reason: 'fresh-cache' | 'no-cache' | 'key-mismatch' | 'format-version-mismatch' | 'corrupt-cache' | 'cache-disabled';
    file_count: number;
    cache_key: string;
    duration_ms: number;
}
export interface BuildSpiCachedOptions extends BuildSpiOptions {
    /** Disable the cache for this build (default: false). When true, the
     *  call behaves exactly like buildSpi() — no read, no write. */
    noCache?: boolean;
    /** Override the cache directory (default: Madar's workspace-specific
     *  artifact output directory plus `.spi-cache`).
     *  Useful for tests and for projects that want to relocate the cache
     *  outside the default out tree. */
    cacheDir?: string;
    /** Receives a stats payload after the call. Lets callers log/measure
     *  whether the cache was used without re-deriving the key themselves. */
    onCacheLookup?: (stats: SpiCacheStats) => void;
}
export interface BuildSpiCachedResult {
    spi: SemanticProgramIndex;
    cache: SpiCacheStats;
}
/**
 * Build (or re-use) a SemanticProgramIndex for the workspace, persisting
 * the result to disk so the next call with an unchanged workspace
 * returns the cached value without re-running the full ts.Program pass.
 *
 * The cache is opt-in: callers must use `buildSpiCached` explicitly; the
 * existing `buildSpi` continues to do a full rebuild every time so any
 * code path that relies on freshness is not affected by this slice.
 */
export declare function buildSpiCached(opts: BuildSpiCachedOptions): BuildSpiCachedResult;
/** Explicit cache invalidation — removes the on-disk artifacts.
 *  Returns true iff anything was deleted. */
export declare function clearSpiCache(root: string, cacheDir?: string): boolean;