ts-knowledge-graph 0.1.2 → 0.1.4

package/README.md

@@ -25,7 +25,9 @@ Compiler API) rather than a syntax-only parser.
 ## Graph model
 
 **Nodes** — `Module`, `Class`, `Interface`, `TypeAlias`, `Enum`, `Function`,
-`Method`, `Property`, `Parameter`, `Variable`, `ExternalModule`.
+`Method`, `Property`, `Parameter`, `Variable`, `ExternalModule`, and the
+system-level `ConfigFlag` (environment variables), `ExternalAPI` (outbound HTTP
+hosts), and `Endpoint` (HTTP routes).
 
 **Edges**
 
@@ -34,9 +36,18 @@ Compiler API) rather than a syntax-only parser.
 | Structural | `CONTAINS`, `IMPORTS`, `EXPORTS` |
 | Type | `EXTENDS`, `IMPLEMENTS`, `USES_TYPE`, `RETURNS`, `PARAM_TYPE` |
 | Behavioral | `CALLS`, `INSTANTIATES`, `OVERRIDES`, `READS`, `WRITES` |
+| System-level | `READS_CONFIG`, `CALLS_EXTERNAL`, `HANDLES` |
 
-The structural layer is cheap and always emitted. The type + behavioral layers
-require symbol resolution and are emitted with `--semantic`.
+The structural layer — plus the always-on config and outbound-HTTP surfaces
+(`ConfigFlag` / `READS_CONFIG`, `ExternalAPI` / `CALLS_EXTERNAL`) — is cheap and
+needs no symbol resolution. The type, behavioral, and endpoint (`Endpoint` /
+`HANDLES`) layers require symbol resolution and are emitted with `--semantic`.
+
+`ConfigFlag` nodes come from `process.env.X` reads; `ExternalAPI` nodes from
+`fetch(...)` call sites (one per host); `Endpoint` nodes from route registrations
+like `app.get('/users', handler)`, each with a `HANDLES` edge to the handler
+function. These are the system-level kinds tracked in
+[#31](https://github.com/jeromeetienne/ts_knowledge_graph/issues/31).
 
 ## Usage
 
@@ -69,6 +80,9 @@ npm run dev -- blast-radius <id> --depth 10  # transitive callers (impact set)
 npm run dev -- references <id>             # everything that references a symbol/type
 npm run dev -- dead-exports                # exported symbols with no inbound refs
 npm run dev -- neighbors <id>              # one-hop neighbourhood (in + out)
+npm run dev -- hotspots --by self-time     # rank nodes by optimization leverage
+npm run dev -- cost                        # inclusive cost + share-of-total (causal)
+npm run dev -- cost <id>                    # where one node's cost goes / who causes it
 ```
 
 Every query command accepts `--json` to emit machine-readable output — this is
@@ -76,8 +90,8 @@ the shape the optimization agent consumes. Node ids come from `find` or another
 query's results; do not hand-write them.
 
 The query methods on `GraphQuery` (`whoCalls`, `blastRadius`, `deadExports`,
-`neighborhood`, …) are designed to map one-to-one onto agent tools: JSON in,
-JSON out.
+`hotspots`, `costRanking`, `costAttribution`, `neighborhood`, …) are designed to
+map one-to-one onto agent tools: JSON in, JSON out.
 
 For a task-oriented walk-through of these commands — using them by hand to
 answer impact, dead-code, and dependency questions — see the
@@ -103,26 +117,36 @@ npm run web -- --db ./outputs/graph.kuzu --port 8080
 ### The optimization agent
 
 The end goal: an agent that uses the graph to find and apply optimizations,
-verifying each one before keeping it.
-
-```bash
-cp .env-sample .env                 # pick a provider block, set key + model
-npm run dev -- optimize --db ./outputs/graph.kuzu
-npm run dev -- optimize "Inline the single-use helper X" --db ./outputs/graph.kuzu --model gpt-5.1
+verifying each one before keeping it. It ships as a [Claude Code](https://claude.com/claude-code)
+slash command, `/code-graph-optimize`, defined in
+[`dotclaude_folder/commands/code-graph-optimize.md`](dotclaude_folder/commands/code-graph-optimize.md)
+— so the agent runtime is your Claude Code subscription, with no API key or
+provider configuration to set up.
+
+```text
+/code-graph-optimize
+/code-graph-optimize Inline the single-use helper X
 ```
 
-The LLM layer sits on the **OpenAI-compatible chat-completions API**, so any
-provider exposing that surface works — OpenAI, OpenRouter, Ollama, LM Studio,
-vLLM — configured entirely through `OPENAI_API_KEY`, `OPENAI_BASE_URL`, and
-`OPENAI_MODEL` (see [.env-sample](.env-sample)).
-
-The agent runs a tool-calling loop. Its tools are the read-only `GraphQuery`
-methods plus `read_file`; it gathers context, confirms blast radius, then calls
-`propose_optimization`. The harness **applies the edit, runs `tsc --noEmit`,
-and keeps it only if type-checking passes** — otherwise it reverts and hands
-the compiler errors back for another attempt. Edits are unique-match
-find/replace with in-memory backups; run on a clean git tree so you can review
-(and `git checkout`) what it kept.
+With no argument the command runs its default mission: find one genuinely dead
+exported symbol, confirm it has zero inbound references, and remove it safely.
+
+The command drives a find → confirm → edit → verify loop. It queries the graph
+through this CLI (`dead-exports`, `references`, `who-calls`, `blast-radius`) to
+gather context and confirm blast radius, makes exactly one edit, then runs
+[`ts-knowledge-graph verify`](docs/commands/verify.md) — the type-check **and**
+the test suite as a single gate. **If verify passes the edit stands; if it fails
+the edit is reverted with `git restore`** and the change is abandoned or retried.
+On a project with no test script verify degrades to type-check-only and the agent
+says so, rather than implying the change was behaviourally verified. Run it on a
+clean git tree so you can review (and `git checkout`) what it kept.
+
+A companion command, `/code-graph-interview`
+([`code-graph-interview.md`](dotclaude_folder/commands/code-graph-interview.md)),
+is read-only: it interviews you to scope a measurable optimization target and
+grounds each candidate in the graph, producing tasks you can then hand to
+`/code-graph-optimize`. Both commands, plus the `code-graph-query` skill, live
+under [`dotclaude_folder/`](dotclaude_folder) and are mirrored into `.claude/`.
 
 ## Architecture
 
@@ -141,14 +165,15 @@ src/
     kuzu_store.ts            load the graph into embedded Kùzu, run Cypher
   query/
     graph_query.ts           the agent's query tools (who-calls, blast-radius…)
-  agent/
-    agent_tools.ts           graph queries + read_file + propose_optimization, as LLM tools
-    code_editor.ts           unique-match find/replace with in-memory backup + revert
-    verifier.ts              runs `tsc --noEmit`, returns pass/fail + output
-    optimizer_agent.ts       the LLM tool-calling loop (propose → verify → keep/revert)
-  cli.ts                     extract / load / query / optimize commands
+  commands/                  one file per CLI command (extract, load, query, web, install)
+  cli.ts                     wires the commands into the ts-knowledge-graph CLI
 ```
 
+The optimization agent is not part of this `src/` tree — it is the
+`/code-graph-optimize` Claude Code command under
+[`dotclaude_folder/commands/`](dotclaude_folder/commands), which drives the same
+queries through the CLI.
+
 Node ids are derived purely from the declaration (`kind:relPath#name@line`), so
 any extractor computes the same id for the same symbol without a shared
 registry — that is what lets the semantic layer link a call site to the exact
@@ -165,10 +190,25 @@ declaration node the structural layer emitted.
   contained member is referenced.
 - [x] **Value-reference (`READS`) edges** — value-identifier usage, so exported
   `const`s (e.g. schemas) are no longer false-positive dead exports.
-- [x] **Optimization agent** — an LLM tool-calling loop (OpenAI-compatible API,
-  provider-agnostic) that proposes edits and keeps them only if `tsc --noEmit`
-  passes (otherwise reverts).
-- [ ] **Test verification** — run the test suite alongside `tsc` in the verify
-  step, so behavior-changing edits are caught, not just type errors.
+- [x] **Runtime enrichment** — the [`enrich`](docs/commands/enrich.md) command
+  ingests a V8 CPU profile and attaches measured self time / sample count onto
+  nodes as `metadata.runtime`, joining frames to nodes by enclosing range.
+- [x] **Hotspot / leverage ranking** — the [`hotspots`](docs/commands/hotspots.md)
+  command ranks nodes by optimization value (runtime self-time, fan-in,
+  call-count, or transitive blast radius), defaulting to measured self time when
+  enriched and degrading gracefully to static fan-in when not.
+- [x] **Optimization agent** — the `/code-graph-optimize` Claude Code command,
+  which proposes one edit and keeps it only if [`verify`](docs/commands/verify.md)
+  (type-check **and** tests) passes (otherwise reverts with `git restore`).
+- [x] **Test verification** — the [`verify`](docs/commands/verify.md) command runs
+  the project's `typecheck` and `test` scripts as one keep/revert gate, so
+  behavior-changing edits are caught, not just type errors. A project with no test
+  script degrades to type-check-only, reported honestly (`behaviorVerified: false`).
+- [x] **Benchmark verification** — the [`benchmark`](docs/commands/benchmark.md)
+  command measures a target node's runtime metric (profile → enrich → cost) over
+  N runs and reports the median + spread, with an advisory baseline→after delta —
+  so an optimization is reported by its *measured* impact (e.g. −57% self-time on
+  `titleCase`) rather than a guess. Advisory by design, distinct from the hard
+  `verify` gate.
 - [ ] **Vector index** — embed per-node summaries for hybrid graph + semantic
   retrieval, so the agent can find candidates by meaning, not just by name.

package/contribs/web_visualisation/README.md

@@ -49,7 +49,35 @@ npx serve        # or: python3 -m http.server
 - **Edge colors**: red `CALLS`, green/teal type edges (`USES_TYPE`, `RETURNS`,
   `PARAM_TYPE`), yellow `READS`, violet heritage, gray structure
   (`CONTAINS`, `IMPORTS`).
+- **Edge width** scales with call-site count — how many times the call / import /
+  read occurs between the two symbols (shown as `×N` in the detail panel). Thick
+  edges are the hot connections.
 - Uncheck noisy kinds (`CONTAINS`, `IMPORTS`) to see the behavioral core;
   enable **hide isolated nodes** to drop whatever the filter disconnected.
+- The **all** checkbox atop Node kinds / Edge kinds toggles every kind at once —
+  hide all, then re-check just the few you want to isolate (it shows a dash when
+  only some kinds are visible).
 - Click a node to fade everything outside its neighborhood and list its edges
   in the sidebar — the links navigate the graph.
+- **Fold any sidebar section** by clicking its header (Runtime, Hotspots, Node
+  kinds, Edge kinds, …); the collapsed state is remembered across reloads.
+
+## Runtime hotspots
+
+When the graph has been enriched (`ts-knowledge-graph enrich <profile.cpuprofile>`),
+each measured symbol carries `metadata.runtime` (self-time + sample count). The
+sidebar's **Runtime** panel surfaces it:
+
+- **Coverage line** — how many nodes were measured and the total self-time, so a
+  partial profile reads as partial.
+- **Heat map toggle** — re-encodes the graph by measured self-time: nodes are
+  **sized and heat-coloured** (cool → yellow → red) by how hot they are, instead
+  of by kind/degree. Toggle off to return to the structural view.
+- **Hotspots list** — the top symbols ranked by self-time; click one to focus it.
+- **Only measured nodes** — hides the un-enriched nodes so only the measured
+  subgraph remains, to focus on where the cost actually is.
+- Selecting any node adds a **runtime** block (self-time, samples, source) to the
+  detail panel.
+
+Un-measured nodes render at a neutral, dashed baseline — "no metric" means
+*inlined or not sampled*, not "free".

package/contribs/web_visualisation/web/css/style.css

@@ -24,6 +24,28 @@ body { display: flex; }
 #sidebar h2 { font-size: 11px; text-transform: uppercase; letter-spacing: .06em; color: #64748b; margin: 16px 0 6px; }
 #sidebar section { margin-top: 8px; }
 
+#sidebar .foldable {
+	display: flex;
+	align-items: center;
+	gap: 7px;
+	line-height: 1;
+	cursor: pointer;
+	user-select: none;
+}
+#sidebar .foldable:hover { color: #94a3b8; }
+#sidebar .foldable::before {
+	content: '';
+	flex: none;
+	width: 0;
+	height: 0;
+	border-left: 5px solid currentColor;
+	border-top: 4px solid transparent;
+	border-bottom: 4px solid transparent;
+	transition: transform .12s ease;
+}
+#sidebar .foldable:not(.collapsed)::before { transform: rotate(90deg); }
+#sidebar .foldable.collapsed ~ * { display: none; }
+
 #status { font-size: 11px; color: #64748b; margin-bottom: 10px; }
 
 #search {
@@ -64,6 +86,49 @@ body { display: flex; }
 	flex: none;
 }
 .legend .count { margin-left: auto; color: #64748b; font-size: 11px; }
+.legend .help-badge {
+	flex: none;
+	width: 13px;
+	height: 13px;
+	border-radius: 50%;
+	border: 1px solid #475569;
+	color: #94a3b8;
+	font-size: 9px;
+	font-weight: 600;
+	line-height: 11px;
+	text-align: center;
+	user-select: none;
+}
+.legend .help-badge:hover,
+.legend .help-badge:focus {
+	background: #334155;
+	color: #e2e8f0;
+	border-color: #64748b;
+	outline: none;
+}
+.legend label.master {
+	margin-bottom: 4px;
+	padding-bottom: 4px;
+	border-bottom: 1px solid #1e293b;
+	color: #94a3b8;
+}
+.legend .swatch.spacer { background: transparent; }
+
+.kind-tooltip {
+	position: fixed;
+	z-index: 1000;
+	max-width: 260px;
+	padding: 6px 9px;
+	border-radius: 6px;
+	background: #0b1424;
+	border: 1px solid #334155;
+	color: #e2e8f0;
+	font-size: 11px;
+	line-height: 1.4;
+	box-shadow: 0 4px 14px rgba(0, 0, 0, .45);
+	pointer-events: none;
+}
+.kind-tooltip[hidden] { display: none; }
 
 .row { display: flex; align-items: center; gap: 6px; margin: 4px 0; }
 
@@ -92,8 +157,47 @@ select { flex: 1; }
 #details-body h3 { font-size: 11px; color: #64748b; margin: 10px 0 3px; }
 #details-body .edge-row { padding: 1px 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 #details-body .edge-kind { color: #64748b; font-size: 10px; }
+#details-body .edge-count { color: #f59e0b; font-size: 10px; font-variant-numeric: tabular-nums; }
 #details-body a { color: #7db2ff; cursor: pointer; text-decoration: none; }
 #details-body a:hover { text-decoration: underline; }
+#details-body a.file-link { text-decoration: underline; word-break: break-all; }
+#details-body a.file-link::after { content: '↗'; margin-left: 3px; font-size: 9px; opacity: 0.7; }
+
+#runtime.empty .heat-legend,
+#runtime.empty .heat-note,
+#runtime.empty .hotspots-title,
+#runtime.empty #hotspots,
+#runtime.empty label.row { display: none; }
+
+#coverage { font-size: 11px; color: #94a3b8; margin: 2px 0 6px; }
+
+#runtime label.row { font-size: 12px; }
+
+.heat-legend { display: flex; align-items: center; gap: 6px; margin: 8px 0 4px; }
+.heat-bar { flex: 1; height: 10px; border-radius: 3px; background: linear-gradient(90deg, #64748b, #fde047, #dc2626); }
+.heat-legend .heat-min, .heat-legend .heat-max { font-size: 10px; color: #64748b; }
+
+.heat-note { display: flex; align-items: center; gap: 6px; font-size: 10px; color: #64748b; }
+.heat-swatch { width: 10px; height: 10px; border-radius: 3px; flex: none; display: inline-block; }
+.heat-swatch.unmeasured { background: #243044; border: 1px dashed #475569; }
+
+.hotspots-title { font-size: 11px; text-transform: uppercase; letter-spacing: .06em; color: #64748b; margin: 12px 0 4px; }
+#hotspots .hotspot {
+	display: flex;
+	align-items: center;
+	gap: 6px;
+	padding: 2px 4px;
+	border-radius: 4px;
+	cursor: pointer;
+	font-size: 12px;
+}
+#hotspots .hotspot:hover { background: #1e293b; }
+.hotspot-name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.hotspot-ms { margin-left: auto; flex: none; color: #f59e0b; font-size: 11px; font-variant-numeric: tabular-nums; }
+
+#details-body .runtime-block { margin-top: 8px; }
+#details-body .runtime-block .metric { display: flex; justify-content: space-between; gap: 8px; padding: 1px 0; }
+#details-body .runtime-block .metric span { color: #64748b; }
 
 #cy { flex: 1; height: 100%; }
 

package/contribs/web_visualisation/web/data/.gitignore

@@ -1,2 +1,3 @@
 *
 !.gitignore
+!kind_descriptions.js

package/contribs/web_visualisation/web/data/kind_descriptions.js

@@ -0,0 +1,38 @@
+// @ts-nocheck
+// Generated from src/schema by scripts/build-data.ts. Do not edit by hand.
+window.KIND_DESCRIPTIONS = {
+	"nodes": {
+		"Module": "A source file in the codebase.",
+		"Class": "A class declaration.",
+		"Interface": "An interface declaration.",
+		"TypeAlias": "A type alias declaration.",
+		"Enum": "An enum declaration.",
+		"Function": "A standalone, module-level function.",
+		"Method": "A function that belongs to a class or interface.",
+		"Property": "A field declared on a class or interface.",
+		"Parameter": "A parameter of a function or method.",
+		"Variable": "A module- or block-level variable binding.",
+		"ExternalModule": "An imported third-party or Node.js module, recorded as one opaque node per import specifier.",
+		"ConfigFlag": "An environment-variable configuration flag, detected from process.env reads.",
+		"ExternalAPI": "An outbound HTTP host called through fetch(), with one node per host.",
+		"Endpoint": "An HTTP route registered by the app, such as app.get(\"/users\", handler)."
+	},
+	"edges": {
+		"CONTAINS": "Structural nesting: the source declares or encloses the target (a module contains a class, which contains a method).",
+		"IMPORTS": "The source module imports the target.",
+		"EXPORTS": "The source module exports the target symbol.",
+		"EXTENDS": "The source class or interface extends the target (inheritance).",
+		"IMPLEMENTS": "The source class implements the target interface.",
+		"USES_TYPE": "The source references the target in a type position.",
+		"RETURNS": "The target type appears in the source function or method return type.",
+		"PARAM_TYPE": "The target type appears in one of the source parameter types.",
+		"CALLS": "The source function or method calls the target.",
+		"INSTANTIATES": "The source constructs the target class with new.",
+		"OVERRIDES": "The source method overrides the base-class member it replaces.",
+		"READS": "The source reads the value of the target variable or property.",
+		"WRITES": "The source assigns to the target variable or property.",
+		"READS_CONFIG": "The source reads the target configuration flag (an environment variable).",
+		"CALLS_EXTERNAL": "The source makes an outbound HTTP call to the target external API.",
+		"HANDLES": "Links an HTTP endpoint to the function that handles it (route to handler)."
+	}
+};

package/contribs/web_visualisation/web/index.html

@@ -14,18 +14,33 @@
 		<input id="search" type="search" placeholder="Search symbol or file… (Enter)" autocomplete="off">
 		<div id="search-results"></div>
 
+		<section id="runtime" class="empty">
+			<h2 class="foldable" data-fold="runtime">Runtime</h2>
+			<div id="coverage">no runtime data</div>
+			<label class="row"><input id="runtime-heat" type="checkbox"> heat map (size + colour by self-time)</label>
+			<label class="row"><input id="only-measured" type="checkbox"> only measured nodes</label>
+			<div class="heat-legend">
+				<span class="heat-min">cold</span>
+				<span class="heat-bar"></span>
+				<span class="heat-max">hot</span>
+			</div>
+			<div class="heat-note"><span class="heat-swatch unmeasured"></span> not measured</div>
+			<h3 class="hotspots-title foldable" data-fold="hotspots">Hotspots</h3>
+			<div id="hotspots"></div>
+		</section>
+
 		<section>
-			<h2>Node kinds</h2>
+			<h2 class="foldable" data-fold="node-kinds">Node kinds</h2>
 			<div id="node-kinds" class="legend"></div>
 		</section>
 
 		<section>
-			<h2>Edge kinds</h2>
+			<h2 class="foldable" data-fold="edge-kinds">Edge kinds</h2>
 			<div id="edge-kinds" class="legend"></div>
 		</section>
 
 		<section>
-			<h2>Options</h2>
+			<h2 class="foldable" data-fold="options">Options</h2>
 			<label class="row"><input id="hide-isolated" type="checkbox"> hide isolated nodes</label>
 			<div class="row">
 				<select id="layout-select">
@@ -40,7 +55,7 @@
 		</section>
 
 		<section id="details" class="empty">
-			<h2>Selection</h2>
+			<h2 class="foldable" data-fold="selection">Selection</h2>
 			<div id="details-body">click a node</div>
 		</section>
 	</aside>
@@ -52,6 +67,7 @@
 	</div>
 
 	<script src="./data/graph_data.js"></script>
+	<script src="./data/kind_descriptions.js"></script>
 	<script src="https://unpkg.com/cytoscape@3/dist/cytoscape.min.js"></script>
 	<script src="./js/app.js"></script>
 </body>