opentology 0.3.4 → 0.3.6

package/README.md

@@ -64,6 +64,52 @@ After setup, every session follows this cycle:
 
 OpenTology doesn't just add capabilities — it **shapes how the AI works** on your project.
 
+### Why Graph over grep?
+
+We ran a real experiment on this codebase: the same question answered with grep vs the knowledge graph.
+
+**Q: "What breaks if I change `store-adapter.ts`?"**
+
+| | grep / ripgrep | OpenTology |
+|---|---|---|
+| Calls needed | **6** (direct imports + 2nd-level deps + test files) | **1** (`context_impact`) |
+| Files found | 7 (missed dead-code dependents) | 9 (complete, including dead code) |
+| Impact severity | Not available | `HIGH` — returned automatically |
+| Manual work | Trace each import, search consumers, assemble the list yourself | None — one call returns the full picture |
+
+```bash
+# grep: 6 separate searches to assemble the dependency chain
+$ rg "import.*store-adapter" src/          # Step 1: direct imports (7 files)
+$ rg "import.*store-factory" src/          # Step 2: who imports those?
+$ rg "import.*reasoner" src/               # Step 3: ...and those?
+$ rg "import.*visualizer" src/             # Step 4
+$ rg "import.*embedded-adapter" src/       # Step 5
+$ rg "store-adapter|store-factory" tests/  # Step 6: test files
+
+# OpenTology: 1 call
+$ opentology context impact src/lib/store-adapter.ts
+# → Impact: HIGH | 9 dependents | 0 dependencies
+```
+
+**Q: "How does `embedded-adapter` reach `reasoner`?"**
+
+| | grep | OpenTology |
+|---|---|---|
+| Calls needed | **4** + manual code reading | **1** SPARQL query |
+| Result | Manual path assembly: adapter -> store-factory -> reasoner | Transitive closure (`dependsOn+`) returns all paths |
+| Bonus | None | Returns all 14 modules that reach reasoner, including indirect paths |
+
+```sparql
+# One query finds all transitive paths
+SELECT ?from ?to WHERE {
+  ?from otx:dependsOn+ ?to .
+  FILTER(?to = <urn:module:src/lib/reasoner>)
+}
+# Returns all 14 modules that reach reasoner, including indirect paths
+```
+
+**[See the interactive comparison at opentology.dev](https://opentology.dev)** — switch between Impact Analysis and Call Path Tracing scenarios.
+
 ### The Knowledge Graph
 
 Everything lives in RDF named graphs with the `otx:` ontology:
@@ -93,7 +139,7 @@ SELECT ?title ?reason WHERE {
 
 # What did we do last session?
 SELECT ?title ?body ?next WHERE {
-  ?s a otx:Session ; otx:title ?title ; otx:body ?body
+  ?s a otx:Session ; otx:title ?title ; otx:date ?date ; otx:body ?body
   OPTIONAL { ?s otx:nextTodo ?next }
 } ORDER BY DESC(?date) LIMIT 1
 ```
@@ -346,6 +392,52 @@ opentology context scan            # 3. 코드베이스를 지식 그래프로
 
 OpenTology는 기능만 추가하는 것이 아니라, **AI가 프로젝트에서 일하는 방식 자체를 바꿉니다**.
 
+### 왜 grep 대신 그래프인가?
+
+이 코드베이스에서 실제 실험을 했습니다: 같은 질문을 grep과 지식 그래프로 각각 답해 봤습니다.
+
+**Q: "`store-adapter.ts`를 바꾸면 뭐가 깨지나?"**
+
+| | grep / ripgrep | OpenTology |
+|---|---|---|
+| 필요한 호출 수 | **6번** (직접 import + 2차 의존 추적 + 테스트 파일) | **1번** (`context_impact`) |
+| 발견한 파일 수 | 7개 (dead code 의존성 누락) | 9개 (dead code 포함 완전한 결과) |
+| 영향도 수준 | 제공 안 됨 | `HIGH` — 자동 반환 |
+| 수작업 | 각 import를 추적하고, 소비자를 검색하고, 직접 목록 조합 | 없음 — 한 번의 호출로 전체 그림 |
+
+```bash
+# grep: 의존성 체인 조합에 6번의 검색
+$ rg "import.*store-adapter" src/          # 1단계: 직접 import (7개 파일)
+$ rg "import.*store-factory" src/          # 2단계: 그걸 누가 import?
+$ rg "import.*reasoner" src/               # 3단계: ...그리고 그걸?
+$ rg "import.*visualizer" src/             # 4단계
+$ rg "import.*embedded-adapter" src/       # 5단계
+$ rg "store-adapter|store-factory" tests/  # 6단계: 테스트 파일
+
+# OpenTology: 1번의 호출
+$ opentology context impact src/lib/store-adapter.ts
+# → Impact: HIGH | 9개 의존 모듈 | 0개 종속성
+```
+
+**Q: "`embedded-adapter`에서 `reasoner`까지 어떻게 연결되나?"**
+
+| | grep | OpenTology |
+|---|---|---|
+| 필요한 호출 수 | **4번** + 코드 직접 읽기 | **1번** SPARQL 쿼리 |
+| 결과 | 수동 경로 조합: adapter → store-factory → reasoner | 전이 폐포(`dependsOn+`)로 모든 경로 반환 |
+| 추가 발견 | 없음 | reasoner에 전이적으로 의존하는 14개 모듈 전체 목록 |
+
+```sparql
+-- 한 번의 쿼리로 모든 전이 경로 발견
+SELECT ?from ?to WHERE {
+  ?from otx:dependsOn+ ?to .
+  FILTER(?to = <urn:module:src/lib/reasoner>)
+}
+-- 간접 경로인 embedded-adapter 포함 14개 모듈 반환
+```
+
+**[opentology.dev에서 인터랙티브 비교 보기](https://opentology.dev)** — Impact Analysis와 Call Path Tracing 시나리오를 전환해 보세요.
+
 ### 지식 그래프 구조
 
 모든 데이터는 `otx:` 온톨로지를 사용하는 RDF named graph에 저장됩니다:
@@ -375,7 +467,7 @@ SELECT ?title ?reason WHERE {
 
 # 지난 세션에서 뭘 했지?
 SELECT ?title ?body ?next WHERE {
-  ?s a otx:Session ; otx:title ?title ; otx:body ?body
+  ?s a otx:Session ; otx:title ?title ; otx:date ?date ; otx:body ?body
   OPTIONAL { ?s otx:nextTodo ?next }
 } ORDER BY DESC(?date) LIMIT 1
 ```

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

@@ -7,7 +7,7 @@
 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;
+type TSNode = import('web-tree-sitter').SyntaxNode;
 export type { TSNode, TSTree, TSLanguage };
 export declare abstract class TreeSitterExtractor implements LanguageExtractor {
     abstract readonly language: string;

package/dist/mcp/server.js

@@ -379,22 +379,46 @@ async function handleContextScan(args) {
         }
         // Auto-push triples server-side
         let pushStats = null;
+        let moduleStats = null;
         try {
             const config = loadConfig();
             const contextUri = `${config.graphUri}/context`;
             const adapter = await createReadyAdapter(config);
+            // Push symbol triples
             pushStats = await pushSymbolTriples(adapter, contextUri, scanResult);
+            // Also push module dependency graph (fixes #64)
+            const snapshot = await scanCodebase(process.cwd());
+            if (snapshot.dependencyGraph && snapshot.dependencyGraph.modules.length > 0) {
+                const dg = snapshot.dependencyGraph;
+                // Clear stale Module/dependsOn triples
+                await adapter.sparqlUpdate(`DELETE { GRAPH <${contextUri}> { ?s ?p ?o } } WHERE { GRAPH <${contextUri}> { ?s ?p ?o . { ?s a <https://opentology.dev/vocab#Module> } UNION { ?s <https://opentology.dev/vocab#dependsOn> ?o } } }`);
+                const sparqlTriples = [];
+                for (const mod of dg.modules) {
+                    sparqlTriples.push(`<urn:module:${mod}> a <https://opentology.dev/vocab#Module> ; <https://opentology.dev/vocab#title> "${mod}" .`);
+                }
+                for (const edge of dg.edges) {
+                    sparqlTriples.push(`<urn:module:${edge.from}> <https://opentology.dev/vocab#dependsOn> <urn:module:${edge.to}> .`);
+                }
+                await adapter.sparqlUpdate(`INSERT DATA { GRAPH <${contextUri}> {\n${sparqlTriples.join('\n')}\n} }`);
+                moduleStats = { modules: dg.modules.length, edges: dg.edges.length };
+            }
             await persistGraph(adapter, config, contextUri);
         }
         catch {
             // Non-fatal: push is best-effort
         }
+        const hints = [];
+        if (pushStats)
+            hints.push(`Symbol triples: ${pushStats.triplesInserted} in ${pushStats.batchCount} batches`);
+        if (moduleStats)
+            hints.push(`Module triples: ${moduleStats.modules} modules, ${moduleStats.edges} edges`);
         return {
             ...scanResult,
             pushStats,
+            moduleStats,
             _experimental: true,
-            _hint: pushStats
-                ? `Symbol triples pushed: ${pushStats.triplesInserted} triples in ${pushStats.batchCount} batches. Query examples:\n- Classes: SELECT ?c ?name WHERE { ?c a otx:Class ; otx:title ?name }\n- Functions in a module: SELECT ?f ?name WHERE { ?f a otx:Function ; otx:title ?name ; otx:definedIn <urn:module:src/mcp/server> }\n- Call graph: SELECT ?caller ?callee WHERE { ?s a otx:MethodCall ; otx:callerSymbol ?caller ; otx:calleeSymbol ?callee }`
+            _hint: hints.length
+                ? `${hints.join('. ')}. Query examples:\n- Classes: SELECT ?c ?name WHERE { ?c a otx:Class ; otx:title ?name }\n- Dependents: SELECT ?dep WHERE { ?dep otx:dependsOn <urn:module:src/lib/store-adapter> }\n- Call graph: SELECT ?caller ?callee WHERE { ?s a otx:MethodCall ; otx:callerSymbol ?caller ; otx:calleeSymbol ?callee }`
                 : 'Deep scan completed but triple push failed. Use push manually with the generated triples.',
         };
     }
@@ -415,7 +439,7 @@ async function handleContextScan(args) {
             // Insert fresh triples
             const sparqlTriples = [];
             for (const mod of dg.modules) {
-                sparqlTriples.push(`<urn:module:${mod}> a <https://opentology.dev/vocab#Module> .`);
+                sparqlTriples.push(`<urn:module:${mod}> a <https://opentology.dev/vocab#Module> ; <https://opentology.dev/vocab#title> "${mod}" .`);
             }
             for (const edge of dg.edges) {
                 sparqlTriples.push(`<urn:module:${edge.from}> <https://opentology.dev/vocab#dependsOn> <urn:module:${edge.to}> .`);
@@ -626,7 +650,7 @@ async function handleContextInit(args) {
             const adapter = await createReadyAdapter(config);
             const sparqlTriples = [];
             for (const mod of dg.modules) {
-                sparqlTriples.push(`<urn:module:${mod}> a <https://opentology.dev/vocab#Module> .`);
+                sparqlTriples.push(`<urn:module:${mod}> a <https://opentology.dev/vocab#Module> ; <https://opentology.dev/vocab#title> "${mod}" .`);
             }
             for (const edge of dg.edges) {
                 sparqlTriples.push(`<urn:module:${edge.from}> <https://opentology.dev/vocab#dependsOn> <urn:module:${edge.to}> .`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentology",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Ontology-powered project memory for AI coding assistants — your codebase as a knowledge graph",
   "type": "module",
   "bin": {
@@ -51,9 +51,9 @@
     "shacl-engine": "^1.1.0"
   },
   "peerDependencies": {
+    "tree-sitter-wasms": ">=0.1.0",
     "ts-morph": ">=21.0.0",
-    "web-tree-sitter": ">=0.24.0",
-    "tree-sitter-wasms": ">=0.1.0"
+    "web-tree-sitter": ">=0.24.0 <0.26.0"
   },
   "peerDependenciesMeta": {
     "ts-morph": {
@@ -72,8 +72,8 @@
     "tree-sitter-wasms": "^0.1.13",
     "ts-morph": "^27.0.2",
     "ts-node": "^10.9.2",
-    "web-tree-sitter": "^0.26.8",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.2",
+    "web-tree-sitter": "^0.24.0"
   }
 }