opentology 0.1.1 → 0.2.0

package/README.md

@@ -22,7 +22,7 @@ graph TB
     end
 
     subgraph MCP["MCP Server"]
-        Tools[11 Tools]
+        Tools[18 Tools]
         Resource["opentology://schema"]
     end
 
@@ -97,7 +97,7 @@ graph LR
 | Docker required | No (embedded mode) | Yes | Yes |
 | RDFS reasoning | Automatic on push | Manual SPARQL CONSTRUCT | Not native |
 | SHACL validation | Built-in | Manual tooling | N/A |
-| AI integration | MCP server with 11 tools | None | Plugin ecosystem |
+| AI integration | MCP server with 18 tools | None | Plugin ecosystem |
 | Query language | SPARQL (auto-prefixed) | SPARQL (raw) | Cypher |
 | Data format | Turtle files | Turtle/N-Triples | Property graph |
 | Project scoping | Automatic named graphs | Manual | Database-level |
@@ -126,7 +126,7 @@ graph LR
 
 **AI Integration**
 
-- MCP server with 11 tools and 1 resource
+- MCP server with 18 tools and 1 resource
 - `opentology://schema` resource auto-loads ontology overview
 - Works with Claude Code, Cursor, and any MCP-compatible client
 
@@ -192,7 +192,7 @@ Add to your MCP client configuration (`.mcp.json`):
 }
 ```
 
-**11 Tools:**
+**18 Tools:**
 
 | Tool | Description |
 |------|-------------|
@@ -207,6 +207,13 @@ Add to your MCP client configuration (`.mcp.json`):
 | `opentology_diff` | Compare local vs graph |
 | `opentology_schema` | Introspect ontology schema |
 | `opentology_infer` | Run RDFS inference |
+| `opentology_graph_list` | List named graphs |
+| `opentology_graph_create` | Create a named graph |
+| `opentology_graph_drop` | Drop a named graph |
+| `opentology_context_init` | Initialize project context graph |
+| `opentology_context_load` | Load project context |
+| `opentology_context_status` | Check context initialization status |
+| `opentology_context_scan` | Scan codebase (module or symbol-level) |
 
 **1 Resource:**
 
@@ -270,6 +277,41 @@ opentology push data.ttl
 opentology shapes
 ```
 
+### Deep Scan (Symbol-Level Analysis)
+
+The `opentology_context_scan` MCP tool supports symbol-level deep scanning that extracts classes, interfaces, functions, and method call relationships from source code, then pushes them as OTX triples to the context graph.
+
+**Supported Languages:**
+
+| Language | Engine | Symbols Extracted |
+|----------|--------|-------------------|
+| TypeScript/JavaScript | ts-morph | class, interface, function, method calls |
+| Python | Tree-sitter | class, ABC/Protocol, function, method calls |
+| Go | Tree-sitter | struct, interface, func, method calls |
+| Rust | Tree-sitter | struct, trait, impl, fn, method calls |
+| Java | Tree-sitter | class, interface, method, method calls |
+| Swift | Tree-sitter | class, struct, protocol, func, method calls |
+
+**Optional Dependencies:**
+
+```bash
+# For TypeScript/JavaScript deep scan
+npm install ts-morph
+
+# For Python/Go/Rust/Java/Swift deep scan
+npm install web-tree-sitter tree-sitter-wasms
+```
+
+**Usage (MCP):**
+
+```json
+{
+  "depth": "symbol",
+  "includeMethodCalls": true,
+  "languages": ["typescript", "python"]
+}
+```
+
 ### Tech Stack
 
 - TypeScript, commander.js, n3.js
@@ -277,11 +319,13 @@ opentology shapes
 - @modelcontextprotocol/sdk for MCP server
 - shacl-engine for SHACL validation
 - picocolors for terminal output
+- ts-morph (optional) for TypeScript symbol analysis
+- web-tree-sitter + tree-sitter-wasms (optional) for multi-language symbol analysis
 
 ### Roadmap
 
 - [x] CLI with 14 commands
-- [x] MCP server with 11 tools and 1 resource
+- [x] MCP server with 18 tools and 1 resource
 - [x] Schema introspection (MCP resource + tool)
 - [x] Complete CRUD (push --replace, drop, delete)
 - [x] SHACL validation (shape constraints on push)
@@ -290,6 +334,7 @@ opentology shapes
 - [x] Prefix management
 - [x] Embedded mode (no Docker required)
 - [x] RDFS reasoning (auto-materialization on push)
+- [x] Multi-language deep scan (TypeScript, Python, Go, Rust, Java, Swift)
 - [ ] OWL reasoning (owl:sameAs, owl:inverseOf)
 - [ ] Remote ontology import
 - [ ] Version control for ontology snapshots
@@ -324,7 +369,7 @@ graph TB
     end
 
     subgraph MCP["MCP Server"]
-        Tools[11 Tools]
+        Tools[18 Tools]
         Resource["opentology://schema"]
     end
 
@@ -399,7 +444,7 @@ graph LR
 | Docker 필수 | 아니오 (임베디드 모드) | 예 | 예 |
 | RDFS 추론 | 푸시 시 자동 | SPARQL CONSTRUCT 수동 작성 | 네이티브 미지원 |
 | SHACL 검증 | 내장 | 별도 도구 필요 | 해당 없음 |
-| AI 연동 | MCP 서버 11개 도구 | 없음 | 플러그인 생태계 |
+| AI 연동 | MCP 서버 18개 도구 | 없음 | 플러그인 생태계 |
 | 쿼리 언어 | SPARQL (접두사 자동 삽입) | SPARQL (수동) | Cypher |
 | 데이터 형식 | Turtle 파일 | Turtle/N-Triples | 속성 그래프 |
 | 프로젝트 구분 | Named Graph 자동 | 수동 관리 | 데이터베이스 단위 |
@@ -428,7 +473,7 @@ graph LR
 
 **AI 연동**
 
-- 11개 도구와 1개 리소스를 제공하는 MCP 서버
+- 18개 도구와 1개 리소스를 제공하는 MCP 서버
 - `opentology://schema` 리소스로 온톨로지 개요 자동 로드
 - Claude Code, Cursor 등 MCP 호환 클라이언트와 연동
 
@@ -494,7 +539,7 @@ MCP 클라이언트 설정 파일(`.mcp.json`)에 추가:
 }
 ```
 
-**11개 도구:**
+**18개 도구:**
 
 | 도구 | 설명 |
 |------|------|
@@ -509,6 +554,13 @@ MCP 클라이언트 설정 파일(`.mcp.json`)에 추가:
 | `opentology_diff` | 로컬 파일과 그래프 비교 |
 | `opentology_schema` | 온톨로지 스키마 조회 |
 | `opentology_infer` | RDFS 추론 실행 |
+| `opentology_graph_list` | Named Graph 목록 조회 |
+| `opentology_graph_create` | Named Graph 생성 |
+| `opentology_graph_drop` | Named Graph 삭제 |
+| `opentology_context_init` | 프로젝트 컨텍스트 그래프 초기화 |
+| `opentology_context_load` | 프로젝트 컨텍스트 로드 |
+| `opentology_context_status` | 컨텍스트 초기화 상태 확인 |
+| `opentology_context_scan` | 코드베이스 스캔 (모듈/심볼 수준) |
 
 **1개 리소스:**
 
@@ -572,6 +624,41 @@ opentology push data.ttl
 opentology shapes
 ```
 
+### 딥스캔 (심볼 수준 분석)
+
+`opentology_context_scan` MCP 도구는 소스 코드에서 클래스, 인터페이스, 함수, 메서드 호출 관계를 추출하여 OTX 트리플로 컨텍스트 그래프에 푸시하는 심볼 수준 딥스캔을 지원합니다.
+
+**지원 언어:**
+
+| 언어 | 엔진 | 추출 심볼 |
+|------|------|-----------|
+| TypeScript/JavaScript | ts-morph | class, interface, function, method calls |
+| Python | Tree-sitter | class, ABC/Protocol, function, method calls |
+| Go | Tree-sitter | struct, interface, func, method calls |
+| Rust | Tree-sitter | struct, trait, impl, fn, method calls |
+| Java | Tree-sitter | class, interface, method, method calls |
+| Swift | Tree-sitter | class, struct, protocol, func, method calls |
+
+**선택적 의존성:**
+
+```bash
+# TypeScript/JavaScript 딥스캔
+npm install ts-morph
+
+# Python/Go/Rust/Java/Swift 딥스캔
+npm install web-tree-sitter tree-sitter-wasms
+```
+
+**사용법 (MCP):**
+
+```json
+{
+  "depth": "symbol",
+  "includeMethodCalls": true,
+  "languages": ["typescript", "python"]
+}
+```
+
 ### 기술 스택
 
 - TypeScript, commander.js, n3.js
@@ -579,11 +666,13 @@ opentology shapes
 - @modelcontextprotocol/sdk (MCP 서버)
 - shacl-engine (SHACL 검증)
 - picocolors (터미널 출력)
+- ts-morph (선택) TypeScript 심볼 분석
+- web-tree-sitter + tree-sitter-wasms (선택) 다중 언어 심볼 분석
 
 ### 로드맵
 
 - [x] 14개 CLI 명령어
-- [x] 11개 도구와 1개 리소스를 갖춘 MCP 서버
+- [x] 18개 도구와 1개 리소스를 갖춘 MCP 서버
 - [x] 스키마 조회 (MCP 리소스 + 도구)
 - [x] 완전한 CRUD (push --replace, drop, delete)
 - [x] SHACL 검증 (푸시 시 형상 제약 자동 검증)
@@ -592,6 +681,7 @@ opentology shapes
 - [x] 접두사 관리
 - [x] 임베디드 모드 (Docker 불필요)
 - [x] RDFS 추론 (푸시 시 자동 물질화)
+- [x] 다중 언어 딥스캔 (TypeScript, Python, Go, Rust, Java, Swift)
 - [ ] OWL 추론 (owl:sameAs, owl:inverseOf)
 - [ ] 원격 온톨로지 임포트
 - [ ] 온톨로지 스냅샷 버전 관리

package/dist/commands/viz.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerViz(program: Command): void;

package/dist/commands/viz.js

@@ -0,0 +1,53 @@
+import { loadConfig, resolveGraphUri } from '../lib/config.js';
+import { createReadyAdapter } from '../lib/store-factory.js';
+import { fromSchemaData, toMermaid, toDot } from '../lib/visualizer.js';
+import { writeFileSync } from 'fs';
+export function registerViz(program) {
+    const viz = program
+        .command('viz')
+        .description('Visualize graph data as Mermaid or DOT diagrams');
+    viz
+        .command('schema')
+        .description('Visualize the ontology schema (classes, properties, relationships)')
+        .option('--format <type>', 'Output format: mermaid, dot', 'mermaid')
+        .option('--output <file>', 'Write output to file instead of stdout')
+        .option('--graph <name>', 'Target a specific named graph')
+        .action(async (options) => {
+        let config;
+        try {
+            config = loadConfig();
+        }
+        catch (err) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        const graphUri = options.graph ? resolveGraphUri(config, options.graph) : config.graphUri;
+        const format = options.format || 'mermaid';
+        if (format !== 'mermaid' && format !== 'dot') {
+            console.error(`Error: unsupported format "${format}". Use "mermaid" or "dot".`);
+            process.exit(1);
+        }
+        try {
+            const adapter = await createReadyAdapter(config);
+            const overview = await adapter.getSchemaOverview(graphUri);
+            const relations = await adapter.getSchemaRelations(graphUri);
+            const visGraph = fromSchemaData(overview, relations);
+            const output = format === 'dot' ? toDot(visGraph) : toMermaid(visGraph);
+            if (options.output) {
+                writeFileSync(options.output, output, 'utf-8');
+                console.log(`Written to ${options.output}`);
+            }
+            else {
+                console.log(output);
+            }
+        }
+        catch (err) {
+            const message = err.message;
+            console.error(`Error: ${message}`);
+            if (message.includes('fetch failed') || message.includes('ECONNREFUSED')) {
+                console.error(`Cannot connect to triplestore at ${config.endpoint ?? 'unknown'}. Is it running?`);
+            }
+            process.exit(1);
+        }
+    });
+}

package/dist/index.js

@@ -15,6 +15,7 @@ import { registerGraph } from './commands/graph.js';
 import { registerInfer } from './commands/infer.js';
 import { registerPrefix } from './commands/prefix.js';
 import { registerContext } from './commands/context.js';
+import { registerViz } from './commands/viz.js';
 const program = new Command();
 program
     .name('opentology')
@@ -35,4 +36,5 @@ registerGraph(program);
 registerInfer(program);
 registerPrefix(program);
 registerContext(program);
+registerViz(program);
 program.parse(process.argv);

package/dist/lib/deep-scan-triples.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Converts DeepScanResult into OTX-compliant SPARQL INSERT DATA triples
+ * with batched insert and scoped delete-then-insert strategy.
+ */
+import type { DeepScanResult } from './deep-scanner.js';
+export declare function generateSymbolTriples(result: DeepScanResult): string[];
+export declare function batchTriples(triples: string[], batchSize?: number): string[][];
+export interface StoreAdapter {
+    sparqlUpdate(query: string): Promise<void>;
+}
+export declare function deleteExistingSymbols(adapter: StoreAdapter, graphUri: string, modulePaths: string[]): Promise<void>;
+export declare function pushSymbolTriples(adapter: StoreAdapter, graphUri: string, result: DeepScanResult): Promise<{
+    triplesInserted: number;
+    batchCount: number;
+}>;

package/dist/lib/deep-scan-triples.js

@@ -0,0 +1,120 @@
+/**
+ * Converts DeepScanResult into OTX-compliant SPARQL INSERT DATA triples
+ * with batched insert and scoped delete-then-insert strategy.
+ */
+const OTX = 'https://opentology.dev/vocab#';
+function encodeSegment(s) {
+    return encodeURIComponent(s);
+}
+function symbolUri(filePath, kind, name) {
+    return `urn:symbol:${encodeSegment(filePath)}/${encodeSegment(kind)}/${encodeSegment(name)}`;
+}
+function moduleUri(filePath) {
+    return `urn:module:${filePath}`;
+}
+function esc(s) {
+    return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+// ── Triple generation ───────────────────────────────────────────
+export function generateSymbolTriples(result) {
+    const triples = [];
+    for (const cls of result.classes) {
+        const uri = symbolUri(cls.filePath, 'class', cls.name);
+        triples.push(`<${uri}> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <${OTX}Class> .`);
+        triples.push(`<${uri}> <${OTX}title> "${esc(cls.name)}" .`);
+        triples.push(`<${uri}> <${OTX}definedIn> <${moduleUri(cls.filePath)}> .`);
+        if (cls.baseClass) {
+            // baseClass is already a qualified path like "src/lib/foo/class/Bar"
+            const parts = cls.baseClass.split('/');
+            const baseName = parts.pop();
+            const baseKind = parts.pop();
+            const basePath = parts.join('/');
+            const baseUri = symbolUri(basePath, baseKind, baseName);
+            triples.push(`<${uri}> <${OTX}extends> <${baseUri}> .`);
+        }
+        for (const iface of cls.interfaces) {
+            // interface is already qualified like "src/lib/foo/interface/Bar"
+            const parts = iface.split('/');
+            const ifaceName = parts.pop();
+            const ifaceKind = parts.pop();
+            const ifacePath = parts.join('/');
+            const ifaceUri = symbolUri(ifacePath, ifaceKind, ifaceName);
+            triples.push(`<${uri}> <${OTX}implements> <${ifaceUri}> .`);
+        }
+        for (const method of cls.methods) {
+            const methodUri = symbolUri(cls.filePath, 'method', `${cls.name}.${method.name}`);
+            triples.push(`<${methodUri}> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <${OTX}Method> .`);
+            triples.push(`<${methodUri}> <${OTX}title> "${esc(method.name)}" .`);
+            triples.push(`<${methodUri}> <${OTX}definedIn> <${moduleUri(cls.filePath)}> .`);
+            triples.push(`<${uri}> <${OTX}hasMethod> <${methodUri}> .`);
+            if (method.returnType && method.returnType !== 'void') {
+                triples.push(`<${methodUri}> <${OTX}returns> "${esc(method.returnType)}" .`);
+            }
+            for (const p of method.parameters) {
+                triples.push(`<${methodUri}> <${OTX}paramType> "${esc(p.name)}: ${esc(p.type)}" .`);
+            }
+        }
+    }
+    for (const iface of result.interfaces) {
+        const uri = symbolUri(iface.filePath, 'interface', iface.name);
+        triples.push(`<${uri}> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <${OTX}Interface> .`);
+        triples.push(`<${uri}> <${OTX}title> "${esc(iface.name)}" .`);
+        triples.push(`<${uri}> <${OTX}definedIn> <${moduleUri(iface.filePath)}> .`);
+        for (const ext of iface.extends) {
+            // Interface extends are just names (not fully qualified) for now
+            triples.push(`<${uri}> <${OTX}extends> "${esc(ext)}" .`);
+        }
+    }
+    for (const fn of result.functions) {
+        const uri = symbolUri(fn.filePath, 'function', fn.name);
+        triples.push(`<${uri}> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <${OTX}Function> .`);
+        triples.push(`<${uri}> <${OTX}title> "${esc(fn.name)}" .`);
+        triples.push(`<${uri}> <${OTX}definedIn> <${moduleUri(fn.filePath)}> .`);
+        if (fn.returnType && fn.returnType !== 'void') {
+            triples.push(`<${uri}> <${OTX}returns> "${esc(fn.returnType)}" .`);
+        }
+    }
+    for (const call of result.methodCalls) {
+        const callerParts = call.caller.split('.');
+        const calleeParts = call.callee.split('.');
+        // Method calls reference by class.method pattern — generate a simple triple
+        triples.push(`<urn:call:${encodeSegment(call.caller)}> <${OTX}calls> <urn:call:${encodeSegment(call.callee)}> .`);
+        // Store caller/callee names for queryability
+        triples.push(`<urn:call:${encodeSegment(call.caller)}> <${OTX}title> "${esc(call.caller)}" .`);
+        triples.push(`<urn:call:${encodeSegment(call.callee)}> <${OTX}title> "${esc(call.callee)}" .`);
+    }
+    return triples;
+}
+// ── Batching ────────────────────────────────────────────────────
+export function batchTriples(triples, batchSize = 100) {
+    const batches = [];
+    for (let i = 0; i < triples.length; i += batchSize) {
+        batches.push(triples.slice(i, i + batchSize));
+    }
+    return batches;
+}
+export async function deleteExistingSymbols(adapter, graphUri, modulePaths) {
+    for (const modPath of modulePaths) {
+        const modUri = moduleUri(modPath);
+        await adapter.sparqlUpdate(`DELETE WHERE { GRAPH <${graphUri}> { ?s <${OTX}definedIn> <${modUri}> . ?s ?p ?o } }`);
+    }
+}
+export async function pushSymbolTriples(adapter, graphUri, result) {
+    // Collect all module paths for scoped delete
+    const modulePaths = new Set();
+    for (const c of result.classes)
+        modulePaths.add(c.filePath);
+    for (const i of result.interfaces)
+        modulePaths.add(i.filePath);
+    for (const f of result.functions)
+        modulePaths.add(f.filePath);
+    // Delete existing symbols for these modules
+    await deleteExistingSymbols(adapter, graphUri, [...modulePaths]);
+    // Generate and batch-insert
+    const triples = generateSymbolTriples(result);
+    const batches = batchTriples(triples, 100);
+    for (const batch of batches) {
+        await adapter.sparqlUpdate(`INSERT DATA { GRAPH <${graphUri}> {\n${batch.join('\n')}\n} }`);
+    }
+    return { triplesInserted: triples.length, batchCount: batches.length };
+}

package/dist/lib/deep-scanner-treesitter.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Tree-sitter base extractor — abstract class that handles WASM loading,
+ * parser initialization, and provides query helpers for language-specific extractors.
+ *
+ * web-tree-sitter and tree-sitter-wasms are optional peerDependencies.
+ */
+import type { LanguageExtractor, ExtractedSymbols } from './language-extractor.js';
+type TSLanguage = import('web-tree-sitter').Language;
+type TSTree = import('web-tree-sitter').Tree;
+type TSNode = import('web-tree-sitter').Node;
+export type { TSNode, TSTree, TSLanguage };
+export declare abstract class TreeSitterExtractor implements LanguageExtractor {
+    abstract readonly language: string;
+    abstract readonly extensions: string[];
+    /** WASM file name, e.g. 'tree-sitter-python.wasm' */
+    protected abstract readonly wasmName: string;
+    protected lang: TSLanguage | null;
+    isAvailable(): Promise<boolean>;
+    extract(filePaths: string[], rootDir: string, options: {
+        maxSymbols: number;
+        timeoutMs: number;
+        includeMethodCalls: boolean;
+    }): Promise<ExtractedSymbols & {
+        warnings: string[];
+        capped: boolean;
+        fatal?: string;
+    }>;
+    /**
+     * Language-specific extraction from a parsed tree.
+     * Subclasses implement this to walk the AST and extract symbols.
+     */
+    protected abstract extractFromTree(tree: TSTree, relPath: string, source: string, includeMethodCalls: boolean): ExtractedSymbols;
+    /** Find all descendant nodes matching a type. */
+    protected findNodes(node: TSNode, type: string): TSNode[];
+    /** Find first child of a specific type. */
+    protected findChild(node: TSNode, type: string): TSNode | null;
+    /** Find all direct children of a specific type. */
+    protected findChildren(node: TSNode, type: string): TSNode[];
+    /** Get the text of a named child field. */
+    protected fieldText(node: TSNode, fieldName: string): string | null;
+}

package/dist/lib/deep-scanner-treesitter.js

@@ -0,0 +1,180 @@
+/**
+ * Tree-sitter base extractor — abstract class that handles WASM loading,
+ * parser initialization, and provides query helpers for language-specific extractors.
+ *
+ * web-tree-sitter and tree-sitter-wasms are optional peerDependencies.
+ */
+import { readFile } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+import { createRequire } from 'node:module';
+// ── WASM loading cache ──────────────────────────────────────────
+let parserClass = null;
+let languageClass = null;
+let initialized = false;
+const languageCache = new Map();
+async function initTreeSitter() {
+    if (initialized)
+        return parserClass !== null;
+    try {
+        const mod = await import('web-tree-sitter');
+        const Parser = mod.default ?? mod;
+        await Parser.init();
+        parserClass = Parser;
+        languageClass = Parser.Language ?? mod.Language;
+        initialized = true;
+        return true;
+    }
+    catch {
+        initialized = true;
+        return false;
+    }
+}
+async function loadLanguage(wasmName) {
+    if (languageCache.has(wasmName))
+        return languageCache.get(wasmName);
+    if (!languageClass)
+        return null;
+    try {
+        const require = createRequire(import.meta.url);
+        const wasmsDir = join(require.resolve('tree-sitter-wasms/package.json'), '..', 'out');
+        const wasmPath = join(wasmsDir, wasmName);
+        const wasmBuf = await readFile(wasmPath);
+        const lang = await languageClass.load(new Uint8Array(wasmBuf.buffer));
+        languageCache.set(wasmName, lang);
+        return lang;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Abstract base class ─────────────────────────────────────────
+export class TreeSitterExtractor {
+    constructor() {
+        this.lang = null;
+    }
+    async isAvailable() {
+        const ok = await initTreeSitter();
+        if (!ok)
+            return false;
+        this.lang = await loadLanguage(this.wasmName);
+        return this.lang !== null;
+    }
+    async extract(filePaths, rootDir, options) {
+        if (!parserClass || !this.lang) {
+            return {
+                classes: [], interfaces: [], functions: [], methodCalls: [],
+                warnings: [], capped: false,
+                fatal: `Tree-sitter or ${this.wasmName} not available.`,
+            };
+        }
+        const parser = new parserClass();
+        parser.setLanguage(this.lang);
+        const start = Date.now();
+        const classes = [];
+        const interfaces = [];
+        const functions = [];
+        const methodCalls = [];
+        const warnings = [];
+        let symbolCount = 0;
+        let capped = false;
+        const rootPrefix = rootDir.endsWith('/') ? rootDir : rootDir + '/';
+        for (const filePath of filePaths) {
+            if (Date.now() - start > options.timeoutMs) {
+                capped = true;
+                warnings.push(`Timeout after ${options.timeoutMs}ms. Returning partial results.`);
+                break;
+            }
+            if (symbolCount >= options.maxSymbols) {
+                capped = true;
+                break;
+            }
+            try {
+                const source = await readFile(filePath, 'utf-8');
+                const tree = parser.parse(source);
+                if (!tree) {
+                    warnings.push(`Failed to parse ${filePath}`);
+                    continue;
+                }
+                const relPath = filePath
+                    .replace(rootPrefix, '')
+                    .replace(new RegExp(`\\${extname(filePath)}$`), '');
+                const extracted = this.extractFromTree(tree, relPath, source, options.includeMethodCalls);
+                for (const c of extracted.classes) {
+                    if (symbolCount >= options.maxSymbols) {
+                        capped = true;
+                        break;
+                    }
+                    classes.push(c);
+                    symbolCount += 1 + c.methods.length;
+                }
+                if (capped)
+                    break;
+                for (const i of extracted.interfaces) {
+                    if (symbolCount >= options.maxSymbols) {
+                        capped = true;
+                        break;
+                    }
+                    interfaces.push(i);
+                    symbolCount++;
+                }
+                if (capped)
+                    break;
+                for (const f of extracted.functions) {
+                    if (symbolCount >= options.maxSymbols) {
+                        capped = true;
+                        break;
+                    }
+                    functions.push(f);
+                    symbolCount++;
+                }
+                if (capped)
+                    break;
+                methodCalls.push(...extracted.methodCalls);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                warnings.push(`Skipped ${filePath}: ${msg}`);
+            }
+        }
+        parser.delete();
+        return { classes, interfaces, functions, methodCalls, warnings, capped };
+    }
+    // ── Query helpers for subclasses ──────────────────────────────
+    /** Find all descendant nodes matching a type. */
+    findNodes(node, type) {
+        const results = [];
+        const walk = (n) => {
+            if (n.type === type)
+                results.push(n);
+            for (let i = 0; i < n.childCount; i++) {
+                walk(n.child(i));
+            }
+        };
+        walk(node);
+        return results;
+    }
+    /** Find first child of a specific type. */
+    findChild(node, type) {
+        for (let i = 0; i < node.childCount; i++) {
+            const child = node.child(i);
+            if (child.type === type)
+                return child;
+        }
+        return null;
+    }
+    /** Find all direct children of a specific type. */
+    findChildren(node, type) {
+        const results = [];
+        for (let i = 0; i < node.childCount; i++) {
+            const child = node.child(i);
+            if (child.type === type)
+                results.push(child);
+        }
+        return results;
+    }
+    /** Get the text of a named child field. */
+    fieldText(node, fieldName) {
+        const child = node.childForFieldName(fieldName);
+        return child ? child.text : null;
+    }
+}

package/dist/lib/deep-scanner-ts.d.ts

@@ -0,0 +1,20 @@
+/**
+ * TypeScript/JavaScript extractor — uses ts-morph for symbol-level analysis.
+ * ts-morph is a peerDependency; when absent isAvailable() returns false.
+ */
+import type { LanguageExtractor, ExtractedSymbols } from './language-extractor.js';
+export declare class TypeScriptExtractor implements LanguageExtractor {
+    readonly language = "typescript";
+    readonly extensions: string[];
+    private tsMorph;
+    isAvailable(): Promise<boolean>;
+    extract(_filePaths: string[], rootDir: string, options: {
+        maxSymbols: number;
+        timeoutMs: number;
+        includeMethodCalls: boolean;
+    }): Promise<ExtractedSymbols & {
+        warnings: string[];
+        capped: boolean;
+        fatal?: string;
+    }>;
+}