ts-knowledge-graph 0.1.1 → 0.1.2

package/dist/store/kuzu_store.js

@@ -0,0 +1,66 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { Connection, Database } from 'kuzu';
+const SCHEMA = [
+    'CREATE NODE TABLE IF NOT EXISTS GraphNode (id STRING, kind STRING, name STRING, filePath STRING, exported BOOLEAN, startLine INT64, endLine INT64, PRIMARY KEY (id))',
+    'CREATE REL TABLE IF NOT EXISTS Edge (FROM GraphNode TO GraphNode, kind STRING)',
+];
+export class KuzuStore {
+    constructor(dbPath) {
+        mkdirSync(dirname(dbPath), { recursive: true });
+        this.db = new Database(dbPath);
+        this.conn = new Connection(this.db);
+    }
+    async initSchema() {
+        for (const statement of SCHEMA) {
+            KuzuStore.closeResults(await this.conn.query(statement));
+        }
+    }
+    async load(nodes, edges) {
+        const nodeStmt = await this.conn.prepare('MERGE (n:GraphNode {id: $id}) SET n.kind = $kind, n.name = $name, n.filePath = $filePath, n.exported = $exported, n.startLine = $startLine, n.endLine = $endLine');
+        for (const node of nodes) {
+            KuzuStore.closeResults(await this.conn.execute(nodeStmt, {
+                id: node.id,
+                kind: node.kind,
+                name: node.name,
+                filePath: node.filePath,
+                exported: node.exported ?? false,
+                startLine: node.range?.startLine ?? 0,
+                endLine: node.range?.endLine ?? 0,
+            }));
+        }
+        const edgeStmt = await this.conn.prepare('MATCH (f:GraphNode {id: $from}), (t:GraphNode {id: $to}) MERGE (f)-[:Edge {kind: $kind}]->(t)');
+        for (const edge of edges) {
+            KuzuStore.closeResults(await this.conn.execute(edgeStmt, { from: edge.from, to: edge.to, kind: edge.kind }));
+        }
+    }
+    async run(cypher, params) {
+        const result = params === undefined
+            ? await this.conn.query(cypher)
+            : await this.conn.execute(await this.conn.prepare(cypher), params);
+        try {
+            return await KuzuStore.first(result).getAll();
+        }
+        finally {
+            KuzuStore.closeResults(result);
+        }
+    }
+    async close() {
+        await this.conn.close();
+        await this.db.close();
+    }
+    static first(result) {
+        return Array.isArray(result) ? result[0] : result;
+    }
+    /**
+     * Releases the native memory behind one or more query results. Results left
+     * unclosed are finalized after the database shuts down at process exit,
+     * which crashes the kuzu native module with a segmentation fault.
+     */
+    static closeResults(result) {
+        for (const item of Array.isArray(result) ? result : [result]) {
+            item.close();
+        }
+    }
+}
+//# sourceMappingURL=kuzu_store.js.map

package/dist/store/kuzu_store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kuzu_store.js","sourceRoot":"","sources":["../../src/store/kuzu_store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ts-knowledge-graph",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"description": "Parse TypeScript source into a knowledge graph for autonomous code optimization",
 	"type": "module",
 	"bin": {
@@ -8,6 +8,8 @@
 	},
 	"files": [
 		"dist",
+		"contribs/web_visualisation/web",
+		"skills/ts-knowledge-graph/SKILL.md",
 		"README.md",
 		"LICENSE",
 		".env-sample"
@@ -20,10 +22,12 @@
 	},
 	"scripts": {
 		"extract": "tsx src/cli.ts extract",
+		"web": "tsx src/cli.ts web",
 		"dev": "tsx src/cli.ts",
 		"build": "tsc -p tsconfig.build.json",
 		"publish:all": "npm run build && npm version patch && npm publish",
-		"typecheck": "tsc --noEmit"
+		"typecheck": "tsc --noEmit",
+		"test": "node --import tsx --test \"test/**/*.test.ts\""
 	},
 	"dependencies": {
 		"chalk": "^5.3.0",

package/skills/ts-knowledge-graph/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ts-knowledge-graph
+description: >-
+  Query a TypeScript codebase as a knowledge graph to answer impact, caller,
+  dependency, and dead-code questions. Use this instead of grep/glob for
+  "who calls X", "what breaks if I change X" (blast radius), "is X dead code",
+  "what references this type", and "what is X connected to". Requires the
+  ts-knowledge-graph CLI and a built graph database.
+---
+
+# ts-knowledge-graph
+
+Answer structural questions about a TypeScript project by querying a semantic
+knowledge graph (built with the TypeScript compiler API) rather than reading or
+grepping source files. The graph has resolved symbols and types, so its answers
+are precise where text search is not.
+
+## When to use this skill
+
+Reach for these commands — not `Grep`/`Glob` — when the question is about code
+structure or impact:
+
+- **Callers** — "who calls this function?" → `who-calls`
+- **Callees** — "what does this function call?" → `calls`
+- **Impact / blast radius** — "what breaks if I change this?" → `blast-radius`
+- **References** — "what uses this symbol or type?" → `references`
+- **Dead code** — "which exports are unused?" → `dead-exports`
+- **Neighbourhood** — "what is this connected to?" → `neighbors`
+
+For reading the actual implementation of a known file, normal file tools are
+still the right choice. Use this skill to decide *which* code matters first.
+
+## Prerequisite: build the graph once
+
+Querying needs a Kùzu database at `./outputs/graph.kuzu`. If it is missing,
+build it first (the `--semantic` flag is required for `CALLS` and heritage
+edges, which power `who-calls`, `calls`, and `blast-radius`):
+
+```bash
+npx ts-knowledge-graph extract <path-to-project> --semantic   # writes ./outputs/graph/*.jsonl
+npx ts-knowledge-graph load                                   # writes ./outputs/graph.kuzu
+```
+
+Inside this repository's own checkout, substitute `npm run dev --` for the
+`ts-knowledge-graph` binary (e.g. `npm run dev -- load`).
+
+## Core workflow: names are not ids
+
+Every query that inspects a symbol takes a **node id**, not a name. Resolve a
+name to id(s) first with `find`, then pass an id to the other commands. Never
+hand-write ids.
+
+```bash
+npx ts-knowledge-graph find <name> --json        # -> array of { id, name, kind, filePath, startLine }
+npx ts-knowledge-graph who-calls <id> --json     # use an id from the find result
+```
+
+Always pass `--json`; consume the JSON, not the human-readable output.
+
+## Command reference
+
+All commands accept `--json` and `-d, --db <path>` (default `./outputs/graph.kuzu`).
+
+| Command | Argument | Purpose |
+| --- | --- | --- |
+| `find <pattern>` | name substring | resolve a name to node id(s) |
+| `who-calls <id>` | node id | direct callers of a symbol |
+| `calls <id>` | node id | what a symbol directly calls |
+| `blast-radius <id> [--depth <n>]` | node id | transitive callers / impact set (default depth 10) |
+| `references <id>` | node id | everything referencing a symbol/type (calls, type usage, heritage, new) |
+| `neighbors <id>` | node id | one-hop neighbourhood, inbound and outbound |
+| `dead-exports` | (none) | exported symbols with no inbound references |
+
+## Output contract
+
+- `find`, `who-calls`, `calls`, `blast-radius`, `dead-exports` return a JSON
+  array of `SymbolRef`: `{ id, kind, name, filePath, startLine }`.
+- `references` and `neighbors` return `NeighborRef`: a `SymbolRef` plus
+  `edgeKind` and `direction` (`"in"` or `"out"`).
+
+## Worked example
+
+> "Is it safe to change the signature of `loadProject`?"
+
+```bash
+npx ts-knowledge-graph find loadProject --json          # -> get its id
+npx ts-knowledge-graph blast-radius <id> --json         # -> every symbol transitively impacted
+```
+
+Report the impacted set (file paths + names) as the blast radius, then read
+those specific call sites to judge the change.