@zipbul/gildash 0.5.1 → 0.7.0

package/dist/src/semantic/symbol-graph.d.ts

@@ -0,0 +1,36 @@
+/**
+ * SymbolGraph — tsc Symbol API로 심볼의 계층(parent/members/exports)을 탐색하고
+ * LRU 캐시로 결과를 재사용한다.
+ */
+import type { TscProgram } from "./tsc-program";
+export interface SymbolNode {
+    /** 심볼 이름 (`ts.Symbol.getName()`) */
+    name: string;
+    /** 첫 번째 선언이 위치한 파일 경로 */
+    filePath: string;
+    /** 첫 번째 선언의 이름 식별자 `getStart()` 오프셋 */
+    position: number;
+    /** 컨테이너 심볼 (namespace·class·enum의 멤버인 경우) */
+    parent?: SymbolNode;
+    /** 클래스·인터페이스·enum의 멤버 심볼 목록 */
+    members?: SymbolNode[];
+    /** namespace의 export 심볼 목록 */
+    exports?: SymbolNode[];
+}
+export declare class SymbolGraph {
+    #private;
+    constructor(program: TscProgram, capacity?: number);
+    /**
+     * `filePath`의 `position` 위치 심볼을 `SymbolNode`로 반환한다.
+     * - 프로그램이 dispose되었거나 심볼을 찾을 수 없으면 `null`을 반환한다.
+     * - 결과는 LRU 캐시에 저장된다.
+     */
+    get(filePath: string, position: number): SymbolNode | null;
+    /**
+     * `filePath`에 해당하는 캐시 항목을 모두 제거한다.
+     * 파일 변경 시 호출하여 stale 결과를 무효화한다.
+     */
+    invalidate(filePath: string): void;
+    /** 캐시 전체를 초기화한다. */
+    clear(): void;
+}

package/dist/src/semantic/tsc-program.d.ts

@@ -0,0 +1,67 @@
+/**
+ * TscProgram — tsc Program/TypeChecker/LanguageService lifecycle manager.
+ *
+ * Wraps `ts.createLanguageService()` with a custom `LanguageServiceHost`
+ * that tracks file versions in-memory for incremental updates.
+ *
+ * All I/O is injected via the `TscProgramOptions` DI parameters so that
+ * unit tests can run without touching the filesystem.
+ */
+import ts from "typescript";
+import { type Result } from "@zipbul/result";
+import { type GildashError } from "../errors";
+/**
+ * Reads a file at `path` and returns its content, or `undefined` if missing.
+ */
+export type ReadConfigFileFn = (path: string) => string | undefined;
+/**
+ * Resolves content for files NOT tracked by the user project
+ * (e.g. TypeScript lib declarations on disk).
+ * Returns file content or `undefined` if not found.
+ */
+export type ResolveNonTrackedFileFn = (path: string) => string | undefined;
+export interface TscProgramOptions {
+    /** Reads tsconfig.json content. Injected for testability. */
+    readConfigFile?: ReadConfigFileFn;
+    /** Resolves non-tracked files (ts libs, node_modules). Injected for testability. */
+    resolveNonTrackedFile?: ResolveNonTrackedFileFn;
+}
+export declare class TscProgram {
+    #private;
+    /** @internal — exposed for unit test verification only. */
+    readonly __testing__: {
+        host: ts.LanguageServiceHost;
+    };
+    private constructor();
+    /**
+     * Create a TscProgram from a tsconfig.json path.
+     *
+     * Parses the config, creates a LanguageServiceHost, and initializes the LanguageService.
+     * Returns `Err<GildashError>` on config read/parse failure.
+     */
+    static create(tsconfigPath: string, options?: TscProgramOptions): Result<TscProgram, GildashError>;
+    get isDisposed(): boolean;
+    getProgram(): ts.Program;
+    getChecker(): ts.TypeChecker;
+    getLanguageService(): ts.LanguageService;
+    /**
+     * Notify that a file's content has changed (or a new file was added).
+     * Bumps the internal version so the LanguageService will re-evaluate on next query.
+     *
+     * No-op if already disposed.
+     */
+    notifyFileChanged(filePath: string, content: string): void;
+    /**
+     * Remove a tracked file from the LanguageService host.
+     * After removal the file will no longer appear in `getScriptFileNames()`
+     * and `getScriptSnapshot()` will return `undefined` for it.
+     *
+     * No-op if already disposed or the file was never tracked.
+     */
+    removeFile(filePath: string): void;
+    /**
+     * Dispose the LanguageService and release references.
+     * Idempotent — safe to call multiple times.
+     */
+    dispose(): void;
+}

package/dist/src/semantic/type-collector.d.ts

@@ -0,0 +1,27 @@
+/**
+ * TypeCollector — tsc TypeChecker 직접 호출로 심볼의 ResolvedType을 수집한다.
+ *
+ * TscProgram에서 Program/TypeChecker를 가져와 AST를 탐색하고
+ * 각 심볼 위치의 타입을 ResolvedType으로 변환한다.
+ */
+import type { ResolvedType } from "./types";
+import type { TscProgram } from "./tsc-program";
+export declare class TypeCollector {
+    private readonly program;
+    constructor(program: TscProgram);
+    /**
+     * `filePath`의 `position` 위치(0-based 문자 오프셋)에 있는 심볼의 타입을 수집한다.
+     *
+     * - 파일이 없거나 위치에 식별자가 없으면 `null` 반환
+     * - `TscProgram이` disposed 상태이면 throw (getProgram이 throw)
+     */
+    collectAt(filePath: string, position: number): ResolvedType | null;
+    /**
+     * `filePath`에서 모든 선언 이름 심볼의 타입을 수집한다.
+     *
+     * 반환 Map의 key = 선언 이름 식별자의 시작 위치(0-based).
+     * 파일이 없으면 빈 Map 반환.
+     * `TscProgram`이 disposed 상태이면 throw.
+     */
+    collectFile(filePath: string): Map<number, ResolvedType>;
+}

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

@@ -0,0 +1,103 @@
+/**
+ * Types for the gildash Semantic Layer (tsc-based).
+ *
+ * All types in this file are plain data shapes — no runtime logic.
+ * The Semantic Layer is opt-in via `Gildash.open({ semantic: true })`.
+ */
+/**
+ * The resolved type of a TypeScript symbol, as determined by the tsc TypeChecker.
+ *
+ * Captures the full structural description of a type including union/intersection
+ * decomposition and generic argument resolution.
+ */
+export interface ResolvedType {
+    /** Human-readable type string, e.g. `"string | undefined"`, `"Promise<number>"`. */
+    text: string;
+    /** Raw TypeScript `TypeFlags` bitmask. */
+    flags: number;
+    /** Whether this type is a union type (`A | B`). */
+    isUnion: boolean;
+    /** Whether this type is an intersection type (`A & B`). */
+    isIntersection: boolean;
+    /**
+     * Whether this type is a generic instantiation (has type arguments).
+     * `true` when the type was instantiated with concrete type arguments
+     * (e.g. `Promise<string>`), `false` for non-generic types or uninstantiated generics.
+     */
+    isGeneric: boolean;
+    /**
+     * Constituent types for union or intersection.
+     * Populated only when `isUnion` or `isIntersection` is `true`.
+     */
+    members?: ResolvedType[];
+    /**
+     * Resolved type arguments for generic instantiations.
+     * e.g. `Promise<string>` → `[{ text: "string", ... }]`
+     */
+    typeArguments?: ResolvedType[];
+}
+/**
+ * A single reference to a symbol, resolved via `LanguageService.findReferences`.
+ *
+ * Unlike text-based search, semantic references are based on symbol identity —
+ * renames, re-exports, and shadowed names are handled correctly.
+ */
+export interface SemanticReference {
+    /** Absolute path of the file containing the reference. */
+    filePath: string;
+    /** Zero-based character offset within the file. */
+    position: number;
+    /** One-based line number. */
+    line: number;
+    /** Zero-based column offset. */
+    column: number;
+    /** Whether this reference is the symbol's own declaration site. */
+    isDefinition: boolean;
+    /** Whether this reference is a write (assignment) rather than a read. */
+    isWrite: boolean;
+}
+/**
+ * A concrete implementation of an interface or abstract class,
+ * found via `LanguageService.getImplementationAtPosition` and
+ * `TypeChecker.isTypeAssignableTo`.
+ *
+ * Includes both explicit (`implements` keyword) and structural (duck-typing) implementations.
+ */
+export interface Implementation {
+    /** Absolute path of the file containing the implementation. */
+    filePath: string;
+    /** Name of the implementing symbol (class, function, or object literal). */
+    symbolName: string;
+    /** Zero-based character offset within the file. */
+    position: number;
+    /** Syntactic kind of the implementing construct. */
+    kind: 'class' | 'function' | 'object';
+    /** `true` if the `implements` keyword is explicitly present; `false` for duck-typing matches. */
+    isExplicit: boolean;
+}
+/**
+ * The semantic view of a module's public interface — exports augmented with resolved types.
+ *
+ * The syntax-layer extractor already captures export names and kinds.
+ * This type adds tsc-resolved type information for each export.
+ */
+export interface SemanticModuleInterface {
+    /** Absolute path of the module file. */
+    filePath: string;
+    /** Per-export type information. */
+    exports: SemanticExport[];
+}
+/**
+ * A single export entry within a {@link SemanticModuleInterface}.
+ */
+export interface SemanticExport {
+    /** Export name as it appears in the source. */
+    name: string;
+    /** Syntactic kind of the exported symbol. */
+    kind: string;
+    /**
+     * Resolved type of this export, or `null` if type resolution failed.
+     * `null` does not propagate as an error — the syntax-layer data remains intact.
+     */
+    resolvedType: ResolvedType | null;
+}

package/dist/src/store/repositories/relation.repository.d.ts

@@ -4,6 +4,7 @@ export interface RelationRecord {
     type: string;
     srcFilePath: string;
     srcSymbolName: string | null;
+    dstProject: string;
     dstFilePath: string;
     dstSymbolName: string | null;
     metaJson: string | null;
@@ -13,17 +14,28 @@ export declare class RelationRepository {
     constructor(db: DbConnection);
     replaceFileRelations(project: string, srcFilePath: string, rels: ReadonlyArray<Partial<RelationRecord>>): void;
     getOutgoing(project: string, srcFilePath: string, srcSymbolName?: string): RelationRecord[];
-    getIncoming(project: string, dstFilePath: string): RelationRecord[];
+    getIncoming(opts: {
+        dstProject: string;
+        dstFilePath: string;
+    }): RelationRecord[];
     getByType(project: string, type: string): RelationRecord[];
     deleteFileRelations(project: string, srcFilePath: string): void;
     searchRelations(opts: {
         srcFilePath?: string;
         srcSymbolName?: string;
+        dstProject?: string;
         dstFilePath?: string;
         dstSymbolName?: string;
         type?: string;
         project?: string;
         limit: number;
     }): RelationRecord[];
-    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;
 }

package/dist/src/store/repositories/symbol.repository.d.ts

@@ -14,6 +14,7 @@ export interface SymbolRecord {
     detailJson: string | null;
     contentHash: string;
     indexedAt: string;
+    resolvedType?: string | null;
 }
 export interface SearchOptions {
     kind?: string;
@@ -50,6 +51,7 @@ export declare class SymbolRepository {
         limit: number;
         decorator?: string;
         regex?: string;
+        resolvedType?: string;
     }): (SymbolRecord & {
         id: number;
     })[];

package/dist/src/store/schema.d.ts

@@ -409,6 +409,25 @@ export declare const symbols: import("drizzle-orm/sqlite-core").SQLiteTableWithC
         }, {}, {
             length: number | undefined;
         }>;
+        resolvedType: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "resolved_type";
+            tableName: "symbols";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
     };
     dialect: "sqlite";
 }>;
@@ -509,6 +528,25 @@ export declare const relations: import("drizzle-orm/sqlite-core").SQLiteTableWit
         }, {}, {
             length: number | undefined;
         }>;
+        dstProject: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "dst_project";
+            tableName: "relations";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
         dstFilePath: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "dst_file_path";
             tableName: "relations";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zipbul/gildash",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "TypeScript code indexing and dependency graph engine for Bun",
   "license": "MIT",
   "repository": {
@@ -44,6 +44,7 @@
   "dependencies": {
     "@ast-grep/napi": "^0.41.0",
     "@parcel/watcher": "^2.5.6",
+    "@zipbul/result": "^0.1.4",
     "comment-parser": "1.4.5",
     "drizzle-orm": "^0.45.1",
     "oxc-parser": "0.115.0"
@@ -55,10 +56,15 @@
     "@commitlint/config-conventional": "^20.4.2",
     "@types/bun": "latest",
     "drizzle-kit": "^0.31.9",
-    "husky": "^9.1.7"
+    "husky": "^9.1.7",
+    "typescript": "^5.8.0"
   },
   "peerDependencies": {
-    "@zipbul/result": "^0.0.3",
-    "oxc-parser": ">=0.114.0"
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
   }
 }