ts-knowledge-graph 0.1.2 → 0.1.6

package/dist/verify/project_verifier.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The reusable verify path for the optimization loop: run the project's
+ * type-check and test gates and reduce them to one pass/fail verdict, plus the
+ * honesty flags an agent needs (was *behaviour* verified, or only types?).
+ *
+ * A type-check proves the edit compiles; it cannot see a swapped operator, an
+ * off-by-one, or a dropped branch. Running the test suite alongside `tsc` is
+ * what turns "still compiles" into "still works". When a project has no test
+ * script the test gate degrades to skipped and {@link VerifyReport.behaviorVerified}
+ * stays false, so the caller can report the change as unverified rather than
+ * implying it was behaviourally checked.
+ */
+/** The two correctness gates, run in order. */
+export type CheckName = 'typecheck' | 'test';
+/** A gate ran and passed, ran and failed, or never ran. */
+export type CheckStatus = 'pass' | 'fail' | 'skipped';
+/** A gate resolved from the project's package.json: its command, or why it was skipped. */
+export type PlannedCheck = {
+    name: CheckName;
+    /** The shell command to run, or `null` when the gate is skipped. */
+    command: string | null;
+    /** Why the gate will not run (e.g. no matching npm script), set when `command` is null. */
+    skippedReason?: string;
+};
+/** The outcome of executing (or skipping) one gate. */
+export type CheckResult = {
+    name: CheckName;
+    command: string | null;
+    status: CheckStatus;
+    /** Process exit code; `null` when the gate was skipped or the process died on a signal. */
+    exitCode: number | null;
+    durationMs: number;
+    /** Combined stdout+stderr, tail-bounded to the last `outputTailLines` lines. */
+    output: string;
+    skippedReason?: string;
+};
+/** The single verdict the optimize loop consumes to keep or revert an edit. */
+export type VerifyReport = {
+    /** True when at least one gate ran and no gate that ran failed. */
+    ok: boolean;
+    /** True only when the test gate actually ran and passed — behaviour, not just types, was checked. */
+    behaviorVerified: boolean;
+    /** True when a gate was skipped (e.g. the project has no test script), so `ok` is weaker than a full pass. */
+    degraded: boolean;
+    checks: CheckResult[];
+    /** A one-line, quotable verdict that states exactly what was and was not verified. */
+    summary: string;
+};
+export type VerifyOptions = {
+    /** Project root whose package.json is read and whose scripts are run. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** npm script name for the type-check gate. Default `typecheck`. */
+    typecheckScript?: string;
+    /** npm script name for the test gate. Default `test`. */
+    testScript?: string;
+    /** Skip the type-check gate entirely. */
+    skipTypecheck?: boolean;
+    /** Skip the test gate entirely (degrades to type-check-only, reported honestly). */
+    skipTests?: boolean;
+    /** Keep only the last N lines of each gate's captured output. Default 80. */
+    outputTailLines?: number;
+};
+/** How a planned gate is executed. Injectable so tests need not spawn npm. */
+export type CheckExecutor = (command: string, cwd: string) => Promise<{
+    exitCode: number | null;
+    output: string;
+}>;
+export declare class ProjectVerifier {
+    /**
+     * Run the project's verify gates and return one verdict. `exec` defaults to a
+     * real subprocess spawn; tests inject a fake to avoid running npm.
+     */
+    static verify(options?: VerifyOptions, exec?: CheckExecutor): Promise<VerifyReport>;
+    /** Resolve each gate against the project's scripts, deciding what will run and what is skipped (pure). */
+    static planChecks(scripts: Record<string, string>, options?: VerifyOptions): PlannedCheck[];
+    /** Reduce a set of gate results to the single verdict, including the honesty flags (pure). */
+    static summarize(checks: CheckResult[]): VerifyReport;
+    private static planOne;
+    private static runCheck;
+    private static buildSummary;
+    private static readScripts;
+    private static tail;
+    private static spawnCommand;
+}
+//# sourceMappingURL=project_verifier.d.ts.map

package/dist/verify/project_verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project_verifier.d.ts","sourceRoot":"","sources":["../../src/verify/project_verifier.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AAEH,+CAA+C;AAC/C,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;AAE7C,2DAA2D;AAC3D,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAEtD,2FAA2F;AAC3F,MAAM,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,oEAAoE;IACpE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,2FAA2F;IAC3F,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,uDAAuD;AACvD,MAAM,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,2FAA2F;IAC3F,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG;IAC1B,mEAAmE;IACnE,EAAE,EAAE,OAAO,CAAC;IACZ,qGAAqG;IACrG,gBAAgB,EAAE,OAAO,CAAC;IAC1B,8GAA8G;IAC9G,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC3B,sGAAsG;IACtG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,oFAAoF;IACpF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6EAA6E;IAC7E,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAQnH,qBAAa,eAAe;IAC3B;;;OAGG;WACU,MAAM,CAAC,OAAO,GAAE,aAAkB,EAAE,IAAI,GAAE,aAA4C,GAAG,OAAO,CAAC,YAAY,CAAC;IAY3H,0GAA0G;IAC1G,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAE,aAAkB,GAAG,YAAY,EAAE;IAS/F,8FAA8F;IAC9F,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,YAAY;IAWrD,OAAO,CAAC,MAAM,CAAC,OAAO;mBAUD,QAAQ;IAwB7B,OAAO,CAAC,MAAM,CAAC,YAAY;mBAoBN,WAAW;IAmBhC,OAAO,CAAC,MAAM,CAAC,IAAI;IAWnB,OAAO,CAAC,MAAM,CAAC,YAAY;CAkB3B"}

package/dist/verify/project_verifier.js

@@ -0,0 +1,138 @@
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+const DEFAULT_TYPECHECK_SCRIPT = 'typecheck';
+const DEFAULT_TEST_SCRIPT = 'test';
+const DEFAULT_TAIL_LINES = 80;
+const PackageJsonSchema = z.object({ scripts: z.record(z.unknown()).optional() });
+export class ProjectVerifier {
+    /**
+     * Run the project's verify gates and return one verdict. `exec` defaults to a
+     * real subprocess spawn; tests inject a fake to avoid running npm.
+     */
+    static async verify(options = {}, exec = ProjectVerifier.spawnCommand) {
+        const cwd = resolve(options.cwd ?? process.cwd());
+        const tailLines = options.outputTailLines ?? DEFAULT_TAIL_LINES;
+        const scripts = await ProjectVerifier.readScripts(cwd);
+        const plan = ProjectVerifier.planChecks(scripts, options);
+        const results = [];
+        for (const check of plan) {
+            results.push(await ProjectVerifier.runCheck(check, cwd, tailLines, exec));
+        }
+        return ProjectVerifier.summarize(results);
+    }
+    /** Resolve each gate against the project's scripts, deciding what will run and what is skipped (pure). */
+    static planChecks(scripts, options = {}) {
+        const typecheckScript = options.typecheckScript ?? DEFAULT_TYPECHECK_SCRIPT;
+        const testScript = options.testScript ?? DEFAULT_TEST_SCRIPT;
+        return [
+            ProjectVerifier.planOne('typecheck', typecheckScript, scripts, options.skipTypecheck === true),
+            ProjectVerifier.planOne('test', testScript, scripts, options.skipTests === true),
+        ];
+    }
+    /** Reduce a set of gate results to the single verdict, including the honesty flags (pure). */
+    static summarize(checks) {
+        const ran = checks.filter((check) => check.status !== 'skipped');
+        const failed = ran.filter((check) => check.status === 'fail');
+        const test = checks.find((check) => check.name === 'test');
+        const behaviorVerified = test !== undefined && test.status === 'pass';
+        const ok = ran.length > 0 && failed.length === 0;
+        const degraded = checks.some((check) => check.status === 'skipped');
+        const summary = ProjectVerifier.buildSummary(ran, failed, test, ok, behaviorVerified);
+        return { ok, behaviorVerified, degraded, checks, summary };
+    }
+    static planOne(name, script, scripts, skip) {
+        if (skip === true) {
+            return { name, command: null, skippedReason: 'skipped by request' };
+        }
+        if (typeof scripts[script] !== 'string') {
+            return { name, command: null, skippedReason: `no "${script}" script in package.json` };
+        }
+        return { name, command: `npm run ${script}` };
+    }
+    static async runCheck(check, cwd, tailLines, exec) {
+        if (check.command === null) {
+            return {
+                name: check.name,
+                command: null,
+                status: 'skipped',
+                exitCode: null,
+                durationMs: 0,
+                output: '',
+                skippedReason: check.skippedReason,
+            };
+        }
+        const startedAt = Date.now();
+        const { exitCode, output } = await exec(check.command, cwd);
+        return {
+            name: check.name,
+            command: check.command,
+            status: exitCode === 0 ? 'pass' : 'fail',
+            exitCode,
+            durationMs: Date.now() - startedAt,
+            output: ProjectVerifier.tail(output, tailLines),
+        };
+    }
+    static buildSummary(ran, failed, test, ok, behaviorVerified) {
+        if (ran.length === 0) {
+            return 'could not verify: no type-check or test script found — change is unverified';
+        }
+        if (ok === false) {
+            return `FAILED: ${failed.map((check) => check.name).join(' and ')} did not pass — revert the edit`;
+        }
+        if (behaviorVerified === true) {
+            return `verified: ${ran.map((check) => check.name).join(' + ')} passed (behaviour checked)`;
+        }
+        const why = test?.skippedReason ?? 'tests did not run';
+        return `type-check passed, but ${why} — behaviour NOT verified`;
+    }
+    static async readScripts(cwd) {
+        try {
+            const raw = await readFile(resolve(cwd, 'package.json'), 'utf8');
+            const parsed = PackageJsonSchema.safeParse(JSON.parse(raw));
+            if (parsed.success === false) {
+                return {};
+            }
+            const scripts = {};
+            for (const [name, value] of Object.entries(parsed.data.scripts ?? {})) {
+                if (typeof value === 'string') {
+                    scripts[name] = value;
+                }
+            }
+            return scripts;
+        }
+        catch {
+            return {};
+        }
+    }
+    static tail(text, lines) {
+        if (lines <= 0) {
+            return text;
+        }
+        const allLines = text.split('\n');
+        if (allLines.length <= lines) {
+            return text;
+        }
+        return allLines.slice(allLines.length - lines).join('\n');
+    }
+    static spawnCommand(command, cwd) {
+        return new Promise((resolvePromise) => {
+            const child = spawn(command, { cwd, shell: true });
+            let output = '';
+            const append = (chunk) => {
+                output += chunk.toString();
+            };
+            child.stdout.on('data', append);
+            child.stderr.on('data', append);
+            child.on('error', (error) => {
+                output += `\n${error.message}`;
+                resolvePromise({ exitCode: 1, output });
+            });
+            child.on('close', (code) => {
+                resolvePromise({ exitCode: code, output });
+            });
+        });
+    }
+}
+//# sourceMappingURL=project_verifier.js.map

package/dist/verify/project_verifier.js.map

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

package/dotclaude_folder/commands/code-graph-interview.md

@@ -0,0 +1,123 @@
+---
+description: Interview the user to scope an optimization target, using the code knowledge graph to surface and ground candidate tasks.
+argument-hint: [focus]
+allowed-tools: Bash, Read, Skill
+---
+
+# code-graph-interview
+
+You are a TypeScript optimization analyst. Your job is **not** to change any code.
+It is to interview the user, narrow a vague wish ("optimize this") into one or more
+concrete, measurable, well-scoped optimization tasks, and ground each candidate in
+the code knowledge graph so it points at real symbols. You finish by **presenting
+the tasks** — you do not apply them.
+
+Use the code knowledge graph as your eyes: it holds resolved symbols and types, so
+its answers about callers, references, and dead code are precise where text search
+is not. Trust it over `grep` for any question about code structure or impact.
+
+## Optional focus
+
+ $ARGUMENTS
+
+If the focus above is non-empty, treat it as the user's starting hint (a dimension,
+a subsystem, or a named symbol) and steer the interview toward it. If it is empty,
+begin the interview from scratch.
+
+## What "optimize" means (drive the interview with this)
+
+"Optimize" is ambiguous and multi-dimensional. Do not guess which dimension the
+user means — establish it. Optimization starts from a business concern, then
+becomes a measurable target with a scope and constraints. Walk the user through
+these five steps, in order, asking one focused round of questions at a time:
+
+1. **Dimension** — what are we optimizing? Offer the choices and let the user pick:
+   execution time / latency, memory usage, infrastructure cost (including LLM
+   tokens), network usage, scalability, code maintainability, binary / bundle size,
+   energy. Execution time is the usual default, but make the user choose.
+2. **Business concern** — capture the pain point, not the metric ("cloud bill too
+   high", "users say search is slow", "hitting API rate limits"). The user
+   understands the pain; you translate it into a technical goal.
+3. **Measurable target** — turn the goal into a baseline and a target, e.g.
+   `800ms → 300ms`, `50 → 10 queries per request`, `10M → 2M tokens/day`. If a
+   thing cannot be measured, it cannot be optimized — say so and help define a
+   metric.
+4. **Scope** — which part of the system: frontend, backend, database, network,
+   cache, queue, external APIs, LLM usage, storage, or a specific module / symbol.
+5. **Constraints** — what must be preserved: same functionality, same security
+   guarantees, same API contract, same UX, same accuracy.
+
+## Tools you will use
+
+Graph queries go through this project's own CLI, which is documented by the
+`code-graph-query` skill. Inside this repository's checkout, run the CLI with
+`npx ts-knowledge-graph`, always pass `--json`, and let it use the default database
+at `./.ts_knowledge_graph/graph.kuzu`:
+
+- `npx ts-knowledge-graph dead-exports --json` — exported symbols with no inbound references (maintainability / dead-code candidates).
+- `npx ts-knowledge-graph find <name> --json` — resolve a name to node id(s). Every other query needs an id; never invent one.
+- `npx ts-knowledge-graph references <id> --json` — everything that references a symbol or type.
+- `npx ts-knowledge-graph who-calls <id> --json` — direct callers of a function or method.
+- `npx ts-knowledge-graph calls <id> --json` — what a symbol directly calls.
+- `npx ts-knowledge-graph blast-radius <id> [--depth <n>] --json` — the transitive impact set (a proxy for change risk).
+- `npx ts-knowledge-graph neighbors <id> --json` — the one-hop neighbourhood, inbound and outbound (a proxy for coupling).
+
+If `./.ts_knowledge_graph/graph.kuzu` does not exist, build it first with
+`npx ts-knowledge-graph extract . --semantic` followed by `npx ts-knowledge-graph load`
+(the `--semantic` flag is required for caller and heritage edges).
+
+For reading exact source text once you have located a symbol, use the Read tool.
+
+### What the graph can and cannot ground
+
+The graph is a **static** structural / semantic model: it knows symbols, callers,
+references, and dead code. It does **not** hold runtime telemetry (latency, CPU,
+memory, cost, call frequency). So:
+
+- For **maintainability and dead-code** work, the graph is decisive: `dead-exports`
+  is a direct source of safe candidates.
+- For **structural risk and coupling**, use `references`, `who-calls`,
+  `blast-radius`, and `neighbors` to rank how central or entangled a symbol is — a
+  high-reference, high-blast-radius symbol is a hotspot to treat carefully; an
+  isolated one is safer to refactor.
+- For **runtime dimensions** (latency, memory, cost, tokens), the graph can only
+  show you *where* in the structure a hot path lives — the user must supply the
+  measurement and baseline. Say this plainly rather than inventing numbers.
+
+## Method (follow it in order)
+
+1. **Establish the dimension and concern.** Ask the user the step 1–2 questions.
+   Do not proceed until you know what is being optimized and why.
+2. **Pin a measurable target and scope.** Ask the step 3–4 questions. Push back on
+   unmeasurable goals.
+3. **Capture constraints.** Ask step 5 — what must not change.
+4. **Survey the graph for candidates.** Run the queries above to surface concrete
+   targets within the agreed scope: start with `dead-exports`, and use `find` +
+   `references` / `who-calls` / `blast-radius` to locate and rank named hotspots.
+   Cite real node ids, file paths, and counts — never invent them.
+5. **Draft the tasks.** Turn the findings into one or more concrete optimization
+   tasks. Each task must be self-contained and shaped so it could later be handed
+   to `/code-graph-optimize`. Include, per task:
+   - **Title** — one line.
+   - **Dimension** and **scope**.
+   - **Target** — the symbol(s) / file(s), with node id(s) and path(s) from the graph.
+   - **Measurable goal** — baseline → target (or "structural only" for dead-code).
+   - **Constraints** — what to preserve.
+   - **Graph evidence** — the reference / caller / blast-radius counts that justify it.
+   - **Estimated risk** — low / medium / high, argued from blast radius and coupling.
+6. **Present and stop.** Show the user the ranked list of candidate tasks. **Do not
+   apply anything and do not invoke `/code-graph-optimize`.** End by telling the
+   user they can run `/code-graph-optimize "<task>"` themselves with whichever task
+   they choose.
+
+## Rules
+
+- This command is read-only. Never edit code, and never call `/code-graph-optimize`.
+- Node ids come from `find` and `dead-exports` output; never invent them, never
+  invent file paths, counts, or runtime numbers.
+- Interview the user — ask real questions and wait for answers. Do not assume the
+  dimension, target, or constraints.
+- Keep every proposed task measurable and scoped. Reject vague goals like "make it
+  faster" until they have a baseline and a target.
+- Present multiple candidates when the graph supports them, ranked by estimated
+  value against risk, so the user can choose.

package/dotclaude_folder/commands/code-graph-optimize.md

@@ -0,0 +1,65 @@
+---
+description: Autonomously find and apply one verified-safe optimization, using the code knowledge graph as its eyes.
+argument-hint: [task]
+allowed-tools: Bash, Read, Edit, Skill
+---
+
+# code-graph-optimize
+
+You are an autonomous TypeScript optimization agent working on this real codebase.
+Use the code knowledge graph as your eyes: it holds resolved symbols and types, so
+its answers about callers, references, and dead code are precise where text search
+is not. Trust it over `grep` for any question about code structure or impact.
+
+## Your task
+
+ $ARGUMENTS
+
+If the task above is empty, default to this mission: **find one genuinely dead
+exported symbol, confirm it has zero inbound references, then remove it safely.**
+
+## Tools you will use
+
+Graph queries go through this project's own CLI, which is documented by the
+`code-graph-query` skill. Inside this repository's checkout, run the CLI with
+`npx ts-knowledge-graph`, always pass `--json`, and let it use the default database at
+`./.ts_knowledge_graph/graph.kuzu`:
+
+- `npx ts-knowledge-graph dead-exports --json` — exported symbols with no inbound references (the safest candidates).
+- `npx ts-knowledge-graph find <name> --json` — resolve a name to node id(s). Every other query needs an id; never invent one.
+- `npx ts-knowledge-graph references <id> --json` — everything that references a symbol or type. This is the decisive safety check.
+- `npx ts-knowledge-graph who-calls <id> --json` — direct callers of a function or method.
+- `npx ts-knowledge-graph blast-radius <id> [--depth <n>] --json` — the transitive impact set.
+- `npx ts-knowledge-graph neighbors <id> --json` — the one-hop neighbourhood, inbound and outbound.
+
+If `./.ts_knowledge_graph/graph.kuzu` does not exist, build it first with
+`npx ts-knowledge-graph extract . --semantic` followed by `npx ts-knowledge-graph load`
+(the `--semantic` flag is required for caller and heritage edges).
+
+To verify an edit, use this project's own verify gate, which runs the
+type-check **and** the test suite together and returns a single verdict:
+
+- `npx ts-knowledge-graph verify --json` — runs the project's `typecheck` + `test` npm scripts and reports one result. `ok: true` means keep the edit; `ok: false` means revert it (the command also exits non-zero on failure). `behaviorVerified: true` means the tests actually ran and passed — not just the type-check. If the project has no `test` script the test gate is skipped, `degraded` is `true`, and the edit is type-checked only.
+
+For reading exact source text, use the Read tool. For making the change, use the
+Edit tool.
+
+## Method (follow it in order)
+
+1. **Find a candidate.** Dead code is the safest win — call `dead-exports` first, or `find` to locate a named target from the task.
+2. **Confirm the blast radius.** Before proposing any change you MUST confirm safety with `references` (and `who-calls` or `blast-radius` when useful). A symbol is safe to remove only when it has zero inbound references.
+3. **Read the exact text** with the Read tool so your edit matches the file precisely.
+4. **Make exactly one edit** with the Edit tool.
+5. **Verify, then keep or revert.** Run `npx ts-knowledge-graph verify --json` — one command that runs the type-check **and** the test suite, so a behaviour-changing edit (a swapped operator, an off-by-one, a dropped branch) is caught, not just a type error.
+   - If `ok` is `true`, the edit stands.
+   - If `ok` is `false`, revert immediately with `git restore <file>`, then either try a different edit or abandon the change. Never leave a failing verify behind.
+6. **Measure the impact (optional — only when the task targets a runtime metric and a workload exists).** If the point of the edit was to make something *faster*, and the project or task supplies a repeatable workload, you can report the measured delta with `npx ts-knowledge-graph benchmark <name> --workload <path> --runs 5` (capture a `--save-baseline` before the edit, compare with `--baseline` after — rebuild the graph in between). This gate is **advisory**: a noisy median with a spread, not a pass/fail. Never present a benchmark delta as a guarantee, and never let it override the hard `verify` result.
+7. **Stop and summarize.** Report the file changed, the symbol removed, and why removal was safe. State plainly **how the edit was verified**: say the change was type-checked *and* tested only when `behaviorVerified` was `true`; if verify ran `degraded` (type-check only, because the project has no test script), say the change was **not** behaviourally verified rather than implying it was. If you measured impact, report it as an advisory delta, not a promise. If you found no safe change, say so plainly.
+
+## Rules
+
+- Node ids come from `find` and `dead-exports` output; never invent them.
+- Act autonomously. Do not ask the user questions — make the call yourself.
+- Prefer removing genuinely dead exports or behavior-preserving simplifications. Never change observable behavior.
+- Before your first edit, confirm the target file has no unrelated uncommitted changes, so that a revert restores a known-good state. If it does, mention it and proceed carefully.
+- Apply at most one verified edit per run, mirroring the original optimizer's discipline.

package/{skills/ts-knowledge-graph → dotclaude_folder/skills/code-graph-query}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ts-knowledge-graph
+name: code-graph-query
 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
@@ -8,7 +8,7 @@ description: >-
   ts-knowledge-graph CLI and a built graph database.
 ---
 
-# ts-knowledge-graph
+# code-graph-query
 
 Answer structural questions about a TypeScript project by querying a semantic
 knowledge graph (built with the TypeScript compiler API) rather than reading or
@@ -32,13 +32,13 @@ 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,
+Querying needs a Kùzu database at `./.ts_knowledge_graph/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
+npx ts-knowledge-graph extract <path-to-project> --semantic   # writes ./.ts_knowledge_graph/graph/*.jsonl
+npx ts-knowledge-graph load                                   # writes ./.ts_knowledge_graph/graph.kuzu
 ```
 
 Inside this repository's own checkout, substitute `npm run dev --` for the
@@ -59,7 +59,7 @@ 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`).
+All commands accept `--json` and `-o, --output-folder <dir>` (default `./.ts_knowledge_graph`).
 
 | Command | Argument | Purpose |
 | --- | --- | --- |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ts-knowledge-graph",
-	"version": "0.1.2",
+	"version": "0.1.6",
 	"description": "Parse TypeScript source into a knowledge graph for autonomous code optimization",
 	"type": "module",
 	"bin": {
@@ -8,37 +8,126 @@
 	},
 	"files": [
 		"dist",
-		"contribs/web_visualisation/web",
-		"skills/ts-knowledge-graph/SKILL.md",
+		"contribs/webview/web",
+		"dotclaude_folder",
 		"README.md",
-		"LICENSE",
-		".env-sample"
+		"LICENSE"
 	],
 	"engines": {
-		"node": ">=18"
+		"node": ">=20.12"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
 	"scripts": {
 		"extract": "tsx src/cli.ts extract",
-		"web": "tsx src/cli.ts web",
+		"webview": "tsx src/cli.ts webview",
 		"dev": "tsx src/cli.ts",
 		"build": "tsc -p tsconfig.build.json",
+		"clean": "npm run clean:dist && npm run clean:outputs",
+		"clean:dist": "rm -rf ./dist",
+		"clean:outputs": "rm -rf ./.ts_knowledge_graph/*/",
+		"symlink:dotclaude": "bash scripts/symlink_dotclaude.sh",
 		"publish:all": "npm run build && npm version patch && npm publish",
-		"typecheck": "tsc --noEmit",
-		"test": "node --import tsx --test \"test/**/*.test.ts\""
+		"typecheck": "tsc --noEmit && tsc -p contribs/webview/tsconfig.web.json",
+		"test": "node --import tsx --test \"tests/**/*.test.ts\"",
+		"verify": "tsx src/cli.ts verify",
+		"project01": "npm run project01:rebuild && npm run project01:dead-exports",
+		"project01:tour": "bash scripts/project_01_tour.sh",
+		"project01:rebuild": "npm run project01:clean && npm run project01:extract && npm run project01:load",
+		"project01:clean": "rm -rf ./.ts_knowledge_graph/project_01/graph ./.ts_knowledge_graph/project_01/graph.kuzu ./.ts_knowledge_graph/project_01/prof",
+		"project01:extract": "tsx src/cli.ts extract sample_projects/project_01/src --semantic -o ./.ts_knowledge_graph/project_01",
+		"project01:load": "tsx src/cli.ts load -o ./.ts_knowledge_graph/project_01",
+		"project01:enrich": "bash scripts/profile_and_enrich.sh project_01",
+		"project01:benchmark": "tsx src/cli.ts benchmark titleCase --workload scripts/benchmarks/project_01_workload.ts -o ./.ts_knowledge_graph/project_01 --root ./sample_projects/project_01 --runs 5",
+		"project01:verify": "tsx src/cli.ts verify --cwd sample_projects/project_01",
+		"project01:dead-exports": "tsx src/cli.ts dead-exports -o ./.ts_knowledge_graph/project_01",
+		"project01:hotspots": "tsx src/cli.ts hotspots -o ./.ts_knowledge_graph/project_01",
+		"project01:cost": "tsx src/cli.ts cost -o ./.ts_knowledge_graph/project_01",
+		"project01:cluster": "tsx src/cli.ts cluster -o ./.ts_knowledge_graph/project_01",
+		"project01:find": "tsx src/cli.ts find -o ./.ts_knowledge_graph/project_01",
+		"project01:who-calls": "tsx src/cli.ts who-calls -o ./.ts_knowledge_graph/project_01",
+		"project01:calls": "tsx src/cli.ts calls -o ./.ts_knowledge_graph/project_01",
+		"project01:references": "tsx src/cli.ts references -o ./.ts_knowledge_graph/project_01",
+		"project01:neighbors": "tsx src/cli.ts neighbors -o ./.ts_knowledge_graph/project_01",
+		"project01:blast-radius": "tsx src/cli.ts blast-radius -o ./.ts_knowledge_graph/project_01",
+		"project01:webview": "tsx src/cli.ts webview -o ./.ts_knowledge_graph/project_01",
+		"project01:report": "tsx src/cli.ts report -o ./.ts_knowledge_graph/project_01",
+		"project02": "npm run project02:rebuild && npm run project02:dead-exports",
+		"project02:tour": "bash scripts/project_02_tour.sh",
+		"project02:rebuild": "npm run project02:clean && npm run project02:extract && npm run project02:load",
+		"project02:clean": "rm -rf ./.ts_knowledge_graph/project_02/graph ./.ts_knowledge_graph/project_02/graph.kuzu ./.ts_knowledge_graph/project_02/prof",
+		"project02:extract": "tsx src/cli.ts extract sample_projects/project_02/src --semantic -o ./.ts_knowledge_graph/project_02",
+		"project02:load": "tsx src/cli.ts load -o ./.ts_knowledge_graph/project_02",
+		"project02:enrich": "bash scripts/profile_and_enrich.sh project_02",
+		"project02:benchmark": "tsx src/cli.ts benchmark parseTerm --workload scripts/benchmarks/project_02_workload.ts -o ./.ts_knowledge_graph/project_02 --root ./sample_projects/project_02 --runs 5",
+		"project02:verify": "tsx src/cli.ts verify --cwd sample_projects/project_02",
+		"project02:dead-exports": "tsx src/cli.ts dead-exports -o ./.ts_knowledge_graph/project_02",
+		"project02:hotspots": "tsx src/cli.ts hotspots -o ./.ts_knowledge_graph/project_02",
+		"project02:cost": "tsx src/cli.ts cost -o ./.ts_knowledge_graph/project_02",
+		"project02:cluster": "tsx src/cli.ts cluster -o ./.ts_knowledge_graph/project_02",
+		"project02:find": "tsx src/cli.ts find -o ./.ts_knowledge_graph/project_02",
+		"project02:who-calls": "tsx src/cli.ts who-calls -o ./.ts_knowledge_graph/project_02",
+		"project02:calls": "tsx src/cli.ts calls -o ./.ts_knowledge_graph/project_02",
+		"project02:references": "tsx src/cli.ts references -o ./.ts_knowledge_graph/project_02",
+		"project02:neighbors": "tsx src/cli.ts neighbors -o ./.ts_knowledge_graph/project_02",
+		"project02:blast-radius": "tsx src/cli.ts blast-radius -o ./.ts_knowledge_graph/project_02",
+		"project02:webview": "tsx src/cli.ts webview -o ./.ts_knowledge_graph/project_02",
+		"project02:report": "tsx src/cli.ts report -o ./.ts_knowledge_graph/project_02",
+		"project03": "npm run project03:rebuild && npm run project03:dead-exports",
+		"project03:tour": "bash scripts/project_03_tour.sh",
+		"project03:rebuild": "npm run project03:clean && npm run project03:extract && npm run project03:load",
+		"project03:clean": "rm -rf ./.ts_knowledge_graph/project_03/graph ./.ts_knowledge_graph/project_03/graph.kuzu ./.ts_knowledge_graph/project_03/prof",
+		"project03:extract": "tsx src/cli.ts extract sample_projects/project_03/src --semantic -o ./.ts_knowledge_graph/project_03",
+		"project03:load": "tsx src/cli.ts load -o ./.ts_knowledge_graph/project_03",
+		"project03:enrich": "bash scripts/profile_and_enrich.sh project_03",
+		"project03:benchmark": "tsx src/cli.ts benchmark describe --workload scripts/benchmarks/project_03_workload.ts -o ./.ts_knowledge_graph/project_03 --root ./sample_projects/project_03 --runs 5",
+		"project03:verify": "tsx src/cli.ts verify --cwd sample_projects/project_03",
+		"project03:dead-exports": "tsx src/cli.ts dead-exports -o ./.ts_knowledge_graph/project_03",
+		"project03:hotspots": "tsx src/cli.ts hotspots -o ./.ts_knowledge_graph/project_03",
+		"project03:cost": "tsx src/cli.ts cost -o ./.ts_knowledge_graph/project_03",
+		"project03:cluster": "tsx src/cli.ts cluster -o ./.ts_knowledge_graph/project_03",
+		"project03:find": "tsx src/cli.ts find -o ./.ts_knowledge_graph/project_03",
+		"project03:who-calls": "tsx src/cli.ts who-calls -o ./.ts_knowledge_graph/project_03",
+		"project03:calls": "tsx src/cli.ts calls -o ./.ts_knowledge_graph/project_03",
+		"project03:references": "tsx src/cli.ts references -o ./.ts_knowledge_graph/project_03",
+		"project03:neighbors": "tsx src/cli.ts neighbors -o ./.ts_knowledge_graph/project_03",
+		"project03:blast-radius": "tsx src/cli.ts blast-radius -o ./.ts_knowledge_graph/project_03",
+		"project03:webview": "tsx src/cli.ts webview -o ./.ts_knowledge_graph/project_03",
+		"project03:report": "tsx src/cli.ts report -o ./.ts_knowledge_graph/project_03",
+		"project04": "npm run project04:rebuild && npm run project04:dead-exports",
+		"project04:tour": "bash scripts/project_04_tour.sh",
+		"project04:rebuild": "npm run project04:clean && npm run project04:extract && npm run project04:load",
+		"project04:clean": "rm -rf ./.ts_knowledge_graph/project_04/graph ./.ts_knowledge_graph/project_04/graph.kuzu ./.ts_knowledge_graph/project_04/prof",
+		"project04:extract": "tsx src/cli.ts extract sample_projects/project_04/src --semantic -o ./.ts_knowledge_graph/project_04",
+		"project04:load": "tsx src/cli.ts load -o ./.ts_knowledge_graph/project_04",
+		"project04:enrich": "bash scripts/profile_and_enrich.sh project_04",
+		"project04:workload": "tsx scripts/benchmarks/project_04_workload.ts",
+		"project04:verify": "tsx src/cli.ts verify --cwd sample_projects/project_04",
+		"project04:dead-exports": "tsx src/cli.ts dead-exports -o ./.ts_knowledge_graph/project_04",
+		"project04:hotspots": "tsx src/cli.ts hotspots -o ./.ts_knowledge_graph/project_04",
+		"project04:cost": "tsx src/cli.ts cost -o ./.ts_knowledge_graph/project_04",
+		"project04:cluster": "tsx src/cli.ts cluster -o ./.ts_knowledge_graph/project_04",
+		"project04:find": "tsx src/cli.ts find -o ./.ts_knowledge_graph/project_04",
+		"project04:who-calls": "tsx src/cli.ts who-calls -o ./.ts_knowledge_graph/project_04",
+		"project04:calls": "tsx src/cli.ts calls -o ./.ts_knowledge_graph/project_04",
+		"project04:references": "tsx src/cli.ts references -o ./.ts_knowledge_graph/project_04",
+		"project04:neighbors": "tsx src/cli.ts neighbors -o ./.ts_knowledge_graph/project_04",
+		"project04:blast-radius": "tsx src/cli.ts blast-radius -o ./.ts_knowledge_graph/project_04",
+		"project04:webview": "tsx src/cli.ts webview -o ./.ts_knowledge_graph/project_04",
+		"project04:report": "tsx src/cli.ts report -o ./.ts_knowledge_graph/project_04"
 	},
 	"dependencies": {
 		"chalk": "^5.3.0",
 		"commander": "^12.1.0",
 		"kuzu": "^0.11.3",
-		"openai": "^6.42.0",
+		"networkanalysis-ts": "^1.0.0",
 		"ts-morph": "^23.0.0",
 		"zod": "^3.23.8"
 	},
 	"devDependencies": {
 		"@types/node": "^20.14.0",
+		"puppeteer": "^25.1.0",
 		"tsx": "^4.16.0",
 		"typescript": "^5.5.0"
 	}