@zipbul/gildash 0.26.0 → 0.27.0

package/README.ko.md

@@ -260,7 +260,8 @@ try {
 | `hasCycle(project?)` | `Promise<boolean>` | 순환 의존성 감지 |
 | `getCyclePaths(project?, opts?)` | `Promise<string[][]>` | 모든 순환 경로 (Tarjan SCC + Johnson's). `opts.maxCycles`로 개수 제한 가능. |
 | `getImportGraph(project?)` | `Promise<Map>` | 전체 인접 리스트 |
-| `getTransitiveDependencies(filePath)` | `Promise<string[]>` | 전방 전이적 BFS |
+| `getTransitiveDependencies(filePath)` | `Promise<string[]>` | 전방 전이적 BFS (이 파일이 의존하는 파일들) |
+| `getTransitiveDependents(filePath)` | `Promise<string[]>` | 역방향 전이적 BFS (이 파일에 의존하는 파일들) |
 
 ### 분석
 
@@ -277,12 +278,40 @@ try {
 
 `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 |
+| `isTypeAssignableTo(opts)` | `boolean` | 두 심볼 타입 간 할당 가능성 |
+| `isTypeAssignableToType(opts)` | `boolean` | 심볼 타입을 임의 타입 문자열에 할당 가능한지 |
+
+#### 라인/컬럼 또는 바이트 위치 기반
+
+| 메서드 | 반환 타입 | 설명 |
+|--------|-----------|------|
+| `getResolvedTypeAt(filePath, line, column)` | `ResolvedType \| null` | 라인/컬럼 위치의 resolved type |
+| `isTypeAssignableToAt(opts)` | `boolean` | 두 라인/컬럼 위치 간 할당 가능성 |
+| `getResolvedTypeAtPosition(filePath, position)` | `ResolvedType \| null` | 바이트 위치의 resolved type |
+| `getResolvedTypesAtPositions(filePath, positions)` | `Map<number, ResolvedType>` | 여러 위치의 resolved type 일괄 조회 |
+| `getSemanticReferencesAtPosition(filePath, position)` | `SemanticReference[]` | 바이트 위치 심볼의 참조 |
+| `getImplementationsAtPosition(filePath, position)` | `Implementation[]` | 바이트 위치 심볼의 구현체 |
+| `isTypeAssignableToAtPosition(opts)` | `boolean` | 두 바이트 위치 간 할당 가능성 |
+| `isTypeAssignableToTypeAtPositions(opts)` | `boolean` | 위치 → 임의 타입 문자열 할당 가능성 |
+
+#### 파일 단위 / 유틸 / 진단
+
+| 메서드 | 반환 타입 | 설명 |
+|--------|-----------|------|
+| `getFileTypes(filePath)` | `Map<number, ResolvedType>` | 파일 내 모든 심볼의 resolved type |
+| `getSymbolNode(filePath, position)` | `SymbolNode \| null` | 위치의 심볼 그래프 노드 |
+| `getBaseTypes(filePath, position)` | `ResolvedType[] \| null` | 위치 심볼의 직접 베이스 타입들 |
+| `lineColumnToPosition(filePath, line, column)` | `number \| null` | 라인/컬럼 → 바이트 오프셋 변환 |
+| `findNamePosition(filePath, declarationPos, name)` | `number \| null` | 선언 내 식별자의 바이트 위치 탐색 |
+| `getSemanticDiagnostics(filePath, opts?)` | `SemanticDiagnostic[]` | 파일의 tsc 진단 |
 
 `getFullSymbol()`은 semantic 활성 시 자동으로 `resolvedType` 필드를 보강합니다.
 `searchSymbols({ resolvedType })`로 resolved type 문자열 기반 필터링이 가능합니다.
@@ -331,23 +360,37 @@ interface SymbolSearchQuery {
   filePath?: string;    // 파일 경로 필터
   isExported?: boolean; // export 여부
   project?: string;     // 프로젝트 이름
-  limit?: number;       // 최대 결과 수 (기본값: 100)
+  limit?: number;       // 미지정 시 limit 미적용 (전체 결과)
   decorator?: string;   // 데코레이터 이름 필터
   regex?: string;       // 정규식 패턴 필터
+  resolvedType?: string;  // 시맨틱 레이어 필터 (`semantic: true` 필요)
 }
 
 interface CodeRelation {
   type: 'imports' | 'type-references' | 're-exports' | 'calls' | 'extends' | 'implements';
   srcFilePath: string;
   srcSymbolName: string | null;
-  dstFilePath: string;
+  /** 외부 패키지 / 미해상 import 의 경우 `null`. */
+  dstFilePath: string | null;
   dstSymbolName: string | null;
   meta?: Record<string, unknown>;
+  /**
+   * 소스에 적힌 모듈 specifier 원문(`'./foo'`, `'@zipbul/core'`, `'lodash'`).
+   * 모듈 source 가 있는 모든 관계(`'imports'`, `'re-exports'`, `'type-references'`,
+   * 동적 `import()`, `require()`)에서 `dstFilePath` 해상 여부와 무관하게 항상 보존.
+   * `'calls'` / `'extends'` / `'implements'` 관계에서만 부재.
+   */
+  specifier?: string;
 }
 
-/** 목적지 프로젝트 식별자가 추가된 CodeRelation */
-interface StoredCodeRelation extends CodeRelation {
-  dstProject: string;
+/** 목적지 프로젝트 식별자와 외부 플래그가 추가된 CodeRelation. */
+interface StoredCodeRelation extends Omit<CodeRelation, 'specifier'> {
+  /** 목적지 프로젝트, 또는 cross-project / 미해상 시 `null`. */
+  dstProject: string | null;
+  /** 외부 패키지(bare specifier) 여부. */
+  isExternal: boolean;
+  /** 원문 specifier (`CodeRelation.specifier` 참고); `'calls'` / `'extends'` / `'implements'` 에서만 `null`. */
+  specifier: string | null;
 }
 
 interface IndexResult {
@@ -355,14 +398,25 @@ interface IndexResult {
   removedFiles: number;
   totalSymbols: number;
   totalRelations: number;
+  totalAnnotations: number;
   durationMs: number;
   changedFiles: string[];
   deletedFiles: string[];
   failedFiles: string[];
+  /** 이전 인덱스 상태 대비 심볼 단위 diff. */
   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 }>;
+    added: Array<{ name: string; filePath: string; kind: string; isExported: boolean }>;
+    modified: Array<{ name: string; filePath: string; kind: string; isExported: boolean }>;
+    removed: Array<{ name: string; filePath: string; kind: string; isExported: boolean }>;
+  };
+  /** 이름이 바뀐 심볼 (구조적 fingerprint 매칭). */
+  renamedSymbols: Array<{ oldName: string; newName: string; filePath: string; kind: string; isExported: boolean }>;
+  /** 다른 파일로 이동한 심볼 (incremental 만; fingerprint 매칭). */
+  movedSymbols: Array<{ name: string; oldFilePath: string; newFilePath: string; kind: string; isExported: boolean }>;
+  /** 이전 인덱스 상태 대비 관계 단위 diff. */
+  changedRelations: {
+    added: Array<{ type: string; srcFilePath: string; dstFilePath: string | null; srcSymbolName: string | null; dstSymbolName: string | null; dstProject: string | null; metaJson: string | null }>;
+    removed: Array<{ type: string; srcFilePath: string; dstFilePath: string | null; srcSymbolName: string | null; dstSymbolName: string | null; dstProject: string | null; metaJson: string | null }>;
   };
 }
 

package/README.md

@@ -300,7 +300,8 @@ Returns `Promise<Gildash>`. Throws `GildashError` on failure.
 | `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 |
+| `getTransitiveDependencies(filePath)` | `Promise<string[]>` | Forward transitive BFS (files this depends on) |
+| `getTransitiveDependents(filePath)` | `Promise<string[]>` | Reverse transitive BFS (files that depend on this) |
 
 ### Analysis
 
@@ -330,12 +331,40 @@ Returns `Promise<Gildash>`. Throws `GildashError` on failure.
 
 Requires `semantic: true` at open time.
 
+#### By symbol name
+
 | 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 |
+| `isTypeAssignableTo(opts)` | `boolean` | Whether one symbol's type is assignable to another's |
+| `isTypeAssignableToType(opts)` | `boolean` | Whether a symbol's type is assignable to an arbitrary type string |
+
+#### By line/column or byte position
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getResolvedTypeAt(filePath, line, column)` | `ResolvedType \| null` | Resolved type at a line/column |
+| `isTypeAssignableToAt(opts)` | `boolean` | Assignability check between two line/column positions |
+| `getResolvedTypeAtPosition(filePath, position)` | `ResolvedType \| null` | Resolved type at a byte position |
+| `getResolvedTypesAtPositions(filePath, positions)` | `Map<number, ResolvedType>` | Batch type lookup across positions |
+| `getSemanticReferencesAtPosition(filePath, position)` | `SemanticReference[]` | References to the symbol at a position |
+| `getImplementationsAtPosition(filePath, position)` | `Implementation[]` | Implementations of the symbol at a position |
+| `isTypeAssignableToAtPosition(opts)` | `boolean` | Assignability check between two byte positions |
+| `isTypeAssignableToTypeAtPositions(opts)` | `boolean` | Assignability check from a position to an arbitrary type string |
+
+#### File-level / utilities / diagnostics
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getFileTypes(filePath)` | `Map<number, ResolvedType>` | All resolved types for symbols in a file |
+| `getSymbolNode(filePath, position)` | `SymbolNode \| null` | Underlying symbol-graph node at a position |
+| `getBaseTypes(filePath, position)` | `ResolvedType[] \| null` | Direct base types of the symbol at a position |
+| `lineColumnToPosition(filePath, line, column)` | `number \| null` | Convert line/column to byte offset |
+| `findNamePosition(filePath, declarationPos, name)` | `number \| null` | Locate an identifier's byte offset within a declaration |
+| `getSemanticDiagnostics(filePath, opts?)` | `SemanticDiagnostic[]` | tsc diagnostics for a file |
 
 `getFullSymbol()` automatically enriches the result with a `resolvedType` field when semantic is enabled.
 `searchSymbols({ resolvedType })` filters symbols by their resolved type string.
@@ -361,12 +390,77 @@ Requires `semantic: true` at open time.
 | `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)` | `FileRecord \| null` | File metadata (hash, mtime, size) |
 | `getStats(project?)` | `SymbolStats` | Symbol / file count statistics |
 | `projects` | `ProjectBoundary[]` | Discovered project boundaries |
 | `close(opts?)` | `Promise<void>` | Shutdown (pass `{ cleanup: true }` to delete DB) |
 
+### AST Primitives
+
+gildash exposes the underlying oxc-parser AST surface and a set of helpers
+for consumers building their own static analysis on top of the same parser.
+These are standalone exports — no `Gildash` instance required — and follow
+the upstream oxc-parser / oxc-walker semver.
+
+#### Parsing & extraction
+
+| Export | Returns | Description |
+|--------|---------|-------------|
+| `parseSource(file, src, opts?)` | `Result<ParsedFile, GildashError>` | Parse a single source string |
+| `extractSymbols(parsed)` | `ExtractedSymbol[]` | Symbols from a parsed AST |
+| `extractRelations(ast, file, ...)` | `CodeRelation[]` | Relations from a parsed AST |
+
+#### Traversal
+
+Re-exported from `oxc-walker` and `oxc-parser`:
+
+| Export | Description |
+|--------|-------------|
+| `walk(node, { enter, leave })` | Generic preorder walker. `enter` receives `(node, parent, ctx)`; call `this.skip()` to prune the subtree. |
+| `parseAndWalk(code, file, cb)` | Parse + walk in one call |
+| `ScopeTracker` | Identifier-declaration tracker that integrates with `walk` |
+| `Visitor` | Per-node-type callback object form (`new Visitor({ CallExpression(...) })`) |
+| `visitorKeys` | `Record<string, string[]>` — child key list per node type |
+
+#### Type predicates over `Node`
+
+Each predicate has the signature `(node: Node) => node is Extract<Node, { type: 'X' }>`.
+
+| Predicate | Discriminator | Notes |
+|-----------|---------------|-------|
+| `isArrowFunctionExpression` | `ArrowFunctionExpression` | |
+| `isAssignmentExpression` | `AssignmentExpression` | |
+| `isCallExpression` | `CallExpression` | |
+| `isFunctionDeclaration` | `FunctionDeclaration` | Narrows to the `Function` interface, which structurally also accepts `TSDeclareFunction` and `TSEmptyBodyFunctionExpression` literals — those return `false` at runtime. |
+| `isFunctionExpression` | `FunctionExpression` | Same `Function`-interface caveat as above. |
+| `isFunctionNode` | `FunctionDeclaration` \| `FunctionExpression` \| `ArrowFunctionExpression` | Union shorthand for "any function-shape node". |
+| `isIdentifier` | `Identifier` | 6-way collision: `IdentifierName`, `IdentifierReference`, `BindingIdentifier`, `LabelIdentifier`, `TSThisParameter`, `TSIndexSignatureName`. All expose `.name`. |
+| `isMemberExpression` | `MemberExpression` | 3-way collision: `ComputedMemberExpression`, `StaticMemberExpression`, `PrivateFieldExpression`. All expose `.object`. |
+| `isTSQualifiedName` | `TSQualifiedName` | 2-way collision: `TSQualifiedName`, `TSImportTypeQualifiedName`. Both expose `.left` / `.right` (different shapes). |
+| `isVariableDeclaration` | `VariableDeclaration` | |
+
+```ts
+import { parseSource, walk, isCallExpression } from '@zipbul/gildash';
+
+const parsed = parseSource('a.ts', 'foo()');
+if (!('stack' in parsed)) {
+  walk(parsed.program, {
+    enter(node) {
+      if (isCallExpression(node)) {
+        console.log(node.callee, node.arguments);
+      }
+    },
+  });
+}
+```
+
+#### AST utility types
+
+`Program`, `Node`, `VisitorObject`, `WalkOptions`, `WalkerEnter`, `WalkerLeave`, `WalkerCallbackContext`, `ScopeTrackerNode`, `ScopeTrackerOptions`, `SourcePosition`, `SourceSpan`, `ParsedFile`, plus `buildLineOffsets` / `getLineColumn` for byte ↔ line/column conversion.
+
 <br>
 
 <details>
@@ -378,70 +472,131 @@ Requires `semantic: true` at open time.
 interface SymbolSearchQuery {
   text?: string;        // FTS5 full-text query
   exact?: boolean;      // exact name match (not prefix)
-  kind?: SymbolKind;    // 'function' | 'method' | 'class' | 'variable' | 'type' | 'interface' | 'enum' | 'property'
+  kind?: SymbolKind;    // 'function' | 'method' | 'class' | 'variable' | 'type' | 'interface' | 'enum' | 'namespace' | 'property'
   filePath?: string;
   isExported?: boolean;
   project?: string;
-  limit?: number;       // default: 100
+  limit?: number;       // when omitted, no limit is applied
   decorator?: string;   // e.g. 'Injectable'
   regex?: string;       // regex applied to symbol name
+  resolvedType?: string;  // semantic-layer filter; requires `semantic: true`
 }
 
 interface SymbolSearchResult {
   id: number;
   filePath: string;
   kind: SymbolKind;
-  name: string;
+  name: string;                    // qualified for members, e.g. "ClassName.methodName"
+  memberName: string | null;       // unqualified member name, or null for top-level
   span: { start: { line: number; column: number }; end: { line: number; column: number } };
   isExported: boolean;
   signature: string | null;
   fingerprint: string | null;
-  detail: Record<string, unknown>;
+  detail: SymbolDetail;            // typed; see below
 }
 
+interface SymbolDetail {
+  parameters?: Parameter[];
+  returnType?: string;
+  heritage?: Array<{ kind: 'extends' | 'implements'; name: string; typeArguments?: string[] }>;
+  decorators?: Decorator[];
+  typeParameters?: string[];
+  modifiers?: Modifier[];
+  initializer?: ExpressionValue;
+  members?: Array<{
+    name: string;
+    kind: string;
+    type?: string;
+    visibility?: string;
+    isStatic?: boolean;
+    isReadonly?: boolean;
+    initializer?: ExpressionValue;
+    decorators?: Decorator[];
+  }>;
+  jsDoc?: JsDocBlock;
+}
+
+interface Parameter {
+  name: string;
+  type?: string;                   // type annotation as source text
+  typeImportSource?: string;       // import specifier when the type is imported
+  isOptional: boolean;
+  defaultValue?: string;
+  decorators?: Decorator[];
+}
+
+interface Decorator {
+  name: string;
+  arguments?: ExpressionValue[];   // structured decorator call arguments
+}
+
+type Modifier =
+  | 'async' | 'static' | 'abstract' | 'readonly'
+  | 'private' | 'protected' | 'public'
+  | 'override' | 'declare' | 'const'
+  | 'accessor';                    // TC39 auto-accessor
+
 interface RelationSearchQuery {
   srcFilePath?: string;
   srcSymbolName?: string;
   dstFilePath?: string;
   dstSymbolName?: string;
-  dstProject?: string;  // filter by destination project
+  dstProject?: string;            // filter by destination project
+  /** Glob (Bun.Glob) for source file path; mutually exclusive with srcFilePath. */
+  srcFilePathPattern?: string;
+  /** Glob (Bun.Glob) for destination file path; mutually exclusive with dstFilePath. */
+  dstFilePathPattern?: string;
   type?: 'imports' | 'type-references' | 're-exports' | 'calls' | 'extends' | 'implements';
   project?: string;
-  limit?: number;       // default: 500
+  /** Filter by raw import specifier (e.g. `'./foo'`, `'lodash'`). */
+  specifier?: string;
+  /** Filter by external (bare specifier) flag. */
+  isExternal?: boolean;
+  limit?: number;                 // when omitted, no limit is applied
 }
 
 interface CodeRelation {
   type: 'imports' | 'type-references' | 're-exports' | 'calls' | 'extends' | 'implements';
   srcFilePath: string;
   srcSymbolName: string | null;
-  dstFilePath: string;
+  /** `null` when the import target could not be resolved (external package, missing file). */
+  dstFilePath: string | null;
   dstSymbolName: string | null;
   metaJson?: string;
   meta?: Record<string, unknown>;   // auto-parsed from metaJson
+  /**
+   * Verbatim module specifier text as written in the source (`'./foo'`,
+   * `'@zipbul/core'`, `'lodash'`). Always present on module-source-bearing
+   * relations (`'imports'`, `'re-exports'`, `'type-references'`, dynamic
+   * `import()`, `require()`) regardless of `dstFilePath` resolution.
+   * Absent on `'calls'` / `'extends'` / `'implements'`.
+   */
+  specifier?: string;
 }
 
-/** CodeRelation enriched with the destination project identifier. */
-interface StoredCodeRelation extends CodeRelation {
-  dstProject: string;
+/** CodeRelation enriched with destination-project identifier and external flag. */
+interface StoredCodeRelation extends Omit<CodeRelation, 'specifier'> {
+  /** Destination project, or `null` for cross-project / unresolved relations. */
+  dstProject: string | null;
+  /** Whether the relation targets an external (bare-specifier) package. */
+  isExternal: boolean;
+  /** Verbatim source specifier (see {@link CodeRelation.specifier}); `null` only on `'calls'` / `'extends'` / `'implements'`. */
+  specifier: string | null;
 }
 
 // ── Analysis ────────────────────────────────────────────────────────────
 
 interface FullSymbol extends SymbolSearchResult {
-  members?: Array<{
-    name: string;
-    kind: string;
-    type?: string;
-    visibility?: string;
-    isStatic?: boolean;
-    isReadonly?: boolean;
-  }>;
-  jsDoc?: string;
-  parameters?: string;
+  members?: SymbolDetail['members'];
+  jsDoc?: JsDocBlock;
+  parameters?: Parameter[];
   returnType?: string;
-  heritage?: string[];
-  decorators?: Array<{ name: string; arguments?: string }>;
-  typeParameters?: string;
+  heritage?: SymbolDetail['heritage'];
+  decorators?: Decorator[];
+  typeParameters?: string[];
+  initializer?: ExpressionValue;
+  /** Resolved type from the Semantic Layer (available when `semantic: true`). */
+  resolvedType?: ResolvedType;
 }
 
 interface FileStats {
@@ -511,10 +666,48 @@ interface IndexResult {
   changedFiles: string[];
   deletedFiles: string[];
   failedFiles: string[];
+  /** Symbol-level diff against previous index state. */
   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 }>;
+    added: Array<{ name: string; filePath: string; kind: string; isExported: boolean }>;
+    modified: Array<{ name: string; filePath: string; kind: string; isExported: boolean }>;
+    removed: Array<{ name: string; filePath: string; kind: string; isExported: boolean }>;
+  };
+  /** Symbols renamed (matched via structural fingerprint). */
+  renamedSymbols: Array<{
+    oldName: string;
+    newName: string;
+    filePath: string;
+    kind: string;
+    isExported: boolean;
+  }>;
+  /** Symbols that moved to a different file (incremental only; matched via fingerprint). */
+  movedSymbols: Array<{
+    name: string;
+    oldFilePath: string;
+    newFilePath: string;
+    kind: string;
+    isExported: boolean;
+  }>;
+  /** Relation-level diff against previous index state. */
+  changedRelations: {
+    added: Array<{
+      type: string;
+      srcFilePath: string;
+      dstFilePath: string | null;
+      srcSymbolName: string | null;
+      dstSymbolName: string | null;
+      dstProject: string | null;
+      metaJson: string | null;
+    }>;
+    removed: Array<{
+      type: string;
+      srcFilePath: string;
+      dstFilePath: string | null;
+      srcSymbolName: string | null;
+      dstSymbolName: string | null;
+      dstProject: string | null;
+      metaJson: string | null;
+    }>;
   };
 }
 
@@ -537,7 +730,7 @@ interface AnnotationSearchQuery {
   symbolName?: string;
   source?: 'jsdoc' | 'line' | 'block';
   project?: string;
-  limit?: number;      // default: 100
+  limit?: number;      // when omitted, no limit is applied
 }
 
 interface AnnotationSearchResult {