@zipbul/gildash 0.8.2 → 0.9.1

package/README.ko.md

@@ -30,6 +30,8 @@ gildash는 TypeScript 코드베이스를 로컬 SQLite 데이터베이스에 인
 - **구조적 패턴 매칭** — [@ast-grep/napi](https://ast-grep.github.io/) 기반 AST 레벨 코드 검색
 - **증분 인덱싱** — `@parcel/watcher` 기반 파일 변경 감지, 변경된 파일만 재인덱싱
 - **심볼 레벨 diff** — `IndexResult`의 `changedSymbols`로 인덱싱 사이클 당 추가/수정/삭제된 심볼 추적
+- **어노테이션 추출** — JSDoc, 라인(`//`), 블록(`/* */`) 주석에서 `@tag value` 패턴을 추출하고 심볼에 자동 연결, FTS5 검색 지원
+- **심볼 변경 이력** — 인덱싱 사이클 간 심볼의 추가/수정/삭제/이름변경/이동을 추적, 구조적 지문 기반 rename 감지
 - **멀티 프로세스 안전** — owner/reader 역할 분리로 단일 writer 보장
 - **스캔 전용 모드** — `watchMode: false`로 파일 워처 없이 1회성 인덱싱
 - **tsconfig.json JSONC** — `tsconfig.json`의 주석(`//`, `/* */`)과 트레일링 콤마를 지원하는 경로 별칭 파싱
@@ -416,6 +418,32 @@ Gildash (파사드)
 
 ## ⬆️ 업그레이드
 
+### 0.9.0 → 0.9.1
+
+**버그 수정 및 성능 개선.** API 호환성 변경 없음.
+
+- **수정:** `getParsedAst()`가 인스턴스 닫힌 상태에서 `GildashError('closed')` throw (기존: `undefined` 반환)
+- **수정:** `searchSymbols({ regex })`에 잘못된 regex 전달 시 `GildashError('validation')` throw (기존: `[]` 반환)
+- **수정:** reader→owner 승격 시 `ctx.role`이 `'owner'`로 정상 갱신
+- **수정:** Full-index 경로에서 파일 읽기 실패 시 `IndexResult.failedFiles`에 정상 추적
+- **수정:** reader→owner 승격 실패 rollback에서 heartbeat 타이머 정리 및 watcher role 해제
+- **성능:** 심볼/어노테이션/체인지로그 repository 배치 INSERT (N+1 개별 insert 제거)
+- **성능:** JSDoc 코멘트 탐색에 binary search 도입 (대형 파일에서 ~40x 개선)
+- **성능:** regex 검색 시 progressive fetch 전략 (고정 5000행 over-fetch 제거)
+- **성능:** `getQualifiedName()` O(n²) unshift → push+reverse O(n)
+
+### 0.8.x → 0.9.0
+
+**신규:** 어노테이션 추출 및 심볼 체인지로그 추적.
+
+- `searchAnnotations(query)` — JSDoc, 라인, 블록 코멘트에서 `@tag value` 검색
+- `getSymbolChanges(since, opts?)` — 심볼 레벨 변경 이력 (rename/move 감지 포함)
+- `pruneChangelog(before)` — 오래된 체인지로그 항목 정리
+- `IndexResult`에 `totalAnnotations` 필드 추가
+- 마이그레이션 `0006_annotations`, `0007_symbol_changelog` 자동 적용
+
+**호환성 변경 없음.** 기존 데이터베이스는 자동 마이그레이션됩니다.
+
 ### 0.7.x → 0.8.0
 
 **Breaking:** `batchParse()`가 `Map<string, ParsedFile>` 대신 `BatchParseResult` (`parsed` + `failures` 필드)를 반환합니다.

package/README.md

@@ -30,6 +30,8 @@ gildash indexes your TypeScript codebase into a local SQLite database, then lets
 - **Structural pattern matching** — AST-level code search via [@ast-grep/napi](https://ast-grep.github.io/)
 - **Incremental indexing** — `@parcel/watcher`-based file change detection; only re-indexes modified files
 - **Symbol-level diff** — `changedSymbols` in `IndexResult` tracks added/modified/removed symbols per index cycle
+- **Annotation extraction** — Generic `@tag value` extraction from JSDoc, line, and block comments with automatic symbol linking and FTS5 search
+- **Symbol changelog** — Tracks added/modified/removed/renamed/moved symbols across index runs, with structural fingerprint-based rename detection
 - **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
 - **tsconfig.json JSONC** — Path alias resolution parses comments and trailing commas in `tsconfig.json`
@@ -140,6 +142,45 @@ const limited   = await ledger.getCyclePaths(undefined, { maxCycles: 100 }); //
 
 ---
 
+### Annotations
+
+Search `@tag value` patterns extracted from JSDoc, line (`//`), and block (`/* */`) comments.
+
+```ts
+// Find all @deprecated annotations
+const deprecated = ledger.searchAnnotations({ tag: 'deprecated' });
+deprecated.forEach(a => console.log(`${a.symbolName}: ${a.value}`));
+
+// Full-text search across annotation values
+const caching = ledger.searchAnnotations({ text: 'caching' });
+
+// Filter by source type and file
+const todos = ledger.searchAnnotations({ tag: 'todo', source: 'line', filePath: 'src/app.ts' });
+```
+
+---
+
+### Symbol Changelog
+
+Track symbol-level changes across index runs. Rename and move detection uses structural fingerprinting.
+
+```ts
+// Get all incremental changes since a given date
+const changes = ledger.getSymbolChanges(new Date('2024-01-01'));
+
+// Include full-index entries and filter by change type
+const renames = ledger.getSymbolChanges(new Date(0), {
+  includeFullIndex: true,
+  changeTypes: ['renamed', 'moved'],
+});
+renames.forEach(c => console.log(`${c.oldName} → ${c.symbolName} (${c.changeType})`));
+
+// Prune old entries (returns deleted count)
+const pruned = ledger.pruneChangelog(new Date('2024-01-01'));
+```
+
+---
+
 ### Code Quality Analysis
 
 Inspect module interfaces and measure coupling.
@@ -272,6 +313,19 @@ Returns `Promise<Gildash>`. Throws `GildashError` on failure.
 | `getInternalRelations(filePath)` | `StoredCodeRelation[]` | Intra-file relations |
 | `diffSymbols(before, after)` | `SymbolDiff` | Snapshot diff (added / removed / modified) |
 
+### Annotations
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `searchAnnotations(query)` | `AnnotationSearchResult[]` | Search `@tag value` annotations in JSDoc, line, and block comments |
+
+### Symbol Changelog
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getSymbolChanges(since, opts?)` | `SymbolChange[]` | Symbol-level change history (added/modified/removed/renamed/moved) |
+| `pruneChangelog(before)` | `number` | Delete changelog entries older than the given date |
+
 ### Semantic (opt-in)
 
 Requires `semantic: true` at open time.
@@ -452,6 +506,7 @@ interface IndexResult {
   removedFiles: number;
   totalSymbols: number;
   totalRelations: number;
+  totalAnnotations: number;
   durationMs: number;
   changedFiles: string[];
   deletedFiles: string[];
@@ -473,6 +528,55 @@ interface FileRecord {
   lineCount?: number | null;
 }
 
+// ── Annotations ─────────────────────────────────────────────────────────
+
+interface AnnotationSearchQuery {
+  text?: string;       // FTS5 full-text query
+  tag?: string;        // exact tag name (e.g. 'deprecated', 'todo')
+  filePath?: string;
+  symbolName?: string;
+  source?: 'jsdoc' | 'line' | 'block';
+  project?: string;
+  limit?: number;      // default: 100
+}
+
+interface AnnotationSearchResult {
+  tag: string;
+  value: string;
+  source: 'jsdoc' | 'line' | 'block';
+  filePath: string;
+  symbolName: string | null;
+  span: { start: { line: number; column: number }; end: { line: number; column: number } };
+}
+
+// ── Symbol Changelog ────────────────────────────────────────────────────
+
+type SymbolChangeType = 'added' | 'modified' | 'removed' | 'renamed' | 'moved';
+
+interface SymbolChange {
+  changeType: SymbolChangeType;
+  symbolName: string;
+  symbolKind: string;
+  filePath: string;
+  oldName: string | null;       // set for 'renamed'
+  oldFilePath: string | null;   // set for 'moved'
+  fingerprint: string | null;
+  changedAt: string;
+  isFullIndex: boolean;
+  indexRunId: string;
+}
+
+interface SymbolChangeQueryOptions {
+  symbolName?: string;
+  changeTypes?: SymbolChangeType[];
+  filePath?: string;
+  includeFullIndex?: boolean;   // default: false
+  indexRunId?: string;
+  afterId?: number;             // pagination cursor
+  limit?: number;               // default: 1000
+  project?: string;
+}
+
 // ── Errors ──────────────────────────────────────────────────────────────
 
 class GildashError extends Error {
@@ -527,6 +631,32 @@ When multiple processes share the same SQLite database, gildash enforces a singl
 
 ## ⬆️ Upgrading
 
+### From 0.9.0 to 0.9.1
+
+**Bug fixes and performance improvements.** No breaking API changes.
+
+- **Fix:** `getParsedAst()` now throws `GildashError('closed')` when the instance is closed, consistent with all other public APIs (previously returned `undefined`)
+- **Fix:** `searchSymbols({ regex })` with an invalid regex now throws `GildashError('validation')` instead of silently returning `[]`
+- **Fix:** `ctx.role` is now correctly updated to `'owner'` when a reader is promoted
+- **Fix:** Full-index path now properly tracks failed file reads in `IndexResult.failedFiles`
+- **Fix:** Reader→Owner promotion rollback now cleans up heartbeat timer and releases watcher role
+- **Perf:** Batch INSERT for symbol, annotation, and changelog repositories (replaces N+1 individual inserts)
+- **Perf:** Binary search for JSDoc comment association (~40x faster on large files)
+- **Perf:** Progressive regex fetch strategy (replaces fixed 5000-row over-fetch)
+- **Perf:** `getQualifiedName()` uses push+reverse instead of O(n²) unshift
+
+### From 0.8.x to 0.9.0
+
+**New:** Annotation extraction and symbol changelog tracking.
+
+- `searchAnnotations(query)` — Search `@tag value` from JSDoc, line, and block comments
+- `getSymbolChanges(since, opts?)` — Symbol-level change history with rename/move detection
+- `pruneChangelog(before)` — Prune old changelog entries
+- `IndexResult` now includes `totalAnnotations`
+- New migrations `0006_annotations` and `0007_symbol_changelog` are applied automatically on open
+
+**No breaking changes.** Existing databases are migrated automatically.
+
 ### From 0.7.x to 0.8.0
 
 **Breaking:** `batchParse()` now returns `BatchParseResult` (with `parsed` and `failures` fields) instead of `Map<string, ParsedFile>`.