@zipbul/gildash 0.3.0 → 0.4.0

package/README.ko.md

@@ -6,19 +6,34 @@
 [![CI](https://github.com/zipbul/gildash/actions/workflows/ci.yml/badge.svg)](https://github.com/zipbul/gildash/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-**Bun 네이티브** TypeScript 코드 인덱서.
-심볼 추출, 파일 간 관계 추적, 의존성 그래프 구축을 하나의 로컬 SQLite 데이터베이스로 제공합니다.
+**Bun 네이티브** TypeScript 코드 인텔리전스 엔진.
+
+gildash는 TypeScript 코드베이스를 로컬 SQLite 데이터베이스에 인덱싱하여, 심볼 검색 · 파일 간 관계 추적 · 의존성 그래프 분석 · 구조적 패턴 매칭을 제공합니다. 파일 변경을 감시하며 증분(incremental) 재인덱싱을 자동으로 수행합니다.
+
+## 💡 왜 gildash인가?
+
+| 문제 | gildash의 해결 방식 |
+|------|---------------------|
+| "이 모듈을 바꾸면 어디가 깨지지?" | 방향 import 그래프 + 전이적(transitive) 영향도 분석 |
+| "순환 의존성이 있나?" | 전체 import 그래프에서 순환 감지 |
+| "이 심볼이 실제로 어디서 정의된 거지?" | re-export 체인을 따라가 원본 소스까지 추적 |
+| "사용되지 않는 export는?" | 프로젝트 전체에서 미사용 export 탐지 |
+| "모든 `console.log(...)` 호출을 찾아줘" | [ast-grep](https://ast-grep.github.io/) 기반 AST 레벨 구조적 패턴 검색 |
 
 <br>
 
 ## ✨ 주요 기능
 
-- **심볼 추출** — 함수, 클래스, 변수, 타입, 인터페이스, 열거형, 프로퍼티를 AST 수준에서 추출
-- **관계 분석** — `import`, `calls`, `extends`, `implements` 관계를 파일 간에 추적
-- **전문 검색** — SQLite FTS5 기반 심볼 이름 전문 검색
-- **의존성 그래프** — 방향 import 그래프로 순환 감지 및 전이적(transitive) 영향도 분석
+- **심볼 추출** — 함수, 클래스, 변수, 타입, 인터페이스, 열거형, 프로퍼티를 [oxc-parser](https://oxc.rs) AST 수준에서 추출
+- **관계 분석** — `import`, `re-exports`, `type-references`, `calls`, `extends`, `implements` 관계를 파일 간에 추적
+- **전문 검색** — SQLite FTS5 기반 심볼 이름 전문 검색 + 정확 일치(exact), 정규식(regex), 데코레이터(decorator) 필터
+- **의존성 그래프** — 방향 import 그래프로 순환 감지, 전이적(transitive) 영향도 분석, 내부 캐싱
+- **구조적 패턴 매칭** — [@ast-grep/napi](https://ast-grep.github.io/) 기반 AST 레벨 코드 검색
 - **증분 인덱싱** — `@parcel/watcher` 기반 파일 변경 감지, 변경된 파일만 재인덱싱
+- **심볼 레벨 diff** — `IndexResult`의 `changedSymbols`로 인덱싱 사이클 당 추가/수정/삭제된 심볼 추적
 - **멀티 프로세스 안전** — owner/reader 역할 분리로 단일 writer 보장
+- **스캔 전용 모드** — `watchMode: false`로 파일 워처 없이 1회성 인덱싱
+- **외부 패키지 인덱싱** — `node_modules`의 `.d.ts` 타입 선언 인덱싱
 
 <br>
 
@@ -35,396 +50,325 @@
 bun add @zipbul/gildash
 ```
 
+> **피어 의존성** — [`@zipbul/result`](https://www.npmjs.com/package/@zipbul/result)가 필요합니다. 모든 public 메서드는 `Result<T, GildashError>`를 반환합니다.
+
 <br>
 
 ## 🚀 빠른 시작
 
 ```ts
 import { Gildash } from '@zipbul/gildash';
+import { isErr } from '@zipbul/result';
 
-// 인덱서 열기 — 최초 실행 시 전체 인덱싱 자동 수행, 이후 파일 변경을 감시
+// 1. 열기 — 최초 실행 시 전체 .ts 파일 인덱싱, 이후 파일 변경 감시
 const ledger = await Gildash.open({
   projectRoot: '/absolute/path/to/project',
 });
 
-// 심볼 검색
-const hits = ledger.searchSymbols({ text: 'UserService', kind: 'class' });
-
-// 정확한 이름 매칭
-const exact = ledger.searchSymbols({ text: 'UserService', exact: true });
-
-// 의존성 그래프 조회
-const deps     = ledger.getDependencies('src/app.ts');
-const affected = await ledger.getAffected(['src/utils.ts']);
-const cyclic   = await ledger.hasCycle();
-
-// 파일 정보 및 심볼 조회
-const fileInfo = ledger.getFileInfo('src/app.ts');
-const symbols  = ledger.getSymbolsByFile('src/app.ts');
-
-// 캐시된 AST 조회
-const ast = ledger.getParsedAst('/absolute/path/to/src/app.ts');
+// 2. 검색 — 이름으로 심볼 찾기
+const result = ledger.searchSymbols({ text: 'UserService', kind: 'class' });
+if (!isErr(result)) {
+  result.forEach(s => console.log(`${s.name} → ${s.filePath}`));
+}
 
+// 3. 종료 — 리소스 해제
 await ledger.close();
 ```
 
-<br>
-
-## 🔍 API 개요
-
-| 메서드 | 반환 타입 | 설명 |
-|--------|-----------|------|
-| `searchSymbols(query)` | `SymbolSearchResult[]` | FTS5 전문 검색 + 필터 조합. `exact` 옵션 지원 |
-| `searchRelations(query)` | `CodeRelation[]` | 파일/심볼/관계 유형 필터 |
-| `getDependencies(filePath, project?)` | `string[]` | 이 파일이 import하는 파일 목록 |
-| `getDependents(filePath, project?)` | `string[]` | 이 파일을 import하는 파일 목록 |
-| `getAffected(changedFiles, project?)` | `Promise<string[]>` | 변경 파일의 전이적 영향 범위 |
-| `hasCycle(project?)` | `Promise<boolean>` | 순환 의존성 감지 |
-| `reindex()` | `Promise<IndexResult>` | 강제 전체 재인덱싱 |
-| `onIndexed(callback)` | `() => void` | 인덱싱 완료 이벤트 구독 |
-| `parseSource(filePath, src)` | `ParsedFile` | 파일 파싱 후 AST 캐시 |
-| `extractSymbols(parsed)` | `ExtractedSymbol[]` | 파싱된 파일에서 심볼 추출 |
-| `extractRelations(parsed)` | `CodeRelation[]` | 파싱된 파일에서 관계 추출 |
-| `getParsedAst(filePath)` | `ParsedFile \| undefined` | 캐시된 AST 조회 |
-| `getFileInfo(filePath, project?)` | `FileRecord \| null` | 인덱싱된 파일 메타데이터 조회 |
-| `getSymbolsByFile(filePath, project?)` | `SymbolSearchResult[]` | 특정 파일의 모든 심볼 조회 |
-| `projects` | `ProjectBoundary[]` | 감지된 프로젝트 경계 (모노레포) |
-| `getStats(project?)` | `SymbolStats` | 심볼 통계 |
-| `close()` | `Promise<void>` | 인덱서 종료 |
+프로젝트 탐색(모노레포 지원), 증분 재인덱싱, 멀티 프로세스 안전 모두 자동으로 처리됩니다.
 
 <br>
 
-## ⚙️ API 레퍼런스
+## 📖 사용 가이드
 
-### `Gildash.open(options)`
+### 심볼 검색
 
-인덱서 인스턴스를 생성합니다. 최초 실행 시 전체 인덱싱을 수행하고, 이후 파일 변경을 감시합니다.
+인덱싱된 심볼을 FTS5 전문 검색, 정확 일치, 정규식, 데코레이터 필터로 검색합니다.
 
 ```ts
-const ledger = await Gildash.open({
-  projectRoot: '/absolute/path',       // 필수. 절대 경로
-  extensions: ['.ts', '.mts', '.cts'], // 선택. 인덱싱 대상 확장자
-  ignorePatterns: ['dist', 'vendor'],  // 선택. 무시할 디렉토리/패턴
-  parseCacheCapacity: 500,             // 선택. 파싱 캐시 크기
-});
-```
-
-| 옵션 | 타입 | 기본값 | 설명 |
-|------|------|--------|------|
-| `projectRoot` | `string` | — | 프로젝트 루트 절대 경로 **(필수)** |
-| `extensions` | `string[]` | `['.ts', '.mts', '.cts']` | 인덱싱 대상 파일 확장자 |
-| `ignorePatterns` | `string[]` | `[]` | 무시할 경로 패턴 |
-| `parseCacheCapacity` | `number` | `500` | LRU 파싱 캐시 최대 크기 |
-| `logger` | `Logger` | `console` | 커스텀 로거 (`{ error(...args): void }`) |
-
-**반환**: `Promise<Gildash>`
-
----
-
-### `ledger.close()`
-
-인덱서를 종료합니다. watcher 중지, DB 연결 해제, 시그널 핸들러 제거를 수행합니다.
-
-```ts
-await ledger.close();
-```
-
-**반환**: `Promise<void>`
+// 전문 검색 (FTS5 접두사 매칭)
+const hits = ledger.searchSymbols({ text: 'handle' });
 
----
-
-### `ledger.searchSymbols(query)`
-
-심볼을 검색합니다. FTS5 전문 검색과 필터를 조합할 수 있습니다.
+// 정확한 이름 매칭
+const exact = ledger.searchSymbols({ text: 'UserService', exact: true });
 
-```ts
-// 이름으로 검색
-const results = ledger.searchSymbols({ text: 'handleClick' });
+// 정규식 패턴
+const handlers = ledger.searchSymbols({ regex: '^handle.*Click$' });
 
-// 정확한 이름 매칭 (FTS prefix가 아닌 완전 일치)
-const exact = ledger.searchSymbols({ text: 'UserService', exact: true });
+// 데코레이터 필터
+const injectables = ledger.searchSymbols({ decorator: 'Injectable' });
 
-// 종류 + export 여부 필터
-const classes = ledger.searchSymbols({
+// 필터 조합
+const exportedClasses = ledger.searchSymbols({
   kind: 'class',
   isExported: true,
   limit: 50,
 });
-
-// 파일 경로 필터
-const inFile = ledger.searchSymbols({
-  filePath: 'src/services/user.ts',
-});
 ```
 
-| 필드 | 타입 | 설명 |
-|------|------|------|
-| `text` | `string?` | FTS5 전문 검색 쿼리 |
-| `exact` | `boolean?` | `true`이면 `text`를 정확한 이름으로 매칭 (FTS prefix 아님) |
-| `kind` | `SymbolKind?` | `'function'` \| `'method'` \| `'class'` \| `'variable'` \| `'type'` \| `'interface'` \| `'enum'` \| `'property'` |
-| `filePath` | `string?` | 특정 파일 경로 필터 |
-| `isExported` | `boolean?` | export 여부 필터 |
-| `project` | `string?` | 프로젝트 이름 (모노레포 지원) |
-| `limit` | `number?` | 최대 결과 수 |
-
-**반환**: `SymbolSearchResult[]`
-
-```ts
-interface SymbolSearchResult {
-  id: number;
-  filePath: string;
-  kind: SymbolKind;
-  name: string;
-  span: {
-    start: { line: number; column: number };
-    end: { line: number; column: number };
-  };
-  isExported: boolean;
-  signature: string | null;
-  fingerprint: string | null;
-  detail: Record<string, unknown>;
-}
-```
-
----
-
-### `ledger.searchRelations(query)`
-
-파일/심볼 간 관계를 검색합니다.
+`searchRelations()`로 파일 간 관계를 검색할 수 있습니다:
 
 ```ts
-// 특정 파일이 import하는 관계
-const imports = ledger.searchRelations({
-  srcFilePath: 'src/app.ts',
-  type: 'imports',
-});
-
-// 특정 심볼을 호출하는 관계
-const callers = ledger.searchRelations({
-  dstSymbolName: 'processOrder',
-  type: 'calls',
-});
+const imports = ledger.searchRelations({ srcFilePath: 'src/app.ts', type: 'imports' });
+const callers = ledger.searchRelations({ dstSymbolName: 'processOrder', type: 'calls' });
 ```
 
-| 필드 | 타입 | 설명 |
-|------|------|------|
-| `srcFilePath` | `string?` | 출발 파일 경로 |
-| `srcSymbolName` | `string?` | 출발 심볼 이름 |
-| `dstFilePath` | `string?` | 도착 파일 경로 |
-| `dstSymbolName` | `string?` | 도착 심볼 이름 |
-| `type` | `'imports'` \| `'calls'` \| `'extends'` \| `'implements'`? | 관계 유형 |
-| `project` | `string?` | 프로젝트 이름 |
-| `limit` | `number?` | 최대 결과 수 |
-
-**반환**: `CodeRelation[]`
-
-```ts
-interface CodeRelation {
-  type: 'imports' | 'calls' | 'extends' | 'implements';
-  srcFilePath: string;
-  srcSymbolName: string | null;  // null = 모듈 레벨
-  dstFilePath: string;
-  dstSymbolName: string | null;
-  metaJson?: string;
-}
-```
+모노레포 프로젝트에서는 `searchAllSymbols()`와 `searchAllRelations()`로 전체 프로젝트를 검색합니다.
 
 ---
 
-### `ledger.getDependencies(filePath, project?)`
+### 의존성 분석
 
-특정 파일이 import하는 파일 목록을 반환합니다.
+import 그래프 분석, 순환 감지, 변경 영향 범위 계산을 수행합니다.
 
 ```ts
+// 직접 import / importer 목록
 const deps = ledger.getDependencies('src/app.ts');
-// → ['src/utils.ts', 'src/config.ts', ...]
-```
+const importers = ledger.getDependents('src/utils.ts');
 
-**반환**: `string[]`
-
----
+// 전이적 영향 — 파일 변경 시 어떤 파일이 영향을 받는가?
+const affected = await ledger.getAffected(['src/utils.ts']);
 
-### `ledger.getDependents(filePath, project?)`
+// 전체 import 그래프 (인접 리스트)
+const graph = await ledger.getImportGraph();
 
-특정 파일을 import하는 파일 목록을 반환합니다.
+// 전이적 의존성 (전방 BFS)
+const transitive = await ledger.getTransitiveDependencies('src/app.ts');
 
-```ts
-const dependents = ledger.getDependents('src/utils.ts');
-// → ['src/app.ts', 'src/services/user.ts', ...]
+// 순환 의존성 감지
+const hasCycles = await ledger.hasCycle();
+const cyclePaths = await ledger.getCyclePaths();
 ```
 
-**반환**: `string[]`
-
 ---
 
-### `ledger.getAffected(changedFiles, project?)`
+### 코드 품질 분석
 
-변경된 파일들의 영향을 받는 모든 파일을 전이적(transitive)으로 계산합니다.
+미사용 export 감지, 모듈 인터페이스 조회, 결합도 측정을 수행합니다.
 
 ```ts
-const affected = await ledger.getAffected(['src/utils.ts']);
-// → ['src/app.ts', 'src/services/user.ts', 'src/main.ts', ...]
-```
-
-**반환**: `Promise<string[]>`
+// 미사용 export — 어디에서도 import되지 않은 exported 심볼
+const dead = ledger.getDeadExports();
 
----
+// 파일 통계 — 라인 수, 심볼 수, 파일 크기
+const stats = ledger.getFileStats('src/app.ts');
 
-### `ledger.hasCycle(project?)`
+// Fan-in / Fan-out 결합도 메트릭
+const fan = await ledger.getFanMetrics('src/app.ts');
 
-프로젝트의 import 그래프에 순환 의존성이 있는지 검사합니다.
+// 모듈 공개 인터페이스 — 모든 exported 심볼과 메타데이터
+const iface = ledger.getModuleInterface('src/services/user.ts');
 
-```ts
-const cyclic = await ledger.hasCycle();
-if (cyclic) {
-  console.warn('순환 의존성이 감지되었습니다');
-}
+// 상세 심볼 정보 — 멤버, jsDoc, 데코레이터, 타입 정보
+const full = ledger.getFullSymbol('UserService', 'src/services/user.ts');
 ```
 
-**반환**: `Promise<boolean>`
-
 ---
 
-### `ledger.reindex()`
+### 패턴 매칭 & 추적
 
-수동으로 전체 재인덱싱을 수행합니다. owner 역할에서만 사용 가능합니다.
+AST 구조로 코드를 검색하고, re-export 체인을 통해 심볼 원본을 추적합니다.
 
 ```ts
-const result = await ledger.reindex();
-```
+// 구조적 패턴 검색 (ast-grep 문법)
+const logs = await ledger.findPattern('console.log($$$)');
+const hooks = await ledger.findPattern('useState($A)', {
+  filePaths: ['src/components/App.tsx'],
+});
 
-**반환**: `Promise<IndexResult>`
+// re-export 체인 추적 — 심볼이 실제로 정의된 위치 찾기
+const resolved = ledger.resolveSymbol('MyComponent', 'src/index.ts');
 
----
+// 상속 체인 — extends/implements 트리 순회
+const tree = await ledger.getHeritageChain('UserService', 'src/services/user.ts');
+```
 
-### `ledger.onIndexed(callback)`
+<br>
+
+## 🔧 스캔 전용 모드
 
-인덱싱 완료 이벤트를 구독합니다.
+CI 파이프라인이나 1회성 분석에서는 파일 워처를 비활성화합니다:
 
 ```ts
-const unsubscribe = ledger.onIndexed((result) => {
-  console.log(`인덱싱 완료: ${result.indexedFiles}개 파일`);
+const ledger = await Gildash.open({
+  projectRoot: '/path/to/project',
+  watchMode: false,        // 워처 없음, heartbeat 없음
 });
 
-// 구독 해제
-unsubscribe();
-```
-
-**반환**: `() => void` (구독 해제 함수)
+// ... 쿼리 실행 ...
 
----
-
-### `ledger.projects`
-
-감지된 프로젝트 경계 목록을 반환합니다 (모노레포에서 여러 프로젝트 감지).
-
-```ts
-const boundaries = ledger.projects;
-// → [{ project: 'my-app', root: '/path/to/project' }, ...]
+await ledger.close({ cleanup: true });   // DB 파일까지 삭제
 ```
 
-**타입**: `ProjectBoundary[]`
-
----
+<br>
 
-### `ledger.getStats(project?)`
+## ❌ 에러 처리
 
-심볼 통계를 반환합니다.
+모든 public 메서드는 [`@zipbul/result`](https://www.npmjs.com/package/@zipbul/result)의 `Result<T, GildashError>`를 반환합니다. `isErr()`로 에러를 분기합니다:
 
 ```ts
-const stats = ledger.getStats();
+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}개 심볼 발견`);
+}
 ```
 
-**반환**: `SymbolStats`
+<br>
 
----
+## ⚙️ 설정
 
-### `ledger.parseSource(filePath, sourceText)`
+### `Gildash.open(options)`
 
-파일을 파싱하여 AST를 반환합니다. 결과는 내부 캐시에 저장됩니다.
+| 옵션 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `projectRoot` | `string` | — | 프로젝트 루트 절대 경로 **(필수)** |
+| `extensions` | `string[]` | `['.ts', '.mts', '.cts']` | 인덱싱 대상 파일 확장자 |
+| `ignorePatterns` | `string[]` | `[]` | 무시할 글로브 패턴 |
+| `parseCacheCapacity` | `number` | `500` | LRU 파싱 캐시 최대 크기 |
+| `logger` | `Logger` | `console` | 커스텀 로거 (`{ error(...args): void }`) |
+| `watchMode` | `boolean` | `true` | `false`이면 파일 워처 비활성화 (스캔 전용 모드) |
 
-```ts
-const parsed = ledger.parseSource('/path/to/file.ts', sourceCode);
-```
+**반환**: `Promise<Gildash>` (`Result`로 래핑됨)
 
-**반환**: `ParsedFile`
+<br>
 
----
+## 🔍 API 레퍼런스
 
-### `ledger.extractSymbols(parsed)`
+### 검색
 
-파싱된 파일에서 심볼을 추출합니다.
+| 메서드 | 반환 타입 | 설명 |
+|--------|-----------|------|
+| `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[]>` | 단일 파일의 모든 심볼 |
 
-```ts
-const symbols = ledger.extractSymbols(parsed);
-```
+### 의존성 그래프
 
-**반환**: `ExtractedSymbol[]`
+| 메서드 | 반환 타입 | 설명 |
+|--------|-----------|------|
+| `getDependencies(filePath)` | `Result<string[]>` | `filePath`가 import하는 파일 목록 |
+| `getDependents(filePath)` | `Result<string[]>` | `filePath`를 import하는 파일 목록 |
+| `getAffected(changedFiles)` | `Promise<Result<string[]>>` | 전이적 영향 범위 |
+| `hasCycle(project?)` | `Promise<Result<boolean>>` | 순환 의존성 감지 |
+| `getCyclePaths(project?)` | `Promise<Result<string[][]>>` | 모든 순환 경로 |
+| `getImportGraph(project?)` | `Promise<Result<Map>>` | 전체 인접 리스트 |
+| `getTransitiveDependencies(filePath)` | `Promise<Result<string[]>>` | 전방 전이적 BFS |
 
----
+### 분석
 
-### `ledger.extractRelations(parsed)`
+| 메서드 | 반환 타입 | 설명 |
+|--------|-----------|------|
+| `getDeadExports(project?, opts?)` | `Result<Array>` | 미사용 exported 심볼 |
+| `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[]>` | 파일 내부 관계 |
+| `diffSymbols(before, after)` | `SymbolDiff` | 스냅샷 diff (추가/삭제/수정) |
 
-파싱된 파일에서 관계를 추출합니다.
+### 고급
 
-```ts
-const relations = ledger.extractRelations(parsed);
-```
+| 메서드 | 반환 타입 | 설명 |
+|--------|-----------|------|
+| `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)` | `Promise<Result<Map>>` | 다중 파일 동시 파싱 |
 
-**반환**: `CodeRelation[]`
+### 라이프사이클 & 저수준
 
----
+| 메서드 | 반환 타입 | 설명 |
+|--------|-----------|------|
+| `reindex()` | `Promise<Result<IndexResult>>` | 강제 전체 재인덱싱 (owner만 가능) |
+| `onIndexed(callback)` | `() => void` | 인덱싱 완료 이벤트 구독 |
+| `parseSource(filePath, src)` | `Result<ParsedFile>` | 단일 파일 파싱 & 캐시 |
+| `extractSymbols(parsed)` | `Result<ExtractedSymbol[]>` | 파싱된 AST에서 심볼 추출 |
+| `extractRelations(parsed)` | `Result<CodeRelation[]>` | 파싱된 AST에서 관계 추출 |
+| `getParsedAst(filePath)` | `ParsedFile \| undefined` | 캐시된 AST 조회 (읽기 전용) |
+| `getFileInfo(filePath)` | `Result<FileRecord \| null>` | 파일 메타데이터 (해시, mtime, 크기) |
+| `getStats(project?)` | `Result<SymbolStats>` | 심볼/파일 통계 |
+| `projects` | `ProjectBoundary[]` | 탐지된 프로젝트 경계 |
+| `close(opts?)` | `Promise<Result<void>>` | 종료 (`{ cleanup: true }`로 DB 삭제 가능) |
+
+<br>
 
-### `ledger.getParsedAst(filePath)`
+<details>
+<summary><strong>타입 정의</strong></summary>
 
-내부 LRU 캐시에서 이전에 파싱된 AST를 조회합니다.
+상세 TypeScript 타입 정의는 영문 README를 참고하세요 → [README.md — Type Definitions](./README.md#type-definitions)
 
-파일이 아직 파싱되지 않았거나 캐시에서 제거된 경우 `undefined`를 반환합니다.
-반환된 객체는 내부 캐시와 공유됩니다 — **읽기 전용**으로 취급하세요.
+주요 타입 요약:
 
 ```ts
-const ast = ledger.getParsedAst('/absolute/path/to/src/app.ts');
-if (ast) {
-  console.log(ast.program.body.length, '개의 AST 노드');
+interface SymbolSearchQuery {
+  text?: string;        // FTS5 전문 검색
+  exact?: boolean;      // 정확한 이름 일치
+  kind?: SymbolKind;    // 심볼 종류 필터
+  filePath?: string;    // 파일 경로 필터
+  isExported?: boolean; // export 여부
+  project?: string;     // 프로젝트 이름
+  limit?: number;       // 최대 결과 수 (기본값: 100)
+  decorator?: string;   // 데코레이터 이름 필터
+  regex?: string;       // 정규식 패턴 필터
 }
-```
 
-**반환**: `ParsedFile | undefined`
-
----
-
-### `ledger.getFileInfo(filePath, project?)`
-
-인덱싱된 파일의 메타데이터를 조회합니다.
+interface CodeRelation {
+  type: 'imports' | 'type-references' | 're-exports' | 'calls' | 'extends' | 'implements';
+  srcFilePath: string;
+  srcSymbolName: string | null;
+  dstFilePath: string;
+  dstSymbolName: string | null;
+  meta?: Record<string, unknown>;
+}
 
-content hash, mtime, size 등이 포함된 `FileRecord`를 반환합니다.
-파일이 아직 인덱싱되지 않은 경우 `null`을 반환합니다.
+interface IndexResult {
+  indexedFiles: number;
+  removedFiles: number;
+  totalSymbols: number;
+  totalRelations: number;
+  durationMs: number;
+  changedFiles: string[];
+  deletedFiles: string[];
+  failedFiles: string[];
+  changedSymbols: {
+    added: Array<{ name: string; filePath: string; kind: string }>;
+    modified: Array<{ name: string; filePath: string; kind: string }>;
+    removed: Array<{ name: string; filePath: string; kind: string }>;
+  };
+}
 
-```ts
-const info = ledger.getFileInfo('src/app.ts');
-if (!isErr(info) && info !== null) {
-  console.log(`해시: ${info.contentHash}, 크기: ${info.size}`);
+interface GildashError {
+  type: GildashErrorType;
+  message: string;
+  cause?: unknown;
 }
 ```
 
-**반환**: `Result<FileRecord | null, GildashError>`
-
----
-
-### `ledger.getSymbolsByFile(filePath, project?)`
+</details>
 
-특정 파일에 선언된 모든 심볼을 조회합니다. `searchSymbols`에 `filePath` 필터를 적용한 편의 래퍼입니다.
+<br>
 
-```ts
-const symbols = ledger.getSymbolsByFile('src/app.ts');
-if (!isErr(symbols)) {
-  for (const sym of symbols) {
-    console.log(`${sym.kind}: ${sym.name}`);
-  }
-}
-```
+## ⚠️ 에러 타입
 
-**반환**: `Result<SymbolSearchResult[], GildashError>`
+| 타입 | 발생 시점 |
+|------|----------|
+| `watcher` | 파일 워처 시작/중지 실패 |
+| `parse` | AST 파싱 실패 |
+| `extract` | 심볼/관계 추출 실패 |
+| `index` | 인덱싱 파이프라인 실패 |
+| `store` | DB 연산 실패 |
+| `search` | 검색 쿼리 실패 |
+| `closed` | 종료된 인스턴스에서 연산 시도 |
+| `validation` | 잘못된 입력 (e.g. `node_modules`에 패키지 없음) |
+| `close` | 종료 중 에러 |
 
 <br>
 
@@ -433,19 +377,19 @@ if (!isErr(symbols)) {
 ```
 Gildash (파사드)
 ├── Parser      — oxc-parser 기반 TypeScript AST 파싱
-├── Extractor   — 심볼/관계 추출 (imports, calls, heritage)
-├── Store       — bun:sqlite + drizzle-orm (files, symbols, relations, FTS5)
-├── Indexer     — 변경 감지 → 파싱 → 추출 → 저장 파이프라인
-├── Search      — 심볼 검색, 관계 검색, 의존성 그래프
+├── Extractor   — 심볼/관계 추출 (imports, re-exports, type-refs, calls, heritage)
+├── Store       — bun:sqlite + drizzle-orm (files · symbols · relations · FTS5)
+├── Indexer     — 파일 변경 → 파싱 → 추출 → 저장 파이프라인, 심볼 레벨 diff
+├── Search      — FTS + regex + decorator 검색, 관계 쿼리, 의존성 그래프, ast-grep
 └── Watcher     — @parcel/watcher + owner/reader 역할 관리
 ```
 
 ### Owner/Reader 패턴
 
-동일 SQLite DB를 여러 프로세스가 공유할 때, 단일 writer를 보장합니다.
+동일 SQLite DB를 여러 프로세스가 공유할 때, 단일 writer를 보장합니다:
 
-- **Owner** — watcher 실행, 인덱싱 수행, heartbeat 전송 (30초 간격)
-- **Reader** — 읽기 전용 접근, 60초 간격으로 owner 상태 확인; owner가 stale 상태가 되면 reader 중 하나가 owner로 승격
+- **Owner** — 파일 워처 실행, 인덱싱 수행, 30초 간격으로 heartbeat 전송
+- **Reader** — 읽기 전용 접근; 60초 간격으로 owner 상태 확인, owner가 stale 상태가 되면 reader 중 하나가 owner로 승격
 
 <br>