@zipbul/gildash 0.5.1 → 0.6.0

package/dist/src/gildash.d.ts

@@ -1,821 +0,0 @@
-import { type Result } from '@zipbul/result';
-import type { ParsedFile } from './parser/types';
-import { parseSource as defaultParseSource } from './parser/parse-source';
-import { ParseCache } from './parser/parse-cache';
-import type { ExtractedSymbol, SymbolKind, CodeRelation } from './extractor/types';
-import { extractSymbols as defaultExtractSymbols } from './extractor/symbol-extractor';
-import { extractRelations as defaultExtractRelations } from './extractor/relation-extractor';
-import { DbConnection } from './store/connection';
-import { FileRepository } from './store/repositories/file.repository';
-import type { FileRecord } from './store/repositories/file.repository';
-import { SymbolRepository } from './store/repositories/symbol.repository';
-import { RelationRepository } from './store/repositories/relation.repository';
-import { ProjectWatcher } from './watcher/project-watcher';
-import { IndexCoordinator } from './indexer/index-coordinator';
-import type { IndexResult } from './indexer/index-coordinator';
-import type { FileChangeEvent } from './watcher/types';
-import { acquireWatcherRole, releaseWatcherRole, updateHeartbeat } from './watcher/ownership';
-import type { WatcherOwnerStore } from './watcher/ownership';
-import { discoverProjects } from './common/project-discovery';
-import type { ProjectBoundary } from './common/project-discovery';
-import { loadTsconfigPaths } from './common/tsconfig-resolver';
-import type { TsconfigPaths } from './common/tsconfig-resolver';
-import type { ParserOptions } from 'oxc-parser';
-import { symbolSearch as defaultSymbolSearch } from './search/symbol-search';
-import type { SymbolSearchQuery, SymbolSearchResult } from './search/symbol-search';
-import { relationSearch as defaultRelationSearch } from './search/relation-search';
-import type { RelationSearchQuery } from './search/relation-search';
-import type { SymbolStats } from './store/repositories/symbol.repository';
-import type { PatternMatch } from './search/pattern-search';
-import { type GildashError } from './errors';
-/**
- * Minimal logger interface accepted by {@link Gildash}.
- *
- * Any object with an `error` method (including `console`) satisfies this interface.
- */
-export interface Logger {
-    /** Log one or more error-level messages. */
-    error(...args: unknown[]): void;
-}
-/**
- * Result of a {@link Gildash.diffSymbols} call.
- */
-export interface SymbolDiff {
-    /** Symbols present in `after` but not in `before`. */
-    added: SymbolSearchResult[];
-    /** Symbols present in `before` but not in `after`. */
-    removed: SymbolSearchResult[];
-    /** Symbols present in both but with a different `fingerprint`. */
-    modified: Array<{
-        before: SymbolSearchResult;
-        after: SymbolSearchResult;
-    }>;
-}
-/**
- * Public interface of a module — its exported symbols with key metadata.
- * Returned by {@link Gildash.getModuleInterface}.
- */
-export interface ModuleInterface {
-    filePath: string;
-    exports: Array<{
-        name: string;
-        kind: SymbolKind;
-        parameters?: string;
-        returnType?: string;
-        jsDoc?: string;
-    }>;
-}
-/**
- * A node in the heritage chain tree returned by {@link Gildash.getHeritageChain}.
- */
-export interface HeritageNode {
-    symbolName: string;
-    filePath: string;
-    /** Relationship kind (`extends` or `implements`). Undefined for the root query node. */
-    kind?: 'extends' | 'implements';
-    children: HeritageNode[];
-}
-/**
- * Full symbol detail including members, documentation, and type information.
- * Returned by {@link Gildash.getFullSymbol}.
- */
-export interface FullSymbol extends SymbolSearchResult {
-    members?: Array<{
-        name: string;
-        kind: string;
-        type?: string;
-        visibility?: string;
-        isStatic?: boolean;
-        isReadonly?: boolean;
-    }>;
-    /** JSDoc comment attached to the symbol. */
-    jsDoc?: string;
-    /** Stringified parameter list (functions/methods). */
-    parameters?: string;
-    /** Stringified return type (functions/methods). */
-    returnType?: string;
-    /** Superclass/interface names (classes/interfaces with heritage). */
-    heritage?: string[];
-    /** Decorators applied to the symbol. */
-    decorators?: Array<{
-        name: string;
-        arguments?: string;
-    }>;
-    /** Stringified type parameters (generic symbols). */
-    typeParameters?: string;
-}
-/**
- * File-level statistics for an indexed file.
- * Returned by {@link Gildash.getFileStats}.
- */
-export interface FileStats {
-    /** Absolute file path. */
-    filePath: string;
-    /** Number of lines in the file at the time of last indexing. */
-    lineCount: number;
-    /** Number of symbols indexed in the file. */
-    symbolCount: number;
-    /** Number of outgoing relations (imports, calls, etc.) from the file. */
-    relationCount: number;
-    /** File size in bytes at the time of last indexing. */
-    size: number;
-    /** Number of exported symbols in the file. */
-    exportedSymbolCount: number;
-}
-/**
- * Import-graph fan metrics for a single file.
- * Returned by {@link Gildash.getFanMetrics}.
- */
-export interface FanMetrics {
-    /** Absolute file path queried. */
-    filePath: string;
-    /** Number of files that import this file (fan-in). */
-    fanIn: number;
-    /** Number of files this file imports (fan-out). */
-    fanOut: number;
-}
-/**
- * Result of following a re-export chain to the original symbol definition.
- */
-export interface ResolvedSymbol {
-    /** The name of the symbol at the end of the re-export chain (may differ from the queried name due to aliasing). */
-    originalName: string;
-    /** Absolute path of the file that originally defines the symbol. */
-    originalFilePath: string;
-    /** Ordered list of re-export hops between the queried file and the original definition. */
-    reExportChain: Array<{
-        filePath: string;
-        exportedAs: string;
-    }>;
-}
-/**
- * Options for creating a {@link Gildash} instance via {@link Gildash.open}.
- *
- * @example
- * ```ts
- * import { isErr } from '@zipbul/result';
- *
- * const result = await Gildash.open({
- *   projectRoot: '/absolute/path/to/project',
- *   extensions: ['.ts', '.tsx'],
- *   ignorePatterns: ['vendor'],
- * });
- * if (isErr(result)) {
- *   console.error(result.data.message);
- *   process.exit(1);
- * }
- * const ledger = result;
- * ```
- */
-export interface GildashOptions {
-    /** Absolute path to the project root directory. */
-    projectRoot: string;
-    /** File extensions to index. Defaults to `['.ts', '.mts', '.cts']`. */
-    extensions?: string[];
-    /** Glob patterns to ignore during indexing. */
-    ignorePatterns?: string[];
-    /** Maximum number of parsed ASTs to keep in the LRU cache. Defaults to `500`. */
-    parseCacheCapacity?: number;
-    /** Logger for error output. Defaults to `console`. */
-    logger?: Logger;
-    /**
-     * When `false`, disables the file watcher and runs in scan-only mode:
-     * ownership contention is skipped, heartbeat and signal handlers are not
-     * registered, and only the initial `fullIndex()` is performed.
-     *
-     * Set `cleanup: true` in {@link Gildash.close} to remove the database files
-     * after a one-shot scan.
-     *
-     * @default true
-     */
-    watchMode?: boolean;
-}
-interface GildashInternalOptions {
-    existsSyncFn?: (p: string) => boolean;
-    dbConnectionFactory?: () => Pick<DbConnection, 'open' | 'close' | 'transaction'> & WatcherOwnerStore;
-    watcherFactory?: () => Pick<ProjectWatcher, 'start' | 'close'>;
-    coordinatorFactory?: () => Pick<IndexCoordinator, 'fullIndex' | 'shutdown' | 'onIndexed'> & {
-        tsconfigPaths?: Promise<TsconfigPaths | null>;
-        handleWatcherEvent?(event: FileChangeEvent): void;
-    };
-    repositoryFactory?: () => {
-        fileRepo: Pick<FileRepository, 'upsertFile' | 'getAllFiles' | 'getFilesMap' | 'deleteFile' | 'getFile'>;
-        symbolRepo: SymbolRepository;
-        relationRepo: RelationRepository;
-        parseCache: Pick<ParseCache, 'set' | 'get' | 'invalidate'>;
-    };
-    acquireWatcherRoleFn?: typeof acquireWatcherRole;
-    releaseWatcherRoleFn?: typeof releaseWatcherRole;
-    updateHeartbeatFn?: typeof updateHeartbeat;
-    discoverProjectsFn?: typeof discoverProjects;
-    parseSourceFn?: typeof defaultParseSource;
-    extractSymbolsFn?: typeof defaultExtractSymbols;
-    extractRelationsFn?: typeof defaultExtractRelations;
-    symbolSearchFn?: typeof defaultSymbolSearch;
-    relationSearchFn?: typeof defaultRelationSearch;
-    patternSearchFn?: (opts: {
-        pattern: string;
-        filePaths: string[];
-    }) => Promise<PatternMatch[]>;
-    loadTsconfigPathsFn?: typeof loadTsconfigPaths;
-    readFileFn?: (filePath: string) => Promise<string>;
-    unlinkFn?: (filePath: string) => Promise<void>;
-    makeExternalCoordinatorFn?: (packageDir: string, project: string) => {
-        fullIndex(): Promise<IndexResult>;
-    };
-}
-/**
- * Main entry point for gildash.
- *
- * `Gildash` indexes TypeScript source code into a local SQLite database,
- * watches for file changes, and provides search / dependency-graph queries.
- *
- * Every public method returns a `Result<T, GildashError>` — either the
- * success value `T` directly, or an `Err<GildashError>` that can be checked
- * with `isErr()` from `@zipbul/result`.
- *
- * Create an instance with the static {@link Gildash.open} factory.
- * Always call {@link Gildash.close} when done to release resources.
- *
- * @example
- * ```ts
- * import { Gildash } from '@zipbul/gildash';
- * import { isErr } from '@zipbul/result';
- *
- * const result = await Gildash.open({ projectRoot: '/my/project' });
- * if (isErr(result)) {
- *   console.error(result.data.message);
- *   process.exit(1);
- * }
- * const ledger = result;
- *
- * const symbols = ledger.searchSymbols({ text: 'handle', kind: 'function' });
- * if (!isErr(symbols)) {
- *   symbols.forEach(s => console.log(s.name));
- * }
- *
- * await ledger.close();
- * ```
- */
-export declare class Gildash {
-    /** Absolute path to the indexed project root. */
-    readonly projectRoot: string;
-    private readonly db;
-    private readonly symbolRepo;
-    private readonly relationRepo;
-    private readonly fileRepo;
-    private readonly parseCache;
-    private coordinator;
-    private watcher;
-    private readonly releaseWatcherRoleFn;
-    private readonly parseSourceFn;
-    private readonly extractSymbolsFn;
-    private readonly extractRelationsFn;
-    private readonly symbolSearchFn;
-    private readonly relationSearchFn;
-    private readonly patternSearchFn;
-    private readonly readFileFn;
-    private readonly unlinkFn;
-    private readonly existsSyncFn;
-    private readonly makeExternalCoordinatorFn?;
-    private readonly logger;
-    private readonly defaultProject;
-    /** Current watcher role: `'owner'` (can reindex) or `'reader'` (read-only). */
-    readonly role: 'owner' | 'reader';
-    private timer;
-    private signalHandlers;
-    private closed;
-    private tsconfigPaths;
-    private boundaries;
-    private readonly onIndexedCallbacks;
-    /** Cached DependencyGraph — invalidated on each index run. */
-    private graphCache;
-    /** Project key of the cached graph (`project ?? '__cross__'`). */
-    private graphCacheKey;
-    private constructor();
-    /**
-     * Create and initialise a new `Gildash` instance.
-     *
-     * Opens (or creates) a SQLite database alongside the project root,
-     * discovers sub-projects, acquires a watcher role, performs initial indexing,
-     * and begins watching for file changes.
-     *
-     * @param options - Configuration for the instance.
-     * @returns A fully-initialised `Gildash` ready for queries, or an `Err<GildashError>` on failure.
-     *
-     * @example
-     * ```ts
-     * const result = await Gildash.open({
-     *   projectRoot: '/home/user/my-app',
-     *   extensions: ['.ts', '.tsx'],
-     * });
-     * if (isErr(result)) { console.error(result.data.message); process.exit(1); }
-     * const ledger = result;
-     * ```
-     */
-    static open(options: GildashOptions & GildashInternalOptions): Promise<Result<Gildash, GildashError>>;
-    /**
-     * Shut down the instance and release all resources.
-     *
-     * Stops the file watcher, shuts down the index coordinator,
-     * releases the watcher ownership role, and closes the database.
-     * Calling `close()` more than once is safe (subsequent calls are no-ops).
-     *
-     * @returns `void` on success, or `Err<GildashError>` with `type='close'` if one or more
-     *   sub-systems failed during shutdown.  The `cause` field contains an array of
-     *   individual errors from each failed sub-system.
-     *
-     * @example
-     * ```ts
-     * const closeResult = await ledger.close();
-     * if (isErr(closeResult)) {
-     *   console.error('Close failed:', closeResult.data.message);
-     *   // closeResult.data.cause is unknown[] of per-subsystem errors
-     * }
-     * ```
-     */
-    close(opts?: {
-        cleanup?: boolean;
-    }): Promise<Result<void, GildashError>>;
-    /**
-     * Register a callback that fires after each indexing run completes.
-     *
-     * @param callback - Receives the {@link IndexResult} for the completed run.
-     * @returns An unsubscribe function. Call it to remove the listener.
-     *
-     * @example
-     * ```ts
-     * const off = ledger.onIndexed(result => {
-     *   console.log(`Indexed ${result.filesProcessed} files`);
-     * });
-     * // later…
-     * off();
-     * ```
-     */
-    onIndexed(callback: (result: IndexResult) => void): () => void;
-    /**
-     * Parse a TypeScript source string into an AST and cache the result.
-     *
-     * On success the result is automatically stored in the internal LRU parse cache
-     * so that subsequent calls to extraction methods can reuse it.
-     *
-     * @param filePath - File path used as the cache key and for diagnostics.
-     * @param sourceText - Raw TypeScript source code.
-     * @param options - Optional oxc-parser {@link ParserOptions} (e.g. `sourceType`, `lang`).
-     * @returns A {@link ParsedFile}, or `Err<GildashError>` with `type='closed'` if the instance
-     *   is closed, or `type='parse'` if the parser fails.
-     *
-     * @example
-     * ```ts
-     * const parsed = ledger.parseSource('/project/src/app.ts', sourceCode);
-     * if (isErr(parsed)) {
-     *   console.error(parsed.data.message); // e.g. "Failed to parse file: ..."
-     *   return;
-     * }
-     * // parsed is now a ParsedFile
-     * const symbols = ledger.extractSymbols(parsed);
-     * ```
-     */
-    parseSource(filePath: string, sourceText: string, options?: ParserOptions): Result<ParsedFile, GildashError>;
-    /**
-     * Extract all symbol declarations from a previously parsed file.
-     *
-     * Returns function, class, variable, type-alias, interface, and enum declarations
-     * found in the AST.
-     *
-     * @param parsed - A {@link ParsedFile} obtained from {@link parseSource}.
-     * @returns An array of {@link ExtractedSymbol} entries, or `Err<GildashError>` with
-     *   `type='closed'` if the instance is closed.
-     *
-     * @example
-     * ```ts
-     * const symbols = ledger.extractSymbols(parsed);
-     * if (isErr(symbols)) return;
-     * for (const sym of symbols) {
-     *   console.log(`${sym.kind}: ${sym.name}`);
-     * }
-     * ```
-     */
-    extractSymbols(parsed: ParsedFile): Result<ExtractedSymbol[], GildashError>;
-    /**
-     * Extract inter-file relationships (imports, calls, extends, implements)
-     * from a previously parsed file.
-     *
-     * If tsconfig path aliases were discovered during {@link Gildash.open},
-     * they are automatically applied when resolving import targets.
-     *
-     * @param parsed - A {@link ParsedFile} obtained from {@link parseSource}.
-     * @returns An array of {@link CodeRelation} entries, or `Err<GildashError>` with
-     *   `type='closed'` if the instance is closed.
-     *
-     * @example
-     * ```ts
-     * const relations = ledger.extractRelations(parsed);
-     * if (isErr(relations)) return;
-     * const imports = relations.filter(r => r.type === 'imports');
-     * ```
-     */
-    extractRelations(parsed: ParsedFile): Result<CodeRelation[], GildashError>;
-    /** Invalidate the cached DependencyGraph (called after every index run). */
-    private invalidateGraphCache;
-    /**
-     * Return a cached or freshly-built {@link DependencyGraph} for the given project.
-     *
-     * Builds once per `project ?? '__cross__'` key; subsequent calls with the same key
-     * return the cached instance. Cache is invalidated by {@link invalidateGraphCache}.
-     */
-    private getOrBuildGraph;
-    /**
-     * Trigger a full re-index of all tracked files.
-     *
-     * Only available to the instance that holds the *owner* role.
-     * Reader instances receive `Err<GildashError>` with `type='closed'`.
-     *
-     * @returns An {@link IndexResult} summary on success, or `Err<GildashError>` with
-     *   `type='closed'` if the instance is closed / reader,
-     *   `type='index'` if the indexing pipeline fails.
-     *
-     * @example
-     * ```ts
-     * const result = await ledger.reindex();
-     * if (isErr(result)) {
-     *   console.error(result.data.message);
-     *   return;
-     * }
-     * console.log(`Indexed ${result.indexedFiles} files in ${result.durationMs}ms`);
-     * ```
-     */
-    reindex(): Promise<Result<IndexResult, GildashError>>;
-    /**
-     * Discovered project boundaries within the project root.
-     *
-     * Each entry contains a project name and its root directory.
-     */
-    get projects(): ProjectBoundary[];
-    /**
-     * Return aggregate symbol statistics for the given project.
-     *
-     * @param project - Project name. Defaults to the auto-discovered primary project.
-     * @returns A {@link SymbolStats} object with counts grouped by symbol kind,
-     *   or `Err<GildashError>` with `type='closed'` if the instance is closed,
-     *   `type='store'` if the database query fails.
-     *
-     * @example
-     * ```ts
-     * const stats = ledger.getStats();
-     * if (isErr(stats)) return;
-     * console.log(`Files: ${stats.fileCount}, Symbols: ${stats.symbolCount}`);
-     * ```
-     */
-    getStats(project?: string): Result<SymbolStats, GildashError>;
-    /**
-     * Search indexed symbols by name, kind, file path, or export status.
-     *
-     * @param query - Search filters (see {@link SymbolSearchQuery}). All fields are optional;
-     *   omitted fields match everything.
-     * @returns An array of {@link SymbolSearchResult} entries, or `Err<GildashError>` with
-     *   `type='closed'` if the instance is closed,
-     *   `type='search'` if the query fails.
-     *
-     * @example
-     * ```ts
-     * const fns = ledger.searchSymbols({ kind: 'function', isExported: true });
-     * if (isErr(fns)) return;
-     * fns.forEach(fn => console.log(fn.name, fn.filePath));
-     * ```
-     */
-    searchSymbols(query: SymbolSearchQuery): Result<SymbolSearchResult[], GildashError>;
-    /**
-     * Search indexed code relationships (imports, calls, extends, implements).
-     *
-     * @param query - Search filters (see {@link RelationSearchQuery}). All fields are optional.
-     * @returns An array of {@link CodeRelation} entries, or `Err<GildashError>` with
-     *   `type='closed'` if the instance is closed,
-     *   `type='search'` if the query fails.
-     *
-     * @example
-     * ```ts
-     * const rels = ledger.searchRelations({ srcFilePath: 'src/app.ts', type: 'imports' });
-     * if (isErr(rels)) return;
-     * rels.forEach(r => console.log(`${r.srcFilePath} -> ${r.dstFilePath}`));
-     * ```
-     */
-    searchRelations(query: RelationSearchQuery): Result<CodeRelation[], GildashError>;
-    /**
-     * Search symbols across all projects (no project filter).
-     *
-     * @param query - Search filters (see {@link SymbolSearchQuery}). The `project` field is ignored.
-     * @returns An array of {@link SymbolSearchResult} entries, or `Err<GildashError>` with
-     *   `type='closed'` if the instance is closed,
-     *   `type='search'` if the query fails.
-     */
-    searchAllSymbols(query: Omit<SymbolSearchQuery, 'project'> & {
-        project?: string;
-    }): Result<SymbolSearchResult[], GildashError>;
-    /**
-     * Search relations across all projects (no project filter).
-     *
-     * @param query - Search filters (see {@link RelationSearchQuery}). The `project` field is ignored.
-     * @returns An array of {@link CodeRelation} entries, or `Err<GildashError>` with
-     *   `type='closed'` if the instance is closed,
-     *   `type='search'` if the query fails.
-     */
-    searchAllRelations(query: RelationSearchQuery): Result<CodeRelation[], GildashError>;
-    /**
-     * List all files indexed for a given project.
-     *
-     * @param project - Project name. Defaults to the primary project.
-     * @returns An array of {@link FileRecord} entries, or `Err<GildashError>` with
-     *   `type='closed'` if the instance is closed,
-     *   `type='store'` if the repository query fails.
-     */
-    listIndexedFiles(project?: string): Result<FileRecord[], GildashError>;
-    /**
-     * Get all intra-file relations for a given file (relations where both source and destination
-     * are within the same file).
-     *
-     * @param filePath - Path of the file to query.
-     * @param project - Project name. Defaults to the primary project.
-     * @returns An array of {@link CodeRelation} entries, or `Err<GildashError>` with
-     *   `type='closed'` if the instance is closed,
-     *   `type='search'` if the query fails.
-     */
-    getInternalRelations(filePath: string, project?: string): Result<CodeRelation[], GildashError>;
-    /**
-     * Compare two snapshots of symbol search results and return a structured diff.
-     *
-     * Symbols are keyed by `name::filePath`. A symbol is:
-     * - **added** if it appears only in `after`
-     * - **removed** if it appears only in `before`
-     * - **modified** if it appears in both but with a different `fingerprint`
-     * - **unchanged** otherwise
-     *
-     * @param before - Snapshot of symbols before the change.
-     * @param after - Snapshot of symbols after the change.
-     * @returns A {@link SymbolDiff} object.
-     */
-    diffSymbols(before: SymbolSearchResult[], after: SymbolSearchResult[]): SymbolDiff;
-    /**
-     * List the files that a given file directly imports.
-     *
-     * @param filePath - Absolute path of the source file.
-     * @param project - Project name. Defaults to the primary project.
-     * @param limit - Maximum results. Defaults to `10_000`.
-     * @returns An array of absolute paths that `filePath` imports,
-     *   or `Err<GildashError>` with `type='closed'` / `type='search'`.
-     *
-     * @example
-     * ```ts
-     * const deps = ledger.getDependencies('/project/src/app.ts');
-     * if (isErr(deps)) return;
-     * console.log('Imports:', deps.join(', '));
-     * ```
-     */
-    getDependencies(filePath: string, project?: string, limit?: number): Result<string[], GildashError>;
-    /**
-     * List the files that directly import a given file.
-     *
-     * @param filePath - Absolute path of the target file.
-     * @param project - Project name. Defaults to the primary project.
-     * @param limit - Maximum results. Defaults to `10_000`.
-     * @returns An array of absolute paths of files that import `filePath`,
-     *   or `Err<GildashError>` with `type='closed'` / `type='search'`.
-     *
-     * @example
-     * ```ts
-     * const dependents = ledger.getDependents('/project/src/utils.ts');
-     * if (isErr(dependents)) return;
-     * console.log('Imported by:', dependents.join(', '));
-     * ```
-     */
-    getDependents(filePath: string, project?: string, limit?: number): Result<string[], GildashError>;
-    /**
-     * Compute the full set of files transitively affected by changes.
-     *
-     * Internally builds a full {@link DependencyGraph} and walks all reverse
-     * edges from each changed file to find every transitive dependent.
-     *
-     * @param changedFiles - Absolute paths of files that changed.
-     * @param project - Project name. Defaults to the primary project.
-     * @returns De-duplicated absolute paths of all transitively-dependent files
-     *   (excluding the changed files themselves), or `Err<GildashError>` with
-     *   `type='closed'` / `type='search'`.
-     *
-     * @example
-     * ```ts
-     * const affected = await ledger.getAffected(['/project/src/utils.ts']);
-     * if (isErr(affected)) return;
-     * console.log('Affected files:', affected.length);
-     * ```
-     */
-    getAffected(changedFiles: string[], project?: string): Promise<Result<string[], GildashError>>;
-    /**
-     * Check whether the import graph contains a circular dependency.
-     *
-     * Internally builds a full {@link DependencyGraph} and runs iterative DFS
-     * cycle detection.
-     *
-     * @param project - Project name. Defaults to the primary project.
-     * @returns `true` if at least one cycle exists, `false` otherwise,
-     *   or `Err<GildashError>` with `type='closed'` / `type='search'`.
-     *
-     * @example
-     * ```ts
-     * const cycleResult = await ledger.hasCycle();
-     * if (isErr(cycleResult)) return;
-     * if (cycleResult) {
-     *   console.warn('Circular dependency detected!');
-     * }
-     * ```
-     */
-    hasCycle(project?: string): Promise<Result<boolean, GildashError>>;
-    /**
-     * Return the full import graph for a project as an adjacency list.
-     *
-     * Builds a {@link DependencyGraph} and exposes its internal adjacency list.
-     * Each file appears as a key; its value lists the files it directly imports.
-     * Files that are imported but do not themselves import appear as keys with empty arrays.
-     *
-     * @param project - Project name. Defaults to the primary project.
-     * @returns A `Map<filePath, importedFilePaths[]>`, or `Err<GildashError>` with
-     *   `type='closed'` / `type='search'`.
-     */
-    getImportGraph(project?: string): Promise<Result<Map<string, string[]>, GildashError>>;
-    /**
-     * Return all files that `filePath` transitively imports (forward BFS).
-     *
-     * @param filePath - Absolute path of the starting file.
-     * @param project - Project name. Defaults to the primary project.
-     * @returns An array of file paths that `filePath` directly or indirectly imports,
-     *   or `Err<GildashError>` with `type='closed'` / `type='search'`.
-     */
-    getTransitiveDependencies(filePath: string, project?: string): Promise<Result<string[], GildashError>>;
-    /**
-     * Return all cycle paths in the import graph.
-     *
-     * Tarjan SCC + Johnson's circuits — 모든 elementary circuit 보장.
-     * 단순한 사이클 유무(`hasCycle`)와 달리 중복 없는 정규화된 경로 전체를 반환합니다.
-     * `maxCycles` 옵션으로 반환 개수를 제한할 수 있습니다.
-     *
-     * @param project - Project name. Defaults to the primary project.
-     * @param options.maxCycles - Maximum number of cycles to return. Defaults to no limit.
-     * @returns An array of cycle paths (`string[][]`), each path starting at the
-     *   lexicographically smallest node (canonical rotation). Returns `[]` if no cycles exist.
-     *   Returns `Err<GildashError>` with `type='closed'` (instance closed) or `type='search'` (graph error).
-     */
-    getCyclePaths(project?: string, options?: {
-        maxCycles?: number;
-    }): Promise<Result<string[][], GildashError>>;
-    /**
-     * Retrieve full details for a named symbol in a specific file,
-     * including members, documentation, and type information.
-     *
-     * @param symbolName - Exact symbol name to look up.
-     * @param filePath   - Absolute path of the file containing the symbol.
-     * @param project    - Project scope override (defaults to `defaultProject`).
-     * @returns A {@link FullSymbol} on success, or `Err<GildashError>` with
-     *   `type='closed'` if the instance is closed,
-     *   `type='search'` if the symbol is not found or the query fails.
-     */
-    getFullSymbol(symbolName: string, filePath: string, project?: string): Result<FullSymbol, GildashError>;
-    /**
-     * Retrieve statistics for an indexed file (line count, symbol count, etc.).
-     *
-     * @param filePath - Absolute path of the file to query.
-     * @param project  - Project scope override (defaults to `defaultProject`).
-     * @returns A {@link FileStats} on success, or `Err<GildashError>` with
-     *   `type='closed'` if the instance is closed,
-     *   `type='search'` if the file is not in the index,
-     *   `type='store'` if the query throws.
-     */
-    getFileStats(filePath: string, project?: string): Result<FileStats, GildashError>;
-    /**
-     * Compute import-graph fan metrics (fan-in / fan-out) for a single file.
-     *
-     * Builds a full {@link DependencyGraph} each call (O(relations)).
-     * For repeated calls, consider caching the graph externally.
-     *
-     * @param filePath - Absolute path of the file to query.
-     * @param project  - Project scope override (defaults to `defaultProject`).
-     * @returns A {@link FanMetrics} on success, or `Err<GildashError>` with
-     *   `type='closed'` if the instance is closed,
-     *   `type='search'` if the graph build fails.
-     */
-    getFanMetrics(filePath: string, project?: string): Promise<Result<FanMetrics, GildashError>>;
-    /**
-     * Resolve the original definition location of a symbol by following its re-export chain.
-     *
-     * Traverses `re-exports` relations iteratively until no further hop is found or a
-     * circular chain is detected.
-     *
-     * @param symbolName - The exported name to resolve.
-     * @param filePath   - The file from which the symbol is exported.
-     * @param project    - Project scope override (defaults to `defaultProject`).
-     * @returns A {@link ResolvedSymbol} on success, or `Err<GildashError>` with
-     *   `type='closed'` if the instance is closed,
-     *   `type='search'` if a circular re-export chain is detected.
-     */
-    resolveSymbol(symbolName: string, filePath: string, project?: string): Result<ResolvedSymbol, GildashError>;
-    /**
-     * Search for an AST structural pattern across indexed TypeScript files.
-     *
-     * Uses ast-grep's `findInFiles` under the hood. Provide `opts.filePaths` to
-     * limit search scope; otherwise all files tracked by the project index are searched.
-     *
-     * @param pattern   - ast-grep structural pattern (e.g. `'console.log($$$)'`).
-     * @param opts      - Optional scope: file paths and/or project override.
-     * @returns An array of {@link PatternMatch} on success, or `Err<GildashError>` with
-     *   `type='closed'` if the instance is closed,
-     *   `type='search'` if the underlying search fails.
-     */
-    findPattern(pattern: string, opts?: {
-        filePaths?: string[];
-        project?: string;
-    }): Promise<Result<PatternMatch[], GildashError>>;
-    /**
-     * Index the TypeScript type declarations (`.d.ts` files) of one or more
-     * `node_modules` packages.
-     *
-     * Each package is indexed under a dedicated `@external/<packageName>` project
-     * so it does not pollute the main project index. Subsequent calls re-index
-     * (incremental diff) the same package.
-     *
-     * @param packages - Package names as they appear in `node_modules/`
-     *   (e.g. `['react', 'typescript']`).
-     * @param opts     - Optional overrides (unused currently, reserved for future use).
-     * @returns An array of {@link IndexResult} — one per package — on success,
-     *   or `Err<GildashError>` with:
-     *   - `type='closed'` if the instance is closed or in reader mode,
-     *   - `type='validation'` if a requested package is not found in `node_modules/`,
-     *   - `type='store'` if indexing fails at runtime.
-     */
-    indexExternalPackages(packages: string[], opts?: {
-        project?: string;
-    }): Promise<Result<IndexResult[], GildashError>>;
-    /**
-     * Parse multiple files concurrently and return a map of results.
-     *
-     * Files that fail to read or parse are silently excluded from the result map.
-     * The operation does not fail even if every file fails — it returns an empty `Map`.
-     *
-     * @param filePaths - Absolute paths of files to parse.
-     * @param options - Optional oxc-parser {@link ParserOptions} (e.g. `sourceType`, `lang`).
-     * @returns A `Map<filePath, ParsedFile>` for every successfully-parsed file,
-     *   or `Err<GildashError>` with `type='closed'` if the instance is closed.
-     */
-    batchParse(filePaths: string[], options?: ParserOptions): Promise<Result<Map<string, ParsedFile>, GildashError>>;
-    /**
-     * Return the public interface of a module: all exported symbols with key metadata.
-     *
-     * @param filePath - Absolute path of the file.
-     * @param project - Project name. Defaults to the primary project.
-     * @returns A {@link ModuleInterface} object, or `Err<GildashError>` with
-     *   `type='closed'` / `type='search'`.
-     */
-    getModuleInterface(filePath: string, project?: string): Result<ModuleInterface, GildashError>;
-    /**
-     * Recursively traverse `extends`/`implements` relations to build a heritage tree.
-     *
-     * The root node represents `symbolName`/`filePath`. Its `children` are the symbols
-     * it extends or implements, and so on transitively. A visited set prevents cycles.
-     *
-     * @param symbolName - Name of the starting symbol.
-     * @param filePath - Absolute path of the file containing the symbol.
-     * @param project - Project name. Defaults to the primary project.
-     * @returns A {@link HeritageNode} tree, or `Err<GildashError>` with
-     *   `type='closed'` / `type='search'`.
-     */
-    getHeritageChain(symbolName: string, filePath: string, project?: string): Promise<Result<HeritageNode, GildashError>>;
-    /**
-     * Retrieve a previously-parsed AST from the internal LRU cache.
-     *
-     * Returns `undefined` if the file has not been parsed or was evicted from the cache.
-     * The returned object is shared with the internal cache — treat it as **read-only**.
-     *
-     * @param filePath - Absolute path of the file.
-     * @returns The cached {@link ParsedFile}, or `undefined` if not available.
-     */
-    getParsedAst(filePath: string): ParsedFile | undefined;
-    /**
-     * Retrieve metadata for an indexed file.
-     *
-     * Returns the stored {@link FileRecord} including content hash, mtime, and size.
-     * Returns `null` if the file has not been indexed yet.
-     *
-     * @param filePath - Relative path from project root (as stored in the index).
-     * @param project - Project name. Defaults to the primary project.
-     * @returns The {@link FileRecord}, or `null` if not found.
-     */
-    getFileInfo(filePath: string, project?: string): Result<FileRecord | null, GildashError>;
-    /**
-     * List all symbols declared in a specific file.
-     *
-     * Convenience wrapper around {@link searchSymbols} with a `filePath` filter.
-     *
-     * @param filePath - File path to query.
-     * @param project - Project name. Defaults to the primary project.
-     * @returns An array of {@link SymbolSearchResult} entries, or `Err<GildashError>`.
-     */
-    getSymbolsByFile(filePath: string, project?: string): Result<SymbolSearchResult[], GildashError>;
-}
-export {};