@zipbul/gildash 0.5.0 → 0.6.0

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

@@ -0,0 +1,92 @@
+import { type Result } from '@zipbul/result';
+import type { ParsedFile } from '../parser/types';
+import type { ParserOptions } from 'oxc-parser';
+import type { ExtractedSymbol, CodeRelation } from '../extractor/types';
+import type { IndexResult } from '../indexer/index-coordinator';
+import type { ProjectBoundary } from '../common/project-discovery';
+import type { SymbolSearchQuery, SymbolSearchResult } from '../search/symbol-search';
+import type { RelationSearchQuery } from '../search/relation-search';
+import type { SymbolStats } from '../store/repositories/symbol.repository';
+import type { FileRecord } from '../store/repositories/file.repository';
+import type { PatternMatch } from '../search/pattern-search';
+import type { GildashError } from '../errors';
+import type { ResolvedType, SemanticReference, Implementation, SemanticModuleInterface } from '../semantic/types';
+import type { GildashContext } from './context';
+import type { GildashOptions, SymbolDiff, ModuleInterface, HeritageNode, FullSymbol, FileStats, FanMetrics, ResolvedSymbol } from './types';
+import type { GildashInternalOptions } from './lifecycle';
+export type { Logger, GildashOptions, SymbolDiff, ModuleInterface, HeritageNode, FullSymbol, FileStats, FanMetrics, ResolvedSymbol, } from './types';
+export type { GildashInternalOptions } from './lifecycle';
+/**
+ * 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.
+ */
+export declare class Gildash {
+    /** Internal state — exposed for advanced testing only. */
+    readonly _ctx: GildashContext;
+    /** Absolute path to the indexed project root. */
+    get projectRoot(): string;
+    /** Current watcher role: `'owner'` (can reindex) or `'reader'` (read-only). */
+    get role(): 'owner' | 'reader';
+    /** Discovered project boundaries within the project root. */
+    get projects(): ProjectBoundary[];
+    private constructor();
+    /**
+     * Create and initialise a new `Gildash` instance.
+     */
+    static open(options: GildashOptions & GildashInternalOptions): Promise<Result<Gildash, GildashError>>;
+    /** Shut down the instance and release all resources. */
+    close(opts?: {
+        cleanup?: boolean;
+    }): Promise<Result<void, GildashError>>;
+    parseSource(filePath: string, sourceText: string, options?: ParserOptions): Result<ParsedFile, GildashError>;
+    batchParse(filePaths: string[], options?: ParserOptions): Promise<Result<Map<string, ParsedFile>, GildashError>>;
+    getParsedAst(filePath: string): ParsedFile | undefined;
+    extractSymbols(parsed: ParsedFile): Result<ExtractedSymbol[], GildashError>;
+    extractRelations(parsed: ParsedFile): Result<CodeRelation[], GildashError>;
+    getStats(project?: string): Result<SymbolStats, GildashError>;
+    searchSymbols(query: SymbolSearchQuery): Result<SymbolSearchResult[], GildashError>;
+    searchRelations(query: RelationSearchQuery): Result<CodeRelation[], GildashError>;
+    searchAllSymbols(query: Omit<SymbolSearchQuery, 'project'> & {
+        project?: string;
+    }): Result<SymbolSearchResult[], GildashError>;
+    searchAllRelations(query: RelationSearchQuery): Result<CodeRelation[], GildashError>;
+    listIndexedFiles(project?: string): Result<FileRecord[], GildashError>;
+    getInternalRelations(filePath: string, project?: string): Result<CodeRelation[], GildashError>;
+    getFullSymbol(symbolName: string, filePath: string, project?: string): Result<FullSymbol, GildashError>;
+    getFileStats(filePath: string, project?: string): Result<FileStats, GildashError>;
+    getFileInfo(filePath: string, project?: string): Result<FileRecord | null, GildashError>;
+    getSymbolsByFile(filePath: string, project?: string): Result<SymbolSearchResult[], GildashError>;
+    getModuleInterface(filePath: string, project?: string): Result<ModuleInterface, GildashError>;
+    getDependencies(filePath: string, project?: string, limit?: number): Result<string[], GildashError>;
+    getDependents(filePath: string, project?: string, limit?: number): Result<string[], GildashError>;
+    getAffected(changedFiles: string[], project?: string): Promise<Result<string[], GildashError>>;
+    hasCycle(project?: string): Promise<Result<boolean, GildashError>>;
+    getImportGraph(project?: string): Promise<Result<Map<string, string[]>, GildashError>>;
+    getTransitiveDependencies(filePath: string, project?: string): Promise<Result<string[], GildashError>>;
+    getCyclePaths(project?: string, options?: {
+        maxCycles?: number;
+    }): Promise<Result<string[][], GildashError>>;
+    getFanMetrics(filePath: string, project?: string): Promise<Result<FanMetrics, GildashError>>;
+    getResolvedType(symbolName: string, filePath: string, project?: string): Result<ResolvedType | null, GildashError>;
+    getSemanticReferences(symbolName: string, filePath: string, project?: string): Result<SemanticReference[], GildashError>;
+    getImplementations(symbolName: string, filePath: string, project?: string): Result<Implementation[], GildashError>;
+    getSemanticModuleInterface(filePath: string): Result<SemanticModuleInterface, GildashError>;
+    diffSymbols(before: SymbolSearchResult[], after: SymbolSearchResult[]): SymbolDiff;
+    onIndexed(callback: (result: IndexResult) => void): () => void;
+    reindex(): Promise<Result<IndexResult, GildashError>>;
+    resolveSymbol(symbolName: string, filePath: string, project?: string): Result<ResolvedSymbol, GildashError>;
+    findPattern(pattern: string, opts?: {
+        filePaths?: string[];
+        project?: string;
+    }): Promise<Result<PatternMatch[], GildashError>>;
+    getHeritageChain(symbolName: string, filePath: string, project?: string): Promise<Result<HeritageNode, GildashError>>;
+}

package/dist/src/gildash/lifecycle.d.ts

@@ -0,0 +1,62 @@
+import { type Result } from '@zipbul/result';
+import { FileRepository } from '../store/repositories/file.repository';
+import { SymbolRepository } from '../store/repositories/symbol.repository';
+import { RelationRepository } from '../store/repositories/relation.repository';
+import { acquireWatcherRole, releaseWatcherRole, updateHeartbeat } from '../watcher/ownership';
+import { discoverProjects } from '../common/project-discovery';
+import { loadTsconfigPaths } from '../common/tsconfig-resolver';
+import { ParseCache } from '../parser/parse-cache';
+import { parseSource as defaultParseSource } from '../parser/parse-source';
+import { extractSymbols as defaultExtractSymbols } from '../extractor/symbol-extractor';
+import { extractRelations as defaultExtractRelations } from '../extractor/relation-extractor';
+import { symbolSearch as defaultSymbolSearch } from '../search/symbol-search';
+import { relationSearch as defaultRelationSearch } from '../search/relation-search';
+import type { PatternMatch } from '../search/pattern-search';
+import { SemanticLayer } from '../semantic/index';
+import type { GildashError } from '../errors';
+import type { GildashContext, CoordinatorLike, WatcherLike, DbStore } from './context';
+import type { GildashOptions } from './types';
+export declare const HEARTBEAT_INTERVAL_MS = 30000;
+export declare const HEALTHCHECK_INTERVAL_MS = 60000;
+export declare const MAX_HEALTHCHECK_RETRIES = 10;
+export interface GildashInternalOptions {
+    existsSyncFn?: (p: string) => boolean;
+    dbConnectionFactory?: () => DbStore;
+    watcherFactory?: () => WatcherLike;
+    coordinatorFactory?: () => CoordinatorLike;
+    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>;
+    semanticLayerFactory?: (tsconfigPath: string) => Result<SemanticLayer, GildashError>;
+}
+/** Create coordinator + watcher, start watcher, heartbeat timer, run fullIndex. */
+export declare function setupOwnerInfrastructure(ctx: GildashContext, opts: {
+    isWatchMode: boolean;
+}): Promise<void>;
+/** Register SIGTERM / SIGINT / beforeExit handlers. */
+export declare function registerSignalHandlers(ctx: GildashContext, closeFn: () => Promise<Result<void, GildashError> | undefined>): void;
+/** Initialize a GildashContext (replaces the old `Gildash.open()` body). */
+export declare function initializeContext(options: GildashOptions & GildashInternalOptions): Promise<Result<GildashContext, GildashError>>;
+/** Shut down the context and release all resources. */
+export declare function closeContext(ctx: GildashContext, opts?: {
+    cleanup?: boolean;
+}): Promise<Result<void, GildashError>>;

package/dist/src/gildash/misc-api.d.ts

@@ -0,0 +1,22 @@
+import { type Result } from '@zipbul/result';
+import type { SymbolSearchResult } from '../search/symbol-search';
+import type { IndexResult } from '../indexer/index-coordinator';
+import type { PatternMatch } from '../search/pattern-search';
+import type { GildashError } from '../errors';
+import type { GildashContext } from './context';
+import type { SymbolDiff, ResolvedSymbol, HeritageNode } from './types';
+/** Compare two snapshots of symbol search results and return a structured diff. */
+export declare function diffSymbols(before: SymbolSearchResult[], after: SymbolSearchResult[]): SymbolDiff;
+/** Register a callback that fires after each indexing run completes. */
+export declare function onIndexed(ctx: GildashContext, callback: (result: IndexResult) => void): () => void;
+/** Trigger a full re-index of all tracked files. */
+export declare function reindex(ctx: GildashContext): Promise<Result<IndexResult, GildashError>>;
+/** Resolve the original definition location of a symbol by following its re-export chain. */
+export declare function resolveSymbol(ctx: GildashContext, symbolName: string, filePath: string, project?: string): Result<ResolvedSymbol, GildashError>;
+/** Search for an AST structural pattern across indexed TypeScript files. */
+export declare function findPattern(ctx: GildashContext, pattern: string, opts?: {
+    filePaths?: string[];
+    project?: string;
+}): Promise<Result<PatternMatch[], GildashError>>;
+/** Recursively traverse extends/implements relations to build a heritage tree. */
+export declare function getHeritageChain(ctx: GildashContext, symbolName: string, filePath: string, project?: string): Promise<Result<HeritageNode, GildashError>>;

package/dist/src/gildash/parse-api.d.ts

@@ -0,0 +1,11 @@
+import { type Result } from '@zipbul/result';
+import type { ParsedFile } from '../parser/types';
+import type { ParserOptions } from 'oxc-parser';
+import type { GildashError } from '../errors';
+import type { GildashContext } from './context';
+/** Parse a TypeScript source string into an AST and cache the result. */
+export declare function parseSource(ctx: GildashContext, filePath: string, sourceText: string, options?: ParserOptions): Result<ParsedFile, GildashError>;
+/** Parse multiple files concurrently and return a map of results. */
+export declare function batchParse(ctx: GildashContext, filePaths: string[], options?: ParserOptions): Promise<Result<Map<string, ParsedFile>, GildashError>>;
+/** Retrieve a previously-parsed AST from the internal LRU cache. */
+export declare function getParsedAst(ctx: GildashContext, filePath: string): ParsedFile | undefined;

package/dist/src/gildash/query-api.d.ts

@@ -0,0 +1,35 @@
+import { type Result } from '@zipbul/result';
+import type { SymbolSearchQuery, SymbolSearchResult } from '../search/symbol-search';
+import type { RelationSearchQuery } from '../search/relation-search';
+import type { CodeRelation } from '../extractor/types';
+import type { FileRecord } from '../store/repositories/file.repository';
+import type { SymbolStats } from '../store/repositories/symbol.repository';
+import type { GildashError } from '../errors';
+import type { GildashContext } from './context';
+import type { FullSymbol, FileStats, ModuleInterface } from './types';
+/** Return aggregate symbol statistics for the given project. */
+export declare function getStats(ctx: GildashContext, project?: string): Result<SymbolStats, GildashError>;
+/** Search indexed symbols by name, kind, file path, or export status. */
+export declare function searchSymbols(ctx: GildashContext, query: SymbolSearchQuery): Result<SymbolSearchResult[], GildashError>;
+/** Search indexed code relationships (imports, calls, extends, implements). */
+export declare function searchRelations(ctx: GildashContext, query: RelationSearchQuery): Result<CodeRelation[], GildashError>;
+/** Search symbols across all projects (no project filter). */
+export declare function searchAllSymbols(ctx: GildashContext, query: Omit<SymbolSearchQuery, 'project'> & {
+    project?: string;
+}): Result<SymbolSearchResult[], GildashError>;
+/** Search relations across all projects (no project filter). */
+export declare function searchAllRelations(ctx: GildashContext, query: RelationSearchQuery): Result<CodeRelation[], GildashError>;
+/** List all files indexed for a given project. */
+export declare function listIndexedFiles(ctx: GildashContext, project?: string): Result<FileRecord[], GildashError>;
+/** Get all intra-file relations for a given file. */
+export declare function getInternalRelations(ctx: GildashContext, filePath: string, project?: string): Result<CodeRelation[], GildashError>;
+/** Retrieve full details for a named symbol in a specific file. */
+export declare function getFullSymbol(ctx: GildashContext, symbolName: string, filePath: string, project?: string): Result<FullSymbol, GildashError>;
+/** Retrieve statistics for an indexed file. */
+export declare function getFileStats(ctx: GildashContext, filePath: string, project?: string): Result<FileStats, GildashError>;
+/** Retrieve metadata for an indexed file. */
+export declare function getFileInfo(ctx: GildashContext, filePath: string, project?: string): Result<FileRecord | null, GildashError>;
+/** List all symbols declared in a specific file. */
+export declare function getSymbolsByFile(ctx: GildashContext, filePath: string, project?: string): Result<SymbolSearchResult[], GildashError>;
+/** Return the public interface of a module. */
+export declare function getModuleInterface(ctx: GildashContext, filePath: string, project?: string): Result<ModuleInterface, GildashError>;

package/dist/src/gildash/semantic-api.d.ts

@@ -0,0 +1,22 @@
+import { type Result } from '@zipbul/result';
+import type { SymbolSearchResult } from '../search/symbol-search';
+import type { GildashError } from '../errors';
+import type { ResolvedType, SemanticReference, Implementation, SemanticModuleInterface } from '../semantic/types';
+import type { GildashContext } from './context';
+/**
+ * Look up a symbol's position for semantic queries.
+ * Returns `null` when the symbol is not indexed or position cannot be resolved.
+ */
+export declare function resolveSymbolPosition(ctx: GildashContext, symbolName: string, filePath: string, project?: string): {
+    sym: SymbolSearchResult;
+    position: number;
+    absPath: string;
+} | null;
+/** Retrieve the resolved type of a symbol using the Semantic Layer. */
+export declare function getResolvedType(ctx: GildashContext, symbolName: string, filePath: string, project?: string): Result<ResolvedType | null, GildashError>;
+/** Find all semantic references to a symbol. */
+export declare function getSemanticReferences(ctx: GildashContext, symbolName: string, filePath: string, project?: string): Result<SemanticReference[], GildashError>;
+/** Find implementations of an interface/abstract class. */
+export declare function getImplementations(ctx: GildashContext, symbolName: string, filePath: string, project?: string): Result<Implementation[], GildashError>;
+/** Retrieve the semantic module interface — exported symbols with resolved types. */
+export declare function getSemanticModuleInterface(ctx: GildashContext, filePath: string): Result<SemanticModuleInterface, GildashError>;

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

@@ -0,0 +1,160 @@
+import type { SymbolSearchResult } from '../search/symbol-search';
+import type { SymbolKind } from '../extractor/types';
+import type { ResolvedType } from '../semantic/types';
+/**
+ * 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 {
+    /** Class/interface members (methods, properties, constructors, accessors). */
+    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;
+    /** Resolved type from the Semantic Layer (available when `semantic: true`). */
+    resolvedType?: ResolvedType;
+}
+/**
+ * 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}.
+ */
+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;
+    /**
+     * Enable the Semantic Layer (tsc-based type analysis).
+     * When `true`, creates a `SemanticLayer` backed by the TypeScript compiler.
+     * Requires a `tsconfig.json` in `projectRoot`.
+     *
+     * @default false
+     */
+    semantic?: boolean;
+}

package/dist/src/index.d.ts

@@ -5,7 +5,7 @@ export type { GildashError, GildashErrorType } 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 type { RelationSearchQuery, StoredCodeRelation } from "./search/relation-search";
 export { DependencyGraph } from "./search/dependency-graph";
 export { patternSearch } from "./search/pattern-search";
 export type { PatternMatch, PatternSearchOptions } from "./search/pattern-search";
@@ -16,3 +16,4 @@ export type { SymbolStats } from "./store/repositories/symbol.repository";
 export type { WatcherRole } from "./watcher/types";
 export type { ParsedFile } from "./parser/types";
 export type { FileRecord } from "./store/repositories/file.repository";
+export type { ResolvedType, SemanticReference, Implementation, SemanticModuleInterface } from "./semantic/types";

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

@@ -80,7 +80,14 @@ export interface IndexCoordinatorOptions {
     };
     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;
+        retargetRelations(opts: {
+            dstProject: string;
+            oldFile: string;
+            oldSymbol: string | null;
+            newFile: string;
+            newSymbol: string | null;
+            newDstProject?: string;
+        }): void;
         deleteFileRelations(project: string, filePath: string): void;
     };
     parseSourceFn?: typeof parseSource;
@@ -108,7 +115,6 @@ export declare class IndexCoordinator {
     shutdown(): Promise<void>;
     private startIndex;
     private doIndex;
-    private processFile;
     private fireCallbacks;
     private flushPending;
 }

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

@@ -1,10 +1,12 @@
 import type { Program } from 'oxc-parser';
+import type { ProjectBoundary } from '../common/project-discovery';
 import type { TsconfigPaths } from '../common/tsconfig-resolver';
 export interface RelationDbRow {
     project: string;
     type: string;
     srcFilePath: string;
     srcSymbolName: string | null;
+    dstProject: string;
     dstFilePath: string;
     dstSymbolName: string | null;
     metaJson: string | null;
@@ -19,6 +21,10 @@ export interface IndexFileRelationsOptions {
     relationRepo: RelationRepoPart;
     projectRoot: string;
     tsconfigPaths?: TsconfigPaths;
+    /** 인덱싱된 파일 경로 Set. `${project}::${filePath}` 형식. */
+    knownFiles?: Set<string>;
+    /** 프로젝트 경계 목록 (dstProject 결정용) */
+    boundaries?: ProjectBoundary[];
 }
 export declare function indexFileRelations(opts: IndexFileRelationsOptions): number;
 export {};

package/dist/src/search/dependency-graph.d.ts

@@ -24,6 +24,7 @@ export declare class DependencyGraph {
     constructor(options: {
         relationRepo: IDependencyGraphRepo;
         project: string;
+        additionalProjects?: string[];
     });
     /**
      * Populate the graph by reading all `imports` relations from the store.

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

@@ -1,5 +1,12 @@
 import type { CodeRelation } from '../extractor/types';
 import type { RelationRecord } from '../store/repositories/relation.repository';
+/**
+ * A {@link CodeRelation} enriched with the destination project identifier
+ * as stored in the relation index.
+ */
+export interface StoredCodeRelation extends CodeRelation {
+    dstProject: string;
+}
 /**
  * Filters for {@link relationSearch}.
  *
@@ -14,6 +21,8 @@ export interface RelationSearchQuery {
     dstFilePath?: string;
     /** Destination symbol name. */
     dstSymbolName?: string;
+    /** Destination project. */
+    dstProject?: string;
     /** Relationship type: `'imports'`, `'calls'`, `'extends'`, or `'implements'`. */
     type?: CodeRelation['type'];
     /** Limit results to this project. */
@@ -27,6 +36,7 @@ export interface IRelationRepo {
         srcSymbolName?: string;
         dstFilePath?: string;
         dstSymbolName?: string;
+        dstProject?: string;
         type?: string;
         project?: string;
         limit: number;
@@ -42,4 +52,4 @@ export declare function relationSearch(options: {
     relationRepo: IRelationRepo;
     project?: string;
     query: RelationSearchQuery;
-}): CodeRelation[];
+}): StoredCodeRelation[];

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

@@ -30,6 +30,11 @@ export interface SymbolSearchQuery {
      * Requires the `REGEXP` SQL function to be registered in the DB connection.
      */
     regex?: string;
+    /**
+     * Filter by the resolved (inferred) type text.
+     * Requires the semantic layer (`semantic: true`) to have populated this field.
+     */
+    resolvedType?: string;
 }
 /**
  * A single result returned by {@link symbolSearch}.
@@ -74,6 +79,7 @@ export interface ISymbolRepo {
         limit: number;
         decorator?: string;
         regex?: string;
+        resolvedType?: string;
     }): (SymbolRecord & {
         id: number;
     })[];

package/dist/src/semantic/ast-node-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared AST node utilities for the semantic layer.
+ */
+import ts from "typescript";
+/**
+ * `pos` 위치의 가장 작은(innermost) 노드를 반환한다.
+ * 범위 밖이면 `undefined`.
+ */
+export declare function findNodeAtPosition(sourceFile: ts.SourceFile, pos: number): ts.Node | undefined;

package/dist/src/semantic/implementation-finder.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ImplementationFinder — findImplementations + isTypeAssignableTo 기반 구현체 탐색.
+ *
+ * interface/abstract class의 구현체를 찾는다.
+ * - LanguageService.getImplementationAtPosition: 명시적 + 일부 구조적 구현체
+ * - TypeChecker.isTypeAssignableTo: 덕 타이핑 구현체 검증
+ *
+ * 명시적(`implements` 키워드) 구현과 구조적(duck-typing) 구현 모두 탐지한다.
+ */
+import type { Implementation } from "./types";
+import type { TscProgram } from "./tsc-program";
+export declare class ImplementationFinder {
+    #private;
+    constructor(program: TscProgram);
+    /**
+     * `filePath`의 `position` 위치 심볼에 대한 구현체를 찾는다.
+     *
+     * - 프로그램이 dispose되었거나 심볼을 찾을 수 없으면 빈 배열을 반환한다.
+     * - 명시적 `implements` + 구조적 타이핑(duck-typing) 구현체 모두 포함한다.
+     */
+    findAt(filePath: string, position: number): Implementation[];
+}

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

@@ -0,0 +1,68 @@
+/**
+ * SemanticLayer — tsc 기반 시맨틱 분석 계층.
+ *
+ * TscProgram + TypeCollector + SymbolGraph + ReferenceResolver + ImplementationFinder를
+ * 하나의 facade로 통합한다.
+ */
+import { type Result } from "@zipbul/result";
+import { type GildashError } from "../errors";
+import { type TscProgramOptions } from "./tsc-program";
+import { TypeCollector } from "./type-collector";
+import { SymbolGraph, type SymbolNode } from "./symbol-graph";
+import { ReferenceResolver } from "./reference-resolver";
+import { ImplementationFinder } from "./implementation-finder";
+import type { ResolvedType, SemanticReference, Implementation, SemanticModuleInterface } from "./types";
+export interface SemanticLayerOptions extends TscProgramOptions {
+    /** Override TypeCollector (for testing). */
+    typeCollector?: TypeCollector;
+    /** Override SymbolGraph (for testing). */
+    symbolGraph?: SymbolGraph;
+    /** Override ReferenceResolver (for testing). */
+    referenceResolver?: ReferenceResolver;
+    /** Override ImplementationFinder (for testing). */
+    implementationFinder?: ImplementationFinder;
+}
+export declare class SemanticLayer {
+    #private;
+    private constructor();
+    /**
+     * Create a SemanticLayer from a tsconfig.json path.
+     *
+     * Internally creates TscProgram and all sub-modules.
+     * DI overrides via `options` for testing.
+     */
+    static create(tsconfigPath: string, options?: SemanticLayerOptions): Result<SemanticLayer, GildashError>;
+    get isDisposed(): boolean;
+    collectTypeAt(filePath: string, position: number): ResolvedType | null;
+    collectFileTypes(filePath: string): Map<number, ResolvedType>;
+    findReferences(filePath: string, position: number): SemanticReference[];
+    findImplementations(filePath: string, position: number): Implementation[];
+    getSymbolNode(filePath: string, position: number): SymbolNode | null;
+    getModuleInterface(filePath: string): SemanticModuleInterface;
+    notifyFileChanged(filePath: string, content: string): void;
+    /**
+     * Remove a tracked file from the tsc program and invalidate its symbol graph entries.
+     *
+     * Call this when a file is deleted from disk so the LanguageService no longer
+     * reports stale references or type information for it.
+     *
+     * No-op if already disposed.
+     */
+    notifyFileDeleted(filePath: string): void;
+    /**
+     * Convert 1-based line + 0-based column to a byte offset using tsc SourceFile.
+     * Returns `null` when the file is not part of the program.
+     */
+    lineColumnToPosition(filePath: string, line: number, column: number): number | null;
+    /**
+     * Find the byte offset of a symbol **name** starting from its declaration position.
+     *
+     * `declarationPos` typically points to the `export` keyword (the declaration start
+     * stored in the DB), while the symbol name sits a few tokens ahead.
+     * Uses a simple text search to locate the first occurrence of `name` after `declarationPos`.
+     *
+     * Returns `null` when the file is not in the program or the name is not found.
+     */
+    findNamePosition(filePath: string, declarationPos: number, name: string): number | null;
+    dispose(): void;
+}