@zipbul/gildash 0.0.1

package/dist/src/extractor/types.d.ts

@@ -0,0 +1,162 @@
+import type { SourcePosition, SourceSpan } from '../parser/types';
+/**
+ * The kind of a symbol extracted from TypeScript source.
+ *
+ * - `'function'` — standalone function declarations and expressions
+ * - `'method'` — class methods, getters, setters, and constructors
+ * - `'class'` — class declarations
+ * - `'variable'` — `const`, `let`, `var` declarations
+ * - `'type'` — type alias declarations
+ * - `'interface'` — interface declarations
+ * - `'enum'` — enum declarations
+ * - `'property'` — class properties and interface/type members
+ */
+export type SymbolKind = 'function' | 'method' | 'class' | 'variable' | 'type' | 'interface' | 'enum' | 'property';
+/**
+ * TypeScript declaration modifiers attached to a symbol.
+ */
+export type Modifier = 'async' | 'static' | 'abstract' | 'readonly' | 'private' | 'protected' | 'public' | 'override' | 'declare' | 'const';
+/**
+ * A function/method parameter.
+ */
+export interface Parameter {
+    /** Parameter name. */
+    name: string;
+    /** Type annotation as raw source text, e.g. `"string"`, `"number[]"`. */
+    type?: string;
+    /** Whether the parameter is optional (has `?` or a default value). */
+    isOptional: boolean;
+    /** Default value expression as source text. */
+    defaultValue?: string;
+    /** Decorators applied to this parameter (e.g. `@Inject`, `@Body`). */
+    decorators?: Decorator[];
+}
+/**
+ * A class/interface heritage clause (`extends` or `implements`).
+ */
+export interface Heritage {
+    /** Whether this is an `extends` or `implements` clause. */
+    kind: 'extends' | 'implements';
+    /** Name of the base class or implemented interface. */
+    name: string;
+    /** Generic type arguments, e.g. `['T', 'U']`. */
+    typeArguments?: string[];
+}
+/**
+ * A decorator applied to a class, method, property, or parameter.
+ */
+export interface Decorator {
+    /** Decorator name without `@`. */
+    name: string;
+    /** Decorator call arguments as source text. */
+    arguments?: string[];
+}
+/**
+ * A single JSDoc tag parsed from a documentation comment.
+ *
+ * @example
+ * For `@param name - The user's name`:
+ * ```ts
+ * { tag: 'param', name: 'name', type: '', description: "The user's name", optional: false }
+ * ```
+ */
+export interface JsDocTag {
+    /** Tag name without `@` (e.g. `'param'`, `'returns'`, `'deprecated'`). */
+    tag: string;
+    /** First word after the tag, typically a parameter name for `@param`. */
+    name: string;
+    /** Type in curly braces (e.g. `'{string}'` → `'string'`). Empty if absent. */
+    type: string;
+    /** Description text following the name. */
+    description: string;
+    /** `true` if the name is wrapped in `[brackets]` (optional parameter). */
+    optional: boolean;
+    /** Default value if `[name=default]` syntax is used. */
+    default?: string;
+}
+/**
+ * A parsed JSDoc documentation comment block.
+ */
+export interface JsDocBlock {
+    /** Full description text before any tags. */
+    description: string;
+    /** Parsed `@tag` entries. */
+    tags: JsDocTag[];
+}
+/**
+ * A symbol extracted from a TypeScript source file.
+ *
+ * Represents a single named declaration (function, class, variable, type, etc.)
+ * with its location, metadata, and optional nested members.
+ */
+export interface ExtractedSymbol {
+    /** What kind of symbol this is. */
+    kind: SymbolKind;
+    /** Symbol name (e.g. `'MyClass'`, `'handleClick'`). */
+    name: string;
+    /** Source location (start/end line and column). */
+    span: SourceSpan;
+    /** Whether this symbol is exported from its module. */
+    isExported: boolean;
+    /** For methods: distinguishes `'method'`, `'getter'`, `'setter'`, or `'constructor'`. */
+    methodKind?: 'method' | 'getter' | 'setter' | 'constructor';
+    /** Function/method parameters. Present for functions, methods, and constructors. */
+    parameters?: Parameter[];
+    /** Return type annotation as source text. */
+    returnType?: string;
+    /** Generic type parameter names (e.g. `['T', 'U extends Foo']`). */
+    typeParameters?: string[];
+    /** Declaration modifiers (e.g. `async`, `static`, `readonly`). */
+    modifiers: Modifier[];
+    /** Heritage clauses (`extends` / `implements`). Present for classes and interfaces. */
+    heritage?: Heritage[];
+    /** Decorators applied to this symbol. */
+    decorators?: Decorator[];
+    /** Nested members (class fields, methods, interface properties, enum members). */
+    members?: ExtractedSymbol[];
+    /** Parsed JSDoc comment associated with this symbol. */
+    jsDoc?: JsDocBlock;
+}
+/**
+ * A dot-separated qualified name (e.g. `a.b.c`).
+ */
+export interface QualifiedName {
+    /** Leftmost identifier (e.g. `'a'` in `'a.b.c'`). */
+    root: string;
+    /** Subsequent parts (e.g. `['b', 'c']`). */
+    parts: string[];
+    /** Full joined string (e.g. `'a.b.c'`). */
+    full: string;
+}
+/**
+ * An import reference resolved from an import statement.
+ */
+export interface ImportReference {
+    /** Resolved absolute path of the imported module. */
+    path: string;
+    /** The imported name: `'default'` for default imports, `'*'` for namespace, or the named identifier. */
+    importedName: string;
+}
+/**
+ * A relationship between two symbols/files extracted from source code.
+ *
+ * - `'imports'` — file A imports from file B
+ * - `'calls'` — symbol in file A calls a symbol in file B
+ * - `'extends'` — class/interface in file A extends one in file B
+ * - `'implements'` — class in file A implements an interface in file B
+ */
+export interface CodeRelation {
+    /** The kind of relationship. */
+    type: 'imports' | 'calls' | 'extends' | 'implements';
+    /** File path where the relationship originates. */
+    srcFilePath: string;
+    /** Source symbol name, or `null` for module-level relationships. */
+    srcSymbolName: string | null;
+    /** File path of the target. */
+    dstFilePath: string;
+    /** Target symbol name, or `null` for module-level imports. */
+    dstSymbolName: string | null;
+    /** Optional JSON-encoded metadata about the relation. */
+    metaJson?: string;
+}
+export type { SourcePosition, SourceSpan };

package/dist/src/gildash.d.ts

@@ -0,0 +1,284 @@
+import type { ParsedFile } from './parser/types';
+import { parseSource as defaultParseSource } from './parser/parse-source';
+import { ParseCache } from './parser/parse-cache';
+import type { ExtractedSymbol } from './extractor/types';
+import { extractSymbols as defaultExtractSymbols } from './extractor/symbol-extractor';
+import { extractRelations as defaultExtractRelations } from './extractor/relation-extractor';
+import type { CodeRelation } from './extractor/types';
+import { DbConnection } from './store/connection';
+import { FileRepository } 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 { 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';
+/**
+ * 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;
+}
+/**
+ * Options for creating a {@link Gildash} instance via {@link Gildash.open}.
+ *
+ * @example
+ * ```ts
+ * const ledger = await Gildash.open({
+ *   projectRoot: '/absolute/path/to/project',
+ *   extensions: ['.ts', '.tsx'],
+ *   ignorePatterns: ['vendor'],
+ * });
+ * ```
+ */
+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;
+}
+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'>;
+        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;
+    loadTsconfigPathsFn?: typeof loadTsconfigPaths;
+}
+/**
+ * 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.
+ *
+ * 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';
+ *
+ * const ledger = await Gildash.open({ projectRoot: '/my/project' });
+ * const symbols = ledger.searchSymbols({ text: 'handle', kind: 'function' });
+ * 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 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 logger;
+    private readonly defaultProject;
+    private readonly role;
+    private timer;
+    private signalHandlers;
+    private closed;
+    private tsconfigPaths;
+    private boundaries;
+    private readonly onIndexedCallbacks;
+    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.
+     * @throws {Error} If `projectRoot` is not absolute or does not exist.
+     *
+     * @example
+     * ```ts
+     * const ledger = await Gildash.open({
+     *   projectRoot: '/home/user/my-app',
+     *   extensions: ['.ts', '.tsx'],
+     * });
+     * ```
+     */
+    static open(options: GildashOptions & GildashInternalOptions): Promise<Gildash>;
+    /**
+     * 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).
+     *
+     * @throws {AggregateError} If one or more sub-systems fail during shutdown.
+     */
+    close(): Promise<void>;
+    /**
+     * 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.
+     *
+     * @param filePath - File path used as the cache key and for diagnostics.
+     * @param sourceText - Raw TypeScript source code.
+     * @returns The parsed file representation.
+     * @throws {Error} If the instance is closed.
+     */
+    parseSource(filePath: string, sourceText: string): ParsedFile;
+    /**
+     * Extract all symbol declarations from a previously parsed file.
+     *
+     * @param parsed - A {@link ParsedFile} obtained from {@link parseSource}.
+     * @returns An array of {@link ExtractedSymbol} entries.
+     * @throws {Error} If the instance is closed.
+     */
+    extractSymbols(parsed: ParsedFile): ExtractedSymbol[];
+    /**
+     * Extract inter-file relationships (imports, calls, extends, implements)
+     * from a previously parsed file.
+     *
+     * @param parsed - A {@link ParsedFile} obtained from {@link parseSource}.
+     * @returns An array of {@link CodeRelation} entries.
+     * @throws {Error} If the instance is closed.
+     */
+    extractRelations(parsed: ParsedFile): CodeRelation[];
+    /**
+     * Trigger a full re-index of all tracked files.
+     *
+     * Only available to the instance that holds the *owner* role.
+     *
+     * @returns The indexing result summary.
+     * @throws {Error} If the instance is closed or is a reader.
+     */
+    reindex(): Promise<IndexResult>;
+    /**
+     * 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 Counts grouped by symbol kind.
+     * @throws {Error} If the instance is closed.
+     */
+    getStats(project?: string): SymbolStats;
+    /**
+     * Search indexed symbols by name, kind, file path, or export status.
+     *
+     * @param query - Search filters. All fields are optional; omitted fields match everything.
+     * @returns Matching {@link SymbolSearchResult} entries.
+     * @throws {Error} If the instance is closed.
+     *
+     * @example
+     * ```ts
+     * const fns = ledger.searchSymbols({ kind: 'function', isExported: true });
+     * ```
+     */
+    searchSymbols(query: SymbolSearchQuery): SymbolSearchResult[];
+    /**
+     * Search indexed code relationships (imports, calls, extends, implements).
+     *
+     * @param query - Search filters. All fields are optional.
+     * @returns Matching {@link CodeRelation} entries.
+     * @throws {Error} If the instance is closed.
+     */
+    searchRelations(query: RelationSearchQuery): CodeRelation[];
+    /**
+     * 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 Absolute paths of imported files.
+     * @throws {Error} If the instance is closed.
+     */
+    getDependencies(filePath: string, project?: string, limit?: number): string[];
+    /**
+     * 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 Absolute paths of files that import the target.
+     * @throws {Error} If the instance is closed.
+     */
+    getDependents(filePath: string, project?: string, limit?: number): string[];
+    /**
+     * Compute the full set of files transitively affected by changes.
+     *
+     * Builds a dependency graph and walks all reverse edges from each changed file.
+     *
+     * @param changedFiles - Absolute paths of files that changed.
+     * @param project - Project name. Defaults to the primary project.
+     * @returns Paths of all transitively-dependent files (excludes the changed files themselves).
+     * @throws {Error} If the instance is closed.
+     */
+    getAffected(changedFiles: string[], project?: string): Promise<string[]>;
+    /**
+     * Check whether the import graph contains a circular dependency.
+     *
+     * @param project - Project name. Defaults to the primary project.
+     * @returns `true` if at least one cycle exists.
+     * @throws {Error} If the instance is closed.
+     */
+    hasCycle(project?: string): Promise<boolean>;
+}
+export {};

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+export { Gildash } from "./gildash";
+export type { GildashOptions, Logger } from "./gildash";
+export { GildashError, WatcherError, ParseError, ExtractError, IndexError, StoreError, SearchError, } from "./errors";
+export { symbolSearch } from "./search/symbol-search";
+export type { SymbolSearchQuery, SymbolSearchResult } from "./search/symbol-search";
+export { relationSearch } from "./search/relation-search";
+export type { RelationSearchQuery } from "./search/relation-search";
+export { DependencyGraph } from "./search/dependency-graph";

package/dist/src/indexer/file-indexer.d.ts

@@ -0,0 +1,27 @@
+export interface FileChangeRecord {
+    filePath: string;
+    contentHash: string;
+    mtimeMs: number;
+    size: number;
+}
+export interface DetectChangesResult {
+    changed: FileChangeRecord[];
+    unchanged: FileChangeRecord[];
+    deleted: string[];
+}
+interface FileRepoPart {
+    getFilesMap(): Map<string, {
+        filePath: string;
+        mtimeMs: number;
+        size: number;
+        contentHash: string;
+    }>;
+}
+export interface DetectChangesOptions {
+    projectRoot: string;
+    extensions: string[];
+    ignorePatterns: string[];
+    fileRepo: FileRepoPart;
+}
+export declare function detectChanges(opts: DetectChangesOptions): Promise<DetectChangesResult>;
+export {};

package/dist/src/indexer/index-coordinator.d.ts

@@ -0,0 +1,80 @@
+import type { FileChangeEvent } from '../watcher/types';
+import type { ProjectBoundary } from '../common/project-discovery';
+import { discoverProjects } from '../common/project-discovery';
+import type { TsconfigPaths } from '../common/tsconfig-resolver';
+import { parseSource } from '../parser/parse-source';
+import type { DbConnection } from '../store/connection';
+import type { FileRecord } from '../store/repositories/file.repository';
+import type { SymbolRecord } from '../store/repositories/symbol.repository';
+import type { RelationRecord } from '../store/repositories/relation.repository';
+import type { Logger } from '../gildash';
+export declare const WATCHER_DEBOUNCE_MS = 100;
+export interface IndexResult {
+    indexedFiles: number;
+    removedFiles: number;
+    totalSymbols: number;
+    totalRelations: number;
+    durationMs: number;
+    changedFiles: string[];
+    deletedFiles: string[];
+    failedFiles: string[];
+}
+export interface IndexCoordinatorOptions {
+    projectRoot: string;
+    boundaries: ProjectBoundary[];
+    extensions: string[];
+    ignorePatterns: string[];
+    dbConnection: {
+        transaction<T>(fn: (tx: DbConnection) => T): T;
+    };
+    parseCache: {
+        set(key: string, value: unknown): void;
+        get(key: string): unknown;
+        invalidate(key: string): void;
+    };
+    fileRepo: {
+        getFilesMap(project: string): Map<string, FileRecord>;
+        getAllFiles(project: string): FileRecord[];
+        upsertFile(record: FileRecord): void;
+        deleteFile(project: string, filePath: string): void;
+    };
+    symbolRepo: {
+        replaceFileSymbols(project: string, filePath: string, contentHash: string, symbols: ReadonlyArray<Partial<SymbolRecord>>): void;
+        getFileSymbols(project: string, filePath: string): SymbolRecord[];
+        getByFingerprint(project: string, fingerprint: string): SymbolRecord[];
+        deleteFileSymbols(project: string, filePath: string): void;
+    };
+    relationRepo: {
+        replaceFileRelations(project: string, filePath: string, relations: ReadonlyArray<Partial<RelationRecord>>): void;
+        retargetRelations(project: string, oldFile: string, oldSymbol: string | null, newFile: string, newSymbol: string | null): void;
+        deleteFileRelations(project: string, filePath: string): void;
+    };
+    parseSourceFn?: typeof parseSource;
+    discoverProjectsFn?: typeof discoverProjects;
+    logger?: Logger;
+}
+export declare class IndexCoordinator {
+    private readonly opts;
+    private readonly logger;
+    private readonly callbacks;
+    private indexingLock;
+    private pendingEvents;
+    private debounceTimer;
+    private currentIndexing;
+    private pendingFullIndex;
+    private pendingFullIndexWaiters;
+    private tsconfigPathsRaw;
+    private boundariesRefresh;
+    constructor(opts: IndexCoordinatorOptions);
+    get tsconfigPaths(): Promise<TsconfigPaths | null>;
+    fullIndex(): Promise<IndexResult>;
+    incrementalIndex(events?: FileChangeEvent[]): Promise<IndexResult>;
+    onIndexed(cb: (result: IndexResult) => void): () => void;
+    handleWatcherEvent(event: FileChangeEvent): void;
+    shutdown(): Promise<void>;
+    private startIndex;
+    private doIndex;
+    private processFile;
+    private fireCallbacks;
+    private flushPending;
+}

package/dist/src/indexer/index.d.ts

@@ -0,0 +1,8 @@
+export { detectChanges } from './file-indexer';
+export type { DetectChangesOptions, DetectChangesResult, FileChangeRecord } from './file-indexer';
+export { indexFileSymbols } from './symbol-indexer';
+export type { IndexFileSymbolsOptions, SymbolDbRow } from './symbol-indexer';
+export { indexFileRelations } from './relation-indexer';
+export type { IndexFileRelationsOptions, RelationDbRow } from './relation-indexer';
+export { IndexCoordinator, WATCHER_DEBOUNCE_MS } from './index-coordinator';
+export type { IndexCoordinatorOptions, IndexResult } from './index-coordinator';

package/dist/src/indexer/relation-indexer.d.ts

@@ -0,0 +1,24 @@
+import type { Program } from 'oxc-parser';
+import type { TsconfigPaths } from '../common/tsconfig-resolver';
+export interface RelationDbRow {
+    project: string;
+    type: string;
+    srcFilePath: string;
+    srcSymbolName: string | null;
+    dstFilePath: string;
+    dstSymbolName: string | null;
+    metaJson: string | null;
+}
+interface RelationRepoPart {
+    replaceFileRelations(project: string, filePath: string, relations: RelationDbRow[]): void;
+}
+export interface IndexFileRelationsOptions {
+    ast: Program;
+    project: string;
+    filePath: string;
+    relationRepo: RelationRepoPart;
+    projectRoot: string;
+    tsconfigPaths?: TsconfigPaths;
+}
+export declare function indexFileRelations(opts: IndexFileRelationsOptions): number;
+export {};

package/dist/src/indexer/symbol-indexer.d.ts

@@ -0,0 +1,29 @@
+import type { ParsedFile } from '../parser/types';
+export interface SymbolDbRow {
+    project: string;
+    filePath: string;
+    kind: string;
+    name: string;
+    startLine: number;
+    startColumn: number;
+    endLine: number;
+    endColumn: number;
+    isExported: number;
+    signature: string | null;
+    fingerprint: string | null;
+    detailJson: string | null;
+    contentHash: string;
+    indexedAt: string;
+}
+interface SymbolRepoPart {
+    replaceFileSymbols(project: string, filePath: string, contentHash: string, symbols: SymbolDbRow[]): void;
+}
+export interface IndexFileSymbolsOptions {
+    parsed: ParsedFile;
+    project: string;
+    filePath: string;
+    contentHash: string;
+    symbolRepo: SymbolRepoPart;
+}
+export declare function indexFileSymbols(opts: IndexFileSymbolsOptions): void;
+export {};

package/dist/src/parser/ast-utils.d.ts

@@ -0,0 +1,10 @@
+import type { QualifiedName } from '../extractor/types';
+export declare function isNode(value: unknown): value is Record<string, unknown>;
+export declare function isNodeArray(value: unknown): value is ReadonlyArray<unknown>;
+export declare function visit(node: unknown, callback: (node: Record<string, unknown>) => void): void;
+export declare function collectNodes(root: unknown, predicate: (node: Record<string, unknown>) => boolean): Record<string, unknown>[];
+export declare function getNodeHeader(node: Record<string, unknown>, parent?: Record<string, unknown> | null): string;
+export declare function isFunctionNode(node: Record<string, unknown>): boolean;
+export declare function getNodeName(node: unknown): string | null;
+export declare function getStringLiteralValue(node: unknown): string | null;
+export declare function getQualifiedName(expr: unknown): QualifiedName | null;

package/dist/src/parser/index.d.ts

@@ -0,0 +1,6 @@
+export { parseSource } from './parse-source';
+export { ParseCache } from './parse-cache';
+export { buildLineOffsets, getLineColumn, } from './source-position';
+export { isNode, isNodeArray, visit, collectNodes, getNodeHeader, isFunctionNode, getNodeName, getStringLiteralValue, getQualifiedName, } from './ast-utils';
+export { parseJsDoc } from './jsdoc-parser';
+export type { ParsedFile, SourcePosition, SourceSpan } from './types';

package/dist/src/parser/jsdoc-parser.d.ts

@@ -0,0 +1,2 @@
+import type { JsDocBlock } from '../extractor/types';
+export declare function parseJsDoc(commentText: string): JsDocBlock;

package/dist/src/parser/parse-cache.d.ts

@@ -0,0 +1,10 @@
+import type { ParsedFile } from './types';
+export declare class ParseCache {
+    private readonly lru;
+    constructor(capacity?: number);
+    get(filePath: string): ParsedFile | undefined;
+    set(filePath: string, parsed: ParsedFile): void;
+    invalidate(filePath: string): void;
+    invalidateAll(): void;
+    size(): number;
+}

package/dist/src/parser/parse-source.d.ts

@@ -0,0 +1,3 @@
+import { parseSync as defaultParseSync } from 'oxc-parser';
+import type { ParsedFile } from './types';
+export declare function parseSource(filePath: string, sourceText: string, parseSyncFn?: typeof defaultParseSync): ParsedFile;

package/dist/src/parser/source-position.d.ts

@@ -0,0 +1,3 @@
+import type { SourcePosition } from './types';
+export declare function buildLineOffsets(sourceText: string): number[];
+export declare function getLineColumn(offsets: number[], offset: number): SourcePosition;