@zipbul/gildash 0.5.1 → 0.7.0

package/README.ko.md

@@ -32,9 +32,8 @@ gildash는 TypeScript 코드베이스를 로컬 SQLite 데이터베이스에 인
 - **심볼 레벨 diff** — `IndexResult`의 `changedSymbols`로 인덱싱 사이클 당 추가/수정/삭제된 심볼 추적
 - **멀티 프로세스 안전** — owner/reader 역할 분리로 단일 writer 보장
 - **스캔 전용 모드** — `watchMode: false`로 파일 워처 없이 1회성 인덱싱
-- **외부 패키지 인덱싱** — `node_modules`의 `.d.ts` 타입 선언 인덱싱
 - **tsconfig.json JSONC** — `tsconfig.json`의 주석(`//`, `/* */`)과 트레일링 콤마를 지원하는 경로 별칭 파싱
-
+- **시맨틱 레이어 (opt-in)** — tsc TypeChecker 통합으로 resolved type, 참조, 구현체, 모듈 인터페이스 분석
 <br>
 
 ## 📋 요구사항
@@ -50,7 +49,7 @@ gildash는 TypeScript 코드베이스를 로컬 SQLite 데이터베이스에 인
 bun add @zipbul/gildash
 ```
 
-> **피어 의존성** — [`@zipbul/result`](https://www.npmjs.com/package/@zipbul/result)가 필요합니다. 모든 public 메서드는 `Result<T, GildashError>`를 반환합니다.
+> **선택적 피어 의존성** — `typescript` (>=5.0.0)는 `semantic: true` 사용 시에만 필요합니다.
 
 <br>
 
@@ -58,7 +57,6 @@ bun add @zipbul/gildash
 
 ```ts
 import { Gildash } from '@zipbul/gildash';
-import { isErr } from '@zipbul/result';
 
 // 1. 열기 — 최초 실행 시 전체 .ts 파일 인덱싱, 이후 파일 변경 감시
 const ledger = await Gildash.open({
@@ -66,10 +64,8 @@ const ledger = await Gildash.open({
 });
 
 // 2. 검색 — 이름으로 심볼 찾기
-const result = ledger.searchSymbols({ text: 'UserService', kind: 'class' });
-if (!isErr(result)) {
-  result.forEach(s => console.log(`${s.name} → ${s.filePath}`));
-}
+const symbols = ledger.searchSymbols({ text: 'UserService', kind: 'class' });
+symbols.forEach(s => console.log(`${s.name} → ${s.filePath}`));
 
 // 3. 종료 — 리소스 해제
 await ledger.close();
@@ -202,16 +198,18 @@ await ledger.close({ cleanup: true });   // DB 파일까지 삭제
 
 ## ❌ 에러 처리
 
-모든 public 메서드는 [`@zipbul/result`](https://www.npmjs.com/package/@zipbul/result)의 `Result<T, GildashError>`를 반환합니다. `isErr()`로 에러를 분기합니다:
+public 메서드는 값을 직접 반환하고, 실패 시 `GildashError`를 throw합니다. `instanceof`로 분기합니다:
 
 ```ts
-import { isErr } from '@zipbul/result';
-
-const result = ledger.searchSymbols({ text: 'foo' });
-if (isErr(result)) {
-  console.error(result.data.type, result.data.message);
-} else {
-  console.log(`${result.length}개 심볼 발견`);
+import { Gildash, GildashError } from '@zipbul/gildash';
+
+try {
+  const symbols = ledger.searchSymbols({ text: 'foo' });
+  console.log(`${symbols.length}개 심볼 발견`);
+} catch (e) {
+  if (e instanceof GildashError) {
+    console.error(`[${e.type}] ${e.message}`);
+  }
 }
 ```
 
@@ -229,8 +227,11 @@ if (isErr(result)) {
 | `parseCacheCapacity` | `number` | `500` | LRU 파싱 캐시 최대 크기 |
 | `logger` | `Logger` | `console` | 커스텀 로거 (`{ error(...args): void }`) |
 | `watchMode` | `boolean` | `true` | `false`이면 파일 워처 비활성화 (스캔 전용 모드) |
+| `semantic` | `boolean` | `false` | tsc TypeChecker 기반 시맨틱 분석 활성화 |
 
-**반환**: `Promise<Gildash>` (`Result`로 래핑됨)
+**반환**: `Promise<Gildash>`. 실패 시 `GildashError`를 throw합니다.
+
+> **참고:** `semantic: true`는 프로젝트 루트에 `tsconfig.json`이 필요합니다. 없으면 `Gildash.open()`이 `GildashError`를 throw합니다.
 
 <br>
 
@@ -240,60 +241,73 @@ if (isErr(result)) {
 
 | 메서드 | 반환 타입 | 설명 |
 |--------|-----------|------|
-| `searchSymbols(query)` | `Result<SymbolSearchResult[]>` | FTS5 전문검색 + exact/regex/decorator 필터 |
-| `searchRelations(query)` | `Result<CodeRelation[]>` | 파일, 심볼, 관계 유형 필터 |
-| `searchAllSymbols(query)` | `Result<SymbolSearchResult[]>` | 전체 프로젝트 심볼 검색 |
-| `searchAllRelations(query)` | `Result<CodeRelation[]>` | 전체 프로젝트 관계 검색 |
-| `listIndexedFiles(project?)` | `Result<FileRecord[]>` | 인덱싱된 파일 목록 |
-| `getSymbolsByFile(filePath)` | `Result<SymbolSearchResult[]>` | 단일 파일의 모든 심볼 |
+| `searchSymbols(query)` | `SymbolSearchResult[]` | FTS5 전문검색 + exact/regex/decorator 필터 |
+| `searchRelations(query)` | `StoredCodeRelation[]` | 파일, 심볼, 관계 유형 필터 |
+| `searchAllSymbols(query)` | `SymbolSearchResult[]` | 전체 프로젝트 심볼 검색 |
+| `searchAllRelations(query)` | `StoredCodeRelation[]` | 전체 프로젝트 관계 검색 |
+| `listIndexedFiles(project?)` | `FileRecord[]` | 인덱싱된 파일 목록 |
+| `getSymbolsByFile(filePath)` | `SymbolSearchResult[]` | 단일 파일의 모든 심볼 |
 
 ### 의존성 그래프
 
 | 메서드 | 반환 타입 | 설명 |
 |--------|-----------|------|
-| `getDependencies(filePath)` | `Result<string[]>` | `filePath`가 import하는 파일 목록 |
-| `getDependents(filePath)` | `Result<string[]>` | `filePath`를 import하는 파일 목록 |
-| `getAffected(changedFiles)` | `Promise<Result<string[]>>` | 전이적 영향 범위 |
-| `hasCycle(project?)` | `Promise<Result<boolean>>` | 순환 의존성 감지 |
-| `getCyclePaths(project?, opts?)` | `Promise<Result<string[][]>>` | 모든 순환 경로 (Tarjan SCC + Johnson's). `opts.maxCycles`로 개수 제한 가능. |
-| `getImportGraph(project?)` | `Promise<Result<Map>>` | 전체 인접 리스트 |
-| `getTransitiveDependencies(filePath)` | `Promise<Result<string[]>>` | 전방 전이적 BFS |
+| `getDependencies(filePath)` | `string[]` | `filePath`가 import하는 파일 목록 |
+| `getDependents(filePath)` | `string[]` | `filePath`를 import하는 파일 목록 |
+| `getAffected(changedFiles)` | `Promise<string[]>` | 전이적 영향 범위 |
+| `hasCycle(project?)` | `Promise<boolean>` | 순환 의존성 감지 |
+| `getCyclePaths(project?, opts?)` | `Promise<string[][]>` | 모든 순환 경로 (Tarjan SCC + Johnson's). `opts.maxCycles`로 개수 제한 가능. |
+| `getImportGraph(project?)` | `Promise<Map>` | 전체 인접 리스트 |
+| `getTransitiveDependencies(filePath)` | `Promise<string[]>` | 전방 전이적 BFS |
 
 ### 분석
 
 | 메서드 | 반환 타입 | 설명 |
 |--------|-----------|------|
-| `getFullSymbol(name, filePath)` | `Result<FullSymbol>` | 멤버, jsDoc, 데코레이터, 타입 정보 |
-| `getFileStats(filePath)` | `Result<FileStats>` | 라인 수, 심볼 수, 파일 크기 |
-| `getFanMetrics(filePath)` | `Promise<Result<FanMetrics>>` | fan-in/fan-out 결합도 |
-| `getModuleInterface(filePath)` | `Result<ModuleInterface>` | 공개 export와 메타데이터 |
-| `getInternalRelations(filePath)` | `Result<CodeRelation[]>` | 파일 내부 관계 |
+| `getFullSymbol(name, filePath)` | `FullSymbol \| null` | 멤버, jsDoc, 데코레이터, 타입 정보 |
+| `getFileStats(filePath)` | `FileStats` | 라인 수, 심볼 수, 파일 크기 |
+| `getFanMetrics(filePath)` | `Promise<FanMetrics>` | fan-in/fan-out 결합도 |
+| `getModuleInterface(filePath)` | `ModuleInterface` | 공개 export와 메타데이터 |
+| `getInternalRelations(filePath)` | `StoredCodeRelation[]` | 파일 내부 관계 |
 | `diffSymbols(before, after)` | `SymbolDiff` | 스냅샷 diff (추가/삭제/수정) |
 
+### 시맨틱 (opt-in)
+
+`semantic: true`로 열어야 사용 가능.
+
+| 메서드 | 반환 타입 | 설명 |
+|--------|-----------|------|
+| `getResolvedType(name, filePath)` | `ResolvedType \| null` | tsc TypeChecker로 resolved type 조회 |
+| `getSemanticReferences(name, filePath)` | `SemanticReference[]` | 심볼의 모든 참조 위치 |
+| `getImplementations(name, filePath)` | `Implementation[]` | 인터페이스/추상 클래스 구현체 |
+| `getSemanticModuleInterface(filePath)` | `SemanticModuleInterface` | 모듈 export 목록 + resolved type |
+
+`getFullSymbol()`은 semantic 활성 시 자동으로 `resolvedType` 필드를 보강합니다.
+`searchSymbols({ resolvedType })`로 resolved type 문자열 기반 필터링이 가능합니다.
+
 ### 고급
 
 | 메서드 | 반환 타입 | 설명 |
 |--------|-----------|------|
-| `findPattern(pattern, opts?)` | `Promise<Result<PatternMatch[]>>` | AST 구조적 검색 (ast-grep) |
-| `resolveSymbol(name, filePath)` | `Result<ResolvedSymbol>` | re-export 체인을 따라 원본 추적 |
-| `getHeritageChain(name, filePath)` | `Promise<Result<HeritageNode>>` | extends/implements 트리 |
-| `indexExternalPackages(packages)` | `Promise<Result<IndexResult[]>>` | `node_modules`의 `.d.ts` 인덱싱 |
-| `batchParse(filePaths, opts?)` | `Promise<Result<Map>>` | 다중 파일 동시 파싱. `opts`: oxc-parser `ParserOptions`. |
+| `findPattern(pattern, opts?)` | `Promise<PatternMatch[]>` | AST 구조적 검색 (ast-grep) |
+| `resolveSymbol(name, filePath)` | `ResolvedSymbol` | re-export 체인을 따라 원본 추적 |
+| `getHeritageChain(name, filePath)` | `Promise<HeritageNode>` | extends/implements 트리 |
+| `batchParse(filePaths, opts?)` | `Promise<Map>` | 다중 파일 동시 파싱. `opts`: oxc-parser `ParserOptions`. |
 
 ### 라이프사이클 & 저수준
 
 | 메서드 | 반환 타입 | 설명 |
 |--------|-----------|------|
-| `reindex()` | `Promise<Result<IndexResult>>` | 강제 전체 재인덱싱 (owner만 가능) |
+| `reindex()` | `Promise<IndexResult>` | 강제 전체 재인덱싱 (owner만 가능) |
 | `onIndexed(callback)` | `() => void` | 인덱싱 완료 이벤트 구독 |
-| `parseSource(filePath, src, opts?)` | `Result<ParsedFile>` | 단일 파일 파싱 & 캐시. `opts`: oxc-parser `ParserOptions`. |
-| `extractSymbols(parsed)` | `Result<ExtractedSymbol[]>` | 파싱된 AST에서 심볼 추출 |
-| `extractRelations(parsed)` | `Result<CodeRelation[]>` | 파싱된 AST에서 관계 추출 |
+| `parseSource(filePath, src, opts?)` | `ParsedFile` | 단일 파일 파싱 & 캐시. `opts`: oxc-parser `ParserOptions`. |
+| `extractSymbols(parsed)` | `ExtractedSymbol[]` | 파싱된 AST에서 심볼 추출 |
+| `extractRelations(parsed)` | `CodeRelation[]` | 파싱된 AST에서 관계 추출 |
 | `getParsedAst(filePath)` | `ParsedFile \| undefined` | 캐시된 AST 조회 (읽기 전용) |
-| `getFileInfo(filePath)` | `Result<FileRecord \| null>` | 파일 메타데이터 (해시, mtime, 크기) |
-| `getStats(project?)` | `Result<SymbolStats>` | 심볼/파일 통계 |
+| `getFileInfo(filePath)` | `FileRecord \| null` | 파일 메타데이터 (해시, mtime, 크기) |
+| `getStats(project?)` | `SymbolStats` | 심볼/파일 통계 |
 | `projects` | `ProjectBoundary[]` | 탐지된 프로젝트 경계 |
-| `close(opts?)` | `Promise<Result<void>>` | 종료 (`{ cleanup: true }`로 DB 삭제 가능) |
+| `close(opts?)` | `Promise<void>` | 종료 (`{ cleanup: true }`로 DB 삭제 가능) |
 
 <br>
 
@@ -326,6 +340,11 @@ interface CodeRelation {
   meta?: Record<string, unknown>;
 }
 
+/** 목적지 프로젝트 식별자가 추가된 CodeRelation */
+interface StoredCodeRelation extends CodeRelation {
+  dstProject: string;
+}
+
 interface IndexResult {
   indexedFiles: number;
   removedFiles: number;
@@ -342,10 +361,10 @@ interface IndexResult {
   };
 }
 
-interface GildashError {
-  type: GildashErrorType;
-  message: string;
-  cause?: unknown;
+class GildashError extends Error {
+  readonly type: GildashErrorType;
+  readonly message: string;
+  readonly cause?: unknown;          // Error에서 상속
 }
 ```
 
@@ -364,6 +383,7 @@ interface GildashError {
 | `store` | DB 연산 실패 |
 | `search` | 검색 쿼리 실패 |
 | `closed` | 종료된 인스턴스에서 연산 시도 |
+| `semantic` | 시맨틱 레이어 미활성화 또는 tsc 에러 |
 | `validation` | 잘못된 입력 (e.g. `node_modules`에 패키지 없음) |
 | `close` | 종료 중 에러 |
 
@@ -378,6 +398,7 @@ Gildash (파사드)
 ├── Store       — bun:sqlite + drizzle-orm (files · symbols · relations · FTS5), `.gildash/gildash.db`에 저장
 ├── Indexer     — 파일 변경 → 파싱 → 추출 → 저장 파이프라인, 심볼 레벨 diff
 ├── Search      — FTS + regex + decorator 검색, 관계 쿼리, 의존성 그래프, ast-grep
+├── Semantic    — tsc TypeChecker 통합 (opt-in): 타입, 참조, 구현체
 └── Watcher     — @parcel/watcher + owner/reader 역할 관리
 ```
 
@@ -390,7 +411,26 @@ Gildash (파사드)
 
 <br>
 
-## ⬆️ 0.5.0에서 업그레이드
+## ⬆️ 업그레이드
+
+### 0.5.x → 0.6.0
+
+**Breaking:** `@zipbul/result`가 더 이상 public API의 일부가 아닙니다. 모든 메서드가 값을 직접 반환하고, 실패 시 `GildashError`를 throw합니다.
+
+```diff
+- import { isErr } from '@zipbul/result';
+- const result = ledger.searchSymbols({ text: 'foo' });
+- if (isErr(result)) { console.error(result.data.message); }
+- else { console.log(result); }
++ const symbols = ledger.searchSymbols({ text: 'foo' }); // 실패 시 GildashError throw
+```
+
+- `@zipbul/result`를 의존성에서 제거하세요 (더 이상 피어 의존성이 아닙니다)
+- `isErr()` 체크를 `try/catch` + `instanceof GildashError`로 교체하세요
+- `getFullSymbol()`, `getFileInfo()`, `getResolvedType()`은 찾지 못하면 에러 대신 `null`을 반환합니다
+- `resolveSymbol()`은 순환 re-export 시 throw 대신 `{ circular: true }`를 반환합니다
+
+### 0.4.x → 0.5.0
 
 데이터베이스 디렉토리가 `.zipbul/`에서 `.gildash/`로 변경되었습니다. 데이터베이스는 `<projectRoot>/.gildash/gildash.db`에 저장됩니다.
 

package/README.md

@@ -32,8 +32,8 @@ gildash indexes your TypeScript codebase into a local SQLite database, then lets
 - **Symbol-level diff** — `changedSymbols` in `IndexResult` tracks added/modified/removed symbols per index cycle
 - **Multi-process safe** — Owner/reader role separation guarantees a single writer per database
 - **Scan-only mode** — `watchMode: false` for one-shot indexing without file watcher overhead
-- **External package indexing** — Index `.d.ts` type declarations from `node_modules`
 - **tsconfig.json JSONC** — Path alias resolution parses comments and trailing commas in `tsconfig.json`
+- **Semantic layer (opt-in)** — tsc TypeChecker integration for resolved types, references, implementations, and module interface analysis
 
 <br>
 
@@ -50,7 +50,7 @@ gildash indexes your TypeScript codebase into a local SQLite database, then lets
 bun add @zipbul/gildash
 ```
 
-> **Peer dependency** — [`@zipbul/result`](https://www.npmjs.com/package/@zipbul/result) is required. All public methods return `Result<T, GildashError>`.
+> **Optional peer** — `typescript` (>=5.0.0) is needed only when using `semantic: true`.
 
 <br>
 
@@ -58,7 +58,6 @@ bun add @zipbul/gildash
 
 ```ts
 import { Gildash } from '@zipbul/gildash';
-import { isErr } from '@zipbul/result';
 
 // 1. Open — indexes every .ts file on first run, then watches for changes
 const ledger = await Gildash.open({
@@ -66,10 +65,8 @@ const ledger = await Gildash.open({
 });
 
 // 2. Search — find symbols by name
-const result = ledger.searchSymbols({ text: 'UserService', kind: 'class' });
-if (!isErr(result)) {
-  result.forEach(s => console.log(`${s.name} → ${s.filePath}`));
-}
+const symbols = ledger.searchSymbols({ text: 'UserService', kind: 'class' });
+symbols.forEach(s => console.log(`${s.name} → ${s.filePath}`));
 
 // 3. Close — release resources
 await ledger.close();
@@ -202,16 +199,18 @@ await ledger.close({ cleanup: true });   // delete DB files after use
 
 ## ❌ Error Handling
 
-Every public method returns `Result<T, GildashError>` from [`@zipbul/result`](https://www.npmjs.com/package/@zipbul/result). Use `isErr()` to branch:
+Public methods return values directly and throw `GildashError` on failure. Use `instanceof` to branch:
 
 ```ts
-import { isErr } from '@zipbul/result';
-
-const result = ledger.searchSymbols({ text: 'foo' });
-if (isErr(result)) {
-  console.error(result.data.type, result.data.message);
-} else {
-  console.log(`Found ${result.length} symbols`);
+import { Gildash, GildashError } from '@zipbul/gildash';
+
+try {
+  const symbols = ledger.searchSymbols({ text: 'foo' });
+  console.log(`Found ${symbols.length} symbols`);
+} catch (e) {
+  if (e instanceof GildashError) {
+    console.error(`[${e.type}] ${e.message}`);
+  }
 }
 ```
 
@@ -229,8 +228,11 @@ if (isErr(result)) {
 | `parseCacheCapacity` | `number` | `500` | LRU parse-cache capacity |
 | `logger` | `Logger` | `console` | Custom logger (`{ error(...args): void }`) |
 | `watchMode` | `boolean` | `true` | `false` disables the file watcher (scan-only mode) |
+| `semantic` | `boolean` | `false` | Enable tsc TypeChecker-backed semantic analysis |
+
+Returns `Promise<Gildash>`. Throws `GildashError` on failure.
 
-Returns `Promise<Gildash>` (wrapped in `Result`).
+> **Note:** `semantic: true` requires a `tsconfig.json` in the project root. If not found, `Gildash.open()` throws a `GildashError`.
 
 <br>
 
@@ -240,60 +242,73 @@ Returns `Promise<Gildash>` (wrapped in `Result`).
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `searchSymbols(query)` | `Result<SymbolSearchResult[]>` | FTS5 full-text + exact / regex / decorator filters |
-| `searchRelations(query)` | `Result<CodeRelation[]>` | Filter by file, symbol, or relation type |
-| `searchAllSymbols(query)` | `Result<SymbolSearchResult[]>` | Cross-project symbol search |
-| `searchAllRelations(query)` | `Result<CodeRelation[]>` | Cross-project relation search |
-| `listIndexedFiles(project?)` | `Result<FileRecord[]>` | All indexed files for a project |
-| `getSymbolsByFile(filePath)` | `Result<SymbolSearchResult[]>` | All symbols in a single file |
+| `searchSymbols(query)` | `SymbolSearchResult[]` | FTS5 full-text + exact / regex / decorator filters |
+| `searchRelations(query)` | `StoredCodeRelation[]` | Filter by file, symbol, or relation type |
+| `searchAllSymbols(query)` | `SymbolSearchResult[]` | Cross-project symbol search |
+| `searchAllRelations(query)` | `StoredCodeRelation[]` | Cross-project relation search |
+| `listIndexedFiles(project?)` | `FileRecord[]` | All indexed files for a project |
+| `getSymbolsByFile(filePath)` | `SymbolSearchResult[]` | All symbols in a single file |
 
 ### Dependency Graph
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `getDependencies(filePath)` | `Result<string[]>` | Files imported by `filePath` |
-| `getDependents(filePath)` | `Result<string[]>` | Files that import `filePath` |
-| `getAffected(changedFiles)` | `Promise<Result<string[]>>` | Transitive impact set |
-| `hasCycle(project?)` | `Promise<Result<boolean>>` | Circular dependency check |
-| `getCyclePaths(project?, opts?)` | `Promise<Result<string[][]>>` | All cycle paths (Tarjan SCC + Johnson's). `opts.maxCycles` limits results. |
-| `getImportGraph(project?)` | `Promise<Result<Map>>` | Full adjacency list |
-| `getTransitiveDependencies(filePath)` | `Promise<Result<string[]>>` | Forward transitive BFS |
+| `getDependencies(filePath)` | `string[]` | Files imported by `filePath` |
+| `getDependents(filePath)` | `string[]` | Files that import `filePath` |
+| `getAffected(changedFiles)` | `Promise<string[]>` | Transitive impact set |
+| `hasCycle(project?)` | `Promise<boolean>` | Circular dependency check |
+| `getCyclePaths(project?, opts?)` | `Promise<string[][]>` | All cycle paths (Tarjan SCC + Johnson's). `opts.maxCycles` limits results. |
+| `getImportGraph(project?)` | `Promise<Map>` | Full adjacency list |
+| `getTransitiveDependencies(filePath)` | `Promise<string[]>` | Forward transitive BFS |
 
 ### Analysis
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `getFullSymbol(name, filePath)` | `Result<FullSymbol>` | Members, jsDoc, decorators, type info |
-| `getFileStats(filePath)` | `Result<FileStats>` | Line count, symbol count, size |
-| `getFanMetrics(filePath)` | `Promise<Result<FanMetrics>>` | Fan-in / fan-out coupling |
-| `getModuleInterface(filePath)` | `Result<ModuleInterface>` | Public exports with metadata |
-| `getInternalRelations(filePath)` | `Result<CodeRelation[]>` | Intra-file relations |
+| `getFullSymbol(name, filePath)` | `FullSymbol \| null` | Members, jsDoc, decorators, type info |
+| `getFileStats(filePath)` | `FileStats` | Line count, symbol count, size |
+| `getFanMetrics(filePath)` | `Promise<FanMetrics>` | Fan-in / fan-out coupling |
+| `getModuleInterface(filePath)` | `ModuleInterface` | Public exports with metadata |
+| `getInternalRelations(filePath)` | `StoredCodeRelation[]` | Intra-file relations |
 | `diffSymbols(before, after)` | `SymbolDiff` | Snapshot diff (added / removed / modified) |
 
+### Semantic (opt-in)
+
+Requires `semantic: true` at open time.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getResolvedType(name, filePath)` | `ResolvedType \| null` | Resolved type via tsc TypeChecker |
+| `getSemanticReferences(name, filePath)` | `SemanticReference[]` | All references to a symbol |
+| `getImplementations(name, filePath)` | `Implementation[]` | Interface / abstract class implementations |
+| `getSemanticModuleInterface(filePath)` | `SemanticModuleInterface` | Module exports with resolved types |
+
+`getFullSymbol()` automatically enriches the result with a `resolvedType` field when semantic is enabled.
+`searchSymbols({ resolvedType })` filters symbols by their resolved type string.
+
 ### Advanced
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `findPattern(pattern, opts?)` | `Promise<Result<PatternMatch[]>>` | AST structural search (ast-grep) |
-| `resolveSymbol(name, filePath)` | `Result<ResolvedSymbol>` | Follow re-export chain to original |
-| `getHeritageChain(name, filePath)` | `Promise<Result<HeritageNode>>` | extends / implements tree |
-| `indexExternalPackages(packages)` | `Promise<Result<IndexResult[]>>` | Index `.d.ts` from `node_modules` |
-| `batchParse(filePaths, opts?)` | `Promise<Result<Map>>` | Concurrent multi-file parsing. `opts`: oxc-parser `ParserOptions`. |
+| `findPattern(pattern, opts?)` | `Promise<PatternMatch[]>` | AST structural search (ast-grep) |
+| `resolveSymbol(name, filePath)` | `ResolvedSymbol` | Follow re-export chain to original |
+| `getHeritageChain(name, filePath)` | `Promise<HeritageNode>` | extends / implements tree |
+| `batchParse(filePaths, opts?)` | `Promise<Map>` | Concurrent multi-file parsing. `opts`: oxc-parser `ParserOptions`. |
 
 ### Lifecycle & Low-level
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `reindex()` | `Promise<Result<IndexResult>>` | Force full re-index (owner only) |
+| `reindex()` | `Promise<IndexResult>` | Force full re-index (owner only) |
 | `onIndexed(callback)` | `() => void` | Subscribe to index-complete events |
-| `parseSource(filePath, src, opts?)` | `Result<ParsedFile>` | Parse & cache a single file. `opts`: oxc-parser `ParserOptions`. |
-| `extractSymbols(parsed)` | `Result<ExtractedSymbol[]>` | Extract symbols from parsed AST |
-| `extractRelations(parsed)` | `Result<CodeRelation[]>` | Extract relations from parsed AST |
+| `parseSource(filePath, src, opts?)` | `ParsedFile` | Parse & cache a single file. `opts`: oxc-parser `ParserOptions`. |
+| `extractSymbols(parsed)` | `ExtractedSymbol[]` | Extract symbols from parsed AST |
+| `extractRelations(parsed)` | `CodeRelation[]` | Extract relations from parsed AST |
 | `getParsedAst(filePath)` | `ParsedFile \| undefined` | Cached AST lookup (read-only) |
-| `getFileInfo(filePath)` | `Result<FileRecord \| null>` | File metadata (hash, mtime, size) |
-| `getStats(project?)` | `Result<SymbolStats>` | Symbol / file count statistics |
+| `getFileInfo(filePath)` | `FileRecord \| null` | File metadata (hash, mtime, size) |
+| `getStats(project?)` | `SymbolStats` | Symbol / file count statistics |
 | `projects` | `ProjectBoundary[]` | Discovered project boundaries |
-| `close(opts?)` | `Promise<Result<void>>` | Shutdown (pass `{ cleanup: true }` to delete DB) |
+| `close(opts?)` | `Promise<void>` | Shutdown (pass `{ cleanup: true }` to delete DB) |
 
 <br>
 
@@ -332,6 +347,7 @@ interface RelationSearchQuery {
   srcSymbolName?: string;
   dstFilePath?: string;
   dstSymbolName?: string;
+  dstProject?: string;  // filter by destination project
   type?: 'imports' | 'type-references' | 're-exports' | 'calls' | 'extends' | 'implements';
   project?: string;
   limit?: number;       // default: 500
@@ -347,6 +363,11 @@ interface CodeRelation {
   meta?: Record<string, unknown>;   // auto-parsed from metaJson
 }
 
+/** CodeRelation enriched with the destination project identifier. */
+interface StoredCodeRelation extends CodeRelation {
+  dstProject: string;
+}
+
 // ── Analysis ────────────────────────────────────────────────────────────
 
 interface FullSymbol extends SymbolSearchResult {
@@ -411,6 +432,7 @@ interface ResolvedSymbol {
   originalName: string;
   originalFilePath: string;
   reExportChain: Array<{ filePath: string; exportedAs: string }>;
+  circular: boolean;    // true when re-export chain contains a cycle
 }
 
 interface HeritageNode {
@@ -450,10 +472,10 @@ interface FileRecord {
 
 // ── Errors ──────────────────────────────────────────────────────────────
 
-interface GildashError {
-  type: GildashErrorType;   // see Error Types table below
-  message: string;
-  cause?: unknown;
+class GildashError extends Error {
+  readonly type: GildashErrorType;   // see Error Types table below
+  readonly message: string;
+  readonly cause?: unknown;          // inherited from Error
 }
 ```
 
@@ -472,6 +494,7 @@ interface GildashError {
 | `store` | Database operation failure |
 | `search` | Search query failure |
 | `closed` | Operation on a closed instance |
+| `semantic` | Semantic layer not enabled or tsc error |
 | `validation` | Invalid input (e.g. missing `node_modules` package) |
 | `close` | Error during shutdown |
 
@@ -486,6 +509,7 @@ Gildash (Facade)
 ├── Store       — bun:sqlite + drizzle-orm (files · symbols · relations · FTS5) at `.gildash/gildash.db`
 ├── Indexer     — File change → parse → extract → store pipeline, symbol-level diff
 ├── Search      — FTS + regex + decorator search, relation queries, dependency graph, ast-grep
+├── Semantic    — tsc TypeChecker integration (opt-in): types, references, implementations
 └── Watcher     — @parcel/watcher + owner/reader role management
 ```
 
@@ -498,7 +522,26 @@ When multiple processes share the same SQLite database, gildash enforces a singl
 
 <br>
 
-## ⬆️ Upgrading from 0.5.0
+## ⬆️ Upgrading
+
+### From 0.5.x to 0.6.0
+
+**Breaking:** `@zipbul/result` is no longer part of the public API. All methods now return values directly and throw `GildashError` on failure.
+
+```diff
+- import { isErr } from '@zipbul/result';
+- const result = ledger.searchSymbols({ text: 'foo' });
+- if (isErr(result)) { console.error(result.data.message); }
+- else { console.log(result); }
++ const symbols = ledger.searchSymbols({ text: 'foo' }); // throws GildashError
+```
+
+- Remove `@zipbul/result` from your dependencies (no longer a peer dependency)
+- Replace `isErr()` checks with `try/catch` using `instanceof GildashError`
+- `getFullSymbol()`, `getFileInfo()`, `getResolvedType()` return `null` instead of an error when not found
+- `resolveSymbol()` returns `{ circular: true }` for circular re-exports instead of throwing
+
+### From 0.4.x to 0.5.0
 
 The database directory was renamed from `.zipbul/` to `.gildash/`. The database is now stored at `<projectRoot>/.gildash/gildash.db`.