ts-knowledge-graph 0.1.1 → 0.1.4

package/README.md

@@ -1,9 +1,15 @@
-# open_ts_optim_ai
+# ts_knowledge_graph
 
 Parse TypeScript source code into a **knowledge graph**, then use that graph as
 the substrate for an autonomous AI agent that finds and applies code
 optimizations.
 
+## Documentation
+
+Full documentation lives in [`./docs`](docs/INDEX.md). The
+[documentation index](docs/INDEX.md) describes every guide and command — start
+there, or jump straight to [Getting Started](docs/GETTING_STARTED.md).
+
 ## Why a graph
 
 An optimization agent constantly needs to reason about *blast radius*:
@@ -19,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**
 
@@ -28,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 — 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`.
 
-The structural layer is cheap and always emitted. The type + behavioral 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
 
@@ -63,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
@@ -70,8 +90,12 @@ 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
+[Static Analysis guide](docs/STATIC_ANALYSIS.md).
 
 > **`dead-exports` accuracy:** it is member-aware (a class/interface counts as
 > live when any contained member is referenced) and considers `CALLS`,
@@ -79,29 +103,50 @@ JSON out.
 > and `READS` (value-identifier) edges. On this repository it reports exactly the
 > two genuinely-unused type aliases — no false positives.
 
-### The optimization agent
+### Web visualisation
 
-The end goal: an agent that uses the graph to find and apply optimizations,
-verifying each one before keeping it.
+Serve the database as an interactive graph — pan/zoom, kind filters, symbol
+search, per-node edge listing (see
+[contribs/web_visualisation](contribs/web_visualisation)):
 
 ```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
+npm run web            # reads ./outputs/graph.kuzu, serves http://localhost:4173
+npm run web -- --db ./outputs/graph.kuzu --port 8080
 ```
 
-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 optimization agent
 
-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.
+The end goal: an agent that uses the graph to find and apply optimizations,
+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
+```
+
+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
 
@@ -109,25 +154,26 @@ find/replace with in-memory backups; run on a clean git tree so you can review
 src/
   schema/        Zod schemas for nodes and edges (the wire format)
   extract/
-    project-loader.ts        load a ts-morph Project from tsconfig
-    node-id.ts               deterministic, position-stable node ids
-    structural-extractor.ts  modules, declarations, imports, containment
-    semantic-extractor.ts    heritage, CALLS, INSTANTIATES, type edges
-    graph-builder.ts         orchestrates extraction, dedupes by id
+    project_loader.ts        load a ts-morph Project from tsconfig
+    node_id.ts               deterministic, position-stable node ids
+    structural_extractor.ts  modules, declarations, imports, containment
+    semantic_extractor.ts    heritage, CALLS, INSTANTIATES, type edges
+    graph_builder.ts         orchestrates extraction, dedupes by id
   store/
-    jsonl-store.ts           serialize the graph to JSONL
-    jsonl-reader.ts          read + Zod-validate the JSONL back in
-    kuzu-store.ts            load the graph into embedded Kùzu, run Cypher
+    jsonl_store.ts           serialize the graph to JSONL
+    jsonl_reader.ts          read + Zod-validate the JSONL back in
+    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
+    graph_query.ts           the agent's query tools (who-calls, blast-radius…)
+  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
@@ -144,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

@@ -0,0 +1,83 @@
+# Web visualisation
+
+Interactive viewer for the knowledge graph — pan/zoom, color-coded node and
+edge kinds with toggleable filters, symbol search, and a per-node detail panel
+showing every incoming/outgoing edge.
+
+**No server required.** The page (in [web/](web)) is fully static; only the
+Cytoscape.js library comes from a CDN (so you need internet, or vendor the
+file).
+
+## Commands
+
+```bash
+npm run build    # embed ../../outputs/graph/*.jsonl into web/data/graph_data.js
+npm start        # serve web/ on http://localhost:4173 (optional)
+npm run open     # open web/index.html directly (file://, macOS)
+```
+
+## Loading data — pick one
+
+**A. Embed the data, then open the page** (works from `file://`, no server):
+
+```bash
+# from the repo root, after `npm run extract -- . --semantic`
+cd contribs/web_visualisation
+npm run build
+npm run open
+```
+
+`scripts/build-data.ts` reads `../../outputs/graph/{nodes,edges}.jsonl` by
+default; pass a different graph directory as the first argument
+(`npx tsx scripts/build-data.ts /path/to/graph`).
+
+**B. Drag & drop** — open `web/index.html` any way at all and drop
+`outputs/graph/nodes.jsonl` + `outputs/graph/edges.jsonl` onto the page.
+
+**C. Serve the repo root** — the page then auto-fetches
+`../../../outputs/graph/*.jsonl`:
+
+```bash
+# from the repo root
+npx serve        # or: python3 -m http.server
+# open http://localhost:3000/contribs/web_visualisation/web/
+```
+
+## Reading the graph
+
+- **Node size** scales with degree (how connected a symbol is).
+- **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

@@ -0,0 +1,219 @@
+* { box-sizing: border-box; }
+
+html, body {
+	margin: 0;
+	height: 100%;
+	font: 13px/1.45 -apple-system, 'Segoe UI', Roboto, sans-serif;
+	background: #0f172a;
+	color: #cbd5e1;
+}
+
+body { display: flex; }
+
+#sidebar {
+	width: 300px;
+	flex: none;
+	height: 100%;
+	overflow-y: auto;
+	padding: 14px;
+	background: #111c33;
+	border-right: 1px solid #1e293b;
+}
+
+#sidebar h1 { font-size: 15px; margin: 0 0 4px; color: #f1f5f9; }
+#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 {
+	width: 100%;
+	padding: 6px 8px;
+	border: 1px solid #334155;
+	border-radius: 6px;
+	background: #0f172a;
+	color: #e2e8f0;
+}
+#search:focus { outline: none; border-color: #4f8cff; }
+
+#search-results { margin-top: 4px; }
+#search-results .hit {
+	padding: 3px 6px;
+	border-radius: 4px;
+	cursor: pointer;
+	font-size: 12px;
+	white-space: nowrap;
+	overflow: hidden;
+	text-overflow: ellipsis;
+}
+#search-results .hit:hover { background: #1e293b; }
+#search-results .hit .loc { color: #64748b; font-size: 10px; }
+
+.legend label {
+	display: flex;
+	align-items: center;
+	gap: 6px;
+	padding: 1px 0;
+	cursor: pointer;
+	user-select: none;
+}
+.legend .swatch {
+	width: 10px;
+	height: 10px;
+	border-radius: 3px;
+	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; }
+
+select, button {
+	background: #1e293b;
+	color: #e2e8f0;
+	border: 1px solid #334155;
+	border-radius: 6px;
+	padding: 4px 8px;
+	font: inherit;
+	cursor: pointer;
+}
+button:hover { background: #334155; }
+select { flex: 1; }
+
+#details-body { font-size: 12px; }
+#details-body .id { color: #64748b; font-size: 10px; word-break: break-all; }
+#details-body .kind-tag {
+	display: inline-block;
+	padding: 1px 6px;
+	border-radius: 4px;
+	font-size: 10px;
+	color: #0f172a;
+	font-weight: 600;
+}
+#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%; }
+
+#dropzone {
+	position: fixed;
+	inset: 0;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	font-size: 18px;
+	color: #e2e8f0;
+	background: rgba(15, 23, 42, .85);
+	border: 3px dashed #4f8cff;
+	pointer-events: none;
+	opacity: 0;
+	transition: opacity .15s;
+}
+#dropzone.active { opacity: 1; }
+#dropzone code { color: #7db2ff; }

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

@@ -0,0 +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

@@ -0,0 +1,74 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="utf-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1">
+	<title>open_ts_optim_ai — knowledge graph</title>
+	<link rel="stylesheet" href="./css/style.css">
+</head>
+<body>
+	<aside id="sidebar">
+		<h1>Knowledge graph</h1>
+		<div id="status">no data loaded</div>
+
+		<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 class="foldable" data-fold="node-kinds">Node kinds</h2>
+			<div id="node-kinds" class="legend"></div>
+		</section>
+
+		<section>
+			<h2 class="foldable" data-fold="edge-kinds">Edge kinds</h2>
+			<div id="edge-kinds" class="legend"></div>
+		</section>
+
+		<section>
+			<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">
+					<option value="cose">cose (force)</option>
+					<option value="concentric">concentric (by degree)</option>
+					<option value="breadthfirst">breadthfirst</option>
+					<option value="circle">circle</option>
+					<option value="grid">grid</option>
+				</select>
+				<button id="relayout">layout</button>
+			</div>
+		</section>
+
+		<section id="details" class="empty">
+			<h2 class="foldable" data-fold="selection">Selection</h2>
+			<div id="details-body">click a node</div>
+		</section>
+	</aside>
+
+	<main id="cy"></main>
+
+	<div id="dropzone" class="hidden-overlay">
+		<div>drop <code>nodes.jsonl</code> + <code>edges.jsonl</code> here</div>
+	</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>
+</html>