ts-knowledge-graph 0.1.4 → 0.1.6

package/README.md

@@ -37,11 +37,15 @@ hosts), and `Endpoint` (HTTP routes).
 | Type | `EXTENDS`, `IMPLEMENTS`, `USES_TYPE`, `RETURNS`, `PARAM_TYPE` |
 | Behavioral | `CALLS`, `INSTANTIATES`, `OVERRIDES`, `READS`, `WRITES` |
 | System-level | `READS_CONFIG`, `CALLS_EXTERNAL`, `HANDLES` |
+| Runtime | `CALLS_RUNTIME` |
 
 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`.
+`HANDLES`) layers require symbol resolution and are emitted with `--semantic`. The
+runtime layer (`CALLS_RUNTIME`) is reconstructed from a CPU profile's call tree by
+[`enrich`](docs/commands/enrich.md), not parsed from source — the calls that
+actually fired, dynamic dispatch included.
 
 `ConfigFlag` nodes come from `process.env.X` reads; `ExternalAPI` nodes from
 `fetch(...)` call sites (one per host); `Endpoint` nodes from route registrations
@@ -61,9 +65,9 @@ npm run extract -- <path-to-project>
 npm run extract -- <path-to-project> --semantic
 ```
 
-Output is two JSONL files — `outputs/graph/nodes.jsonl` and
-`outputs/graph/edges.jsonl` (override with `--out`) — one record per line, easy
-to inspect, diff, and load into any store.
+Output is two JSONL files — `.ts_knowledge_graph/graph/nodes.jsonl` and
+`.ts_knowledge_graph/graph/edges.jsonl` (override the base folder with `-o, --output-folder`)
+— one record per line, easy to inspect, diff, and load into any store.
 
 ### Querying the graph
 
@@ -71,7 +75,7 @@ Load the JSONL into an embedded [Kùzu](https://kuzudb.com) database, then run t
 query tools:
 
 ```bash
-npm run dev -- load        # reads ./outputs/graph, writes ./outputs/graph.kuzu
+npm run dev -- load        # reads ./.ts_knowledge_graph/graph, writes ./.ts_knowledge_graph/graph.kuzu
 
 npm run dev -- find <name>                 # resolve a name to node ids
 npm run dev -- who-calls <id>              # direct callers of a symbol
@@ -83,6 +87,7 @@ 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
+npm run dev -- cluster                      # detect code communities (Leiden) -> metadata.community
 ```
 
 Every query command accepts `--json` to emit machine-readable output — this is
@@ -107,11 +112,11 @@ answer impact, dead-code, and dependency questions — see the
 
 Serve the database as an interactive graph — pan/zoom, kind filters, symbol
 search, per-node edge listing (see
-[contribs/web_visualisation](contribs/web_visualisation)):
+[contribs/webview](contribs/webview)):
 
 ```bash
-npm run web            # reads ./outputs/graph.kuzu, serves http://localhost:4173
-npm run web -- --db ./outputs/graph.kuzu --port 8080
+npm run webview            # reads ./.ts_knowledge_graph/graph.kuzu, serves http://localhost:4173
+npm run webview -- -o ./.ts_knowledge_graph --port 8080
 ```
 
 ### The optimization agent
@@ -148,6 +153,15 @@ 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/`.
 
+To install all of them into another project, run
+[`install`](docs/commands/install.md) from that project — it copies every
+bundled command and skill into the project's `.claude/` directory:
+
+```bash
+npx ts-knowledge-graph install            # into ./.claude
+npx ts-knowledge-graph install --force    # overwrite previously installed copies
+```
+
 ## Architecture
 
 ```
@@ -210,5 +224,9 @@ declaration node the structural layer emitted.
   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.
+- [x] **Community detection** — the [`cluster`](docs/commands/cluster.md) command
+  runs the Leiden algorithm (CPM) over the weighted coupling graph and attaches a
+  module index onto nodes as `metadata.community`, with the internal-connectedness
+  guarantee Louvain lacks.
 - [ ] **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 → webview}/README.md

@@ -1,4 +1,4 @@
-# Web visualisation
+# WebView
 
 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
@@ -11,7 +11,7 @@ file).
 ## Commands
 
 ```bash
-npm run build    # embed ../../outputs/graph/*.jsonl into web/data/graph_data.js
+npm run build    # embed ../../.ts_knowledge_graph/graph/*.jsonl into web/js_autogenerated/graph_data.js
 npm start        # serve web/ on http://localhost:4173 (optional)
 npm run open     # open web/index.html directly (file://, macOS)
 ```
@@ -22,25 +22,25 @@ npm run open     # open web/index.html directly (file://, macOS)
 
 ```bash
 # from the repo root, after `npm run extract -- . --semantic`
-cd contribs/web_visualisation
+cd contribs/webview
 npm run build
 npm run open
 ```
 
-`scripts/build-data.ts` reads `../../outputs/graph/{nodes,edges}.jsonl` by
+`scripts/build-data.ts` reads `../../.ts_knowledge_graph/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.
+`.ts_knowledge_graph/graph/nodes.jsonl` + `.ts_knowledge_graph/graph/edges.jsonl` onto the page.
 
 **C. Serve the repo root** — the page then auto-fetches
-`../../../outputs/graph/*.jsonl`:
+`../../../.ts_knowledge_graph/graph/*.jsonl`:
 
 ```bash
 # from the repo root
 npx serve        # or: python3 -m http.server
-# open http://localhost:3000/contribs/web_visualisation/web/
+# open http://localhost:3000/contribs/webview/web/
 ```
 
 ## Reading the graph

package/contribs/webview/web/css/style.css

@@ -0,0 +1,310 @@
+/* Dark theme (default). Every colour is a variable so a single `data-theme`
+   attribute on <html> repaints the whole viewer; see [data-theme="light"] below
+   and the matching graph-canvas variables read by js/app.js (cyStyle). */
+:root {
+	color-scheme: dark;
+	--bg: #0f172a;
+	--surface: #111c33;
+	--surface-raised: #1e293b;
+	--surface-hover: #334155;
+	--border: #1e293b;
+	--border-control: #334155;
+	--border-subtle: #475569;
+	--input-bg: #0f172a;
+	--text: #cbd5e1;
+	--heading: #f1f5f9;
+	--muted: #64748b;
+	--muted-strong: #94a3b8;
+	--text-on-control: #e2e8f0;
+	--accent: #4f8cff;
+	--link: #7db2ff;
+	--tooltip-bg: #0b1424;
+	--tooltip-text: #e2e8f0;
+	--overlay-bg: rgba(15, 23, 42, .85);
+	--shadow: 0 4px 14px rgba(0, 0, 0, .45);
+	--on-swatch: #0f172a;
+	--num: #f59e0b;
+	--unmeasured-fill: #243044;
+	--unmeasured-border: #475569;
+	/* Graph canvas colours, read from JS so the graph tracks the theme. */
+	--graph-label: #cbd5e1;
+	--graph-label-bg: #0f172a;
+	--graph-sel-border: #ffffff;
+	--graph-node-border: #334155;
+	--graph-node-border-width: 0;
+}
+
+[data-theme="light"] {
+	color-scheme: light;
+	--bg: #f8fafc;
+	--surface: #f1f5f9;
+	--surface-raised: #e2e8f0;
+	--surface-hover: #cbd5e1;
+	--border: #e2e8f0;
+	--border-control: #cbd5e1;
+	--border-subtle: #94a3b8;
+	--input-bg: #ffffff;
+	--text: #334155;
+	--heading: #0f172a;
+	--muted: #64748b;
+	--muted-strong: #475569;
+	--text-on-control: #1e293b;
+	--accent: #2563eb;
+	--link: #2563eb;
+	--tooltip-bg: #ffffff;
+	--tooltip-text: #1e293b;
+	--overlay-bg: rgba(226, 232, 240, .85);
+	--shadow: 0 4px 14px rgba(15, 23, 42, .18);
+	--on-swatch: #0f172a;
+	--num: #b45309;
+	--unmeasured-fill: #e2e8f0;
+	--unmeasured-border: #94a3b8;
+	--graph-label: #334155;
+	--graph-label-bg: #f8fafc;
+	--graph-sel-border: #0f172a;
+	--graph-node-border: #cbd5e1;
+	--graph-node-border-width: 1;
+}
+
+* { box-sizing: border-box; }
+
+html, body {
+	margin: 0;
+	height: 100%;
+	font: 13px/1.45 -apple-system, 'Segoe UI', Roboto, sans-serif;
+	background: var(--bg);
+	color: var(--text);
+}
+
+body { display: flex; }
+
+#sidebar {
+	width: 300px;
+	flex: none;
+	height: 100%;
+	overflow-y: auto;
+	padding: 14px;
+	background: var(--surface);
+	border-right: 1px solid var(--border);
+}
+
+.sidebar-head { display: flex; align-items: center; gap: 8px; margin: 0 0 4px; }
+#sidebar h1 { font-size: 15px; margin: 0; flex: 1; color: var(--heading); }
+#sidebar h2 { font-size: 11px; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); margin: 16px 0 6px; }
+#sidebar section { margin-top: 8px; }
+
+.theme-toggle {
+	flex: none;
+	width: 26px;
+	height: 26px;
+	padding: 0;
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	font-size: 14px;
+	line-height: 1;
+	border-radius: 6px;
+	background: var(--surface-raised);
+	color: var(--text-on-control);
+	border: 1px solid var(--border-control);
+	cursor: pointer;
+}
+.theme-toggle:hover { background: var(--surface-hover); }
+
+#sidebar .foldable {
+	display: flex;
+	align-items: center;
+	gap: 7px;
+	line-height: 1;
+	cursor: pointer;
+	user-select: none;
+}
+#sidebar .foldable:hover { color: var(--muted-strong); }
+#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: var(--muted); margin-bottom: 10px; }
+
+#search {
+	width: 100%;
+	padding: 6px 8px;
+	border: 1px solid var(--border-control);
+	border-radius: 6px;
+	background: var(--input-bg);
+	color: var(--text-on-control);
+}
+#search:focus { outline: none; border-color: var(--accent); }
+
+#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: var(--surface-raised); }
+#search-results .hit .loc { color: var(--muted); 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: var(--muted); font-size: 11px; }
+.legend .help-badge {
+	flex: none;
+	width: 13px;
+	height: 13px;
+	border-radius: 50%;
+	border: 1px solid var(--border-subtle);
+	color: var(--muted-strong);
+	font-size: 9px;
+	font-weight: 600;
+	line-height: 11px;
+	text-align: center;
+	user-select: none;
+	opacity: 0.5;
+}
+.legend .help-badge:hover,
+.legend .help-badge:focus {
+	background: var(--surface-hover);
+	color: var(--text-on-control);
+	border-color: var(--muted);
+	outline: none;
+}
+.legend label.master {
+	margin-bottom: 4px;
+	padding-bottom: 4px;
+	border-bottom: 1px solid var(--border);
+	color: var(--muted-strong);
+}
+.legend .swatch.spacer { background: transparent; }
+
+.kind-tooltip {
+	position: fixed;
+	z-index: 1000;
+	max-width: 260px;
+	padding: 6px 9px;
+	border-radius: 6px;
+	background: var(--tooltip-bg);
+	border: 1px solid var(--border-control);
+	color: var(--tooltip-text);
+	font-size: 11px;
+	line-height: 1.4;
+	box-shadow: var(--shadow);
+	pointer-events: none;
+}
+.kind-tooltip[hidden] { display: none; }
+
+.row { display: flex; align-items: center; gap: 6px; margin: 4px 0; }
+
+select, button {
+	background: var(--surface-raised);
+	color: var(--text-on-control);
+	border: 1px solid var(--border-control);
+	border-radius: 6px;
+	padding: 4px 8px;
+	font: inherit;
+	cursor: pointer;
+}
+button:hover { background: var(--surface-hover); }
+select { flex: 1; }
+.colour-by label { font-size: 12px; color: var(--muted-strong); white-space: nowrap; }
+
+#details-body { font-size: 12px; }
+#details-body .id { color: var(--muted); font-size: 10px; word-break: break-all; }
+#details-body .kind-tag {
+	display: inline-block;
+	padding: 1px 6px;
+	border-radius: 4px;
+	font-size: 10px;
+	color: var(--on-swatch);
+	font-weight: 600;
+}
+#details-body h3 { font-size: 11px; color: var(--muted); margin: 10px 0 3px; }
+#details-body .edge-row { padding: 1px 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+#details-body .edge-kind { color: var(--muted); font-size: 10px; }
+#details-body .edge-count { color: var(--num); font-size: 10px; font-variant-numeric: tabular-nums; }
+#details-body a { color: var(--link); 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; }
+
+#communities.empty { display: none; }
+
+#coverage { font-size: 11px; color: var(--muted-strong); 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: var(--muted); }
+
+.heat-note { display: flex; align-items: center; gap: 6px; font-size: 10px; color: var(--muted); }
+.heat-swatch { width: 10px; height: 10px; border-radius: 3px; flex: none; display: inline-block; }
+.heat-swatch.unmeasured { background: var(--unmeasured-fill); border: 1px dashed var(--unmeasured-border); }
+
+.hotspots-title { font-size: 11px; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); 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: var(--surface-raised); }
+.hotspot-name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.hotspot-ms { margin-left: auto; flex: none; color: var(--num); 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: var(--muted); }
+
+#cy { flex: 1; height: 100%; }
+
+#dropzone {
+	position: fixed;
+	inset: 0;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	font-size: 18px;
+	color: var(--text-on-control);
+	background: var(--overlay-bg);
+	border: 3px dashed var(--accent);
+	pointer-events: none;
+	opacity: 0;
+	transition: opacity .15s;
+}
+#dropzone.active { opacity: 1; }
+#dropzone code { color: var(--link); }

package/contribs/{web_visualisation → webview}/web/index.html

@@ -3,21 +3,47 @@
 <head>
 	<meta charset="utf-8">
 	<meta name="viewport" content="width=device-width, initial-scale=1">
-	<title>open_ts_optim_ai — knowledge graph</title>
+	<title>ts-knowledge-graph - WebView</title>
+	<script>
+		/* Resolve the theme before the stylesheet paints so there is no flash of
+		   the wrong colours. js/app.js owns the toggle and persistence after this. */
+		(function () {
+			try {
+				var stored = localStorage.getItem('ktg.theme');
+				var theme = stored === 'light' || stored === 'dark'
+					? stored
+					: (window.matchMedia && window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark');
+				document.documentElement.setAttribute('data-theme', theme);
+			} catch (error) {
+				document.documentElement.setAttribute('data-theme', 'dark');
+			}
+		})();
+	</script>
 	<link rel="stylesheet" href="./css/style.css">
 </head>
 <body>
 	<aside id="sidebar">
-		<h1>Knowledge graph</h1>
+		<div class="sidebar-head">
+			<h1>Knowledge graph</h1>
+			<button id="theme-toggle" class="theme-toggle" type="button" aria-label="Switch theme"></button>
+		</div>
 		<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>
 
+		<div class="row colour-by">
+			<label for="encoding-select">Colour by</label>
+			<select id="encoding-select">
+				<option value="structural">kind</option>
+				<option value="runtime">self-time (heat)</option>
+				<option value="community">community</option>
+			</select>
+		</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>
@@ -39,11 +65,17 @@
 			<div id="edge-kinds" class="legend"></div>
 		</section>
 
+		<section id="communities" class="empty">
+			<h2 class="foldable" data-fold="communities">Communities</h2>
+			<div id="community-legend" 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="fcose">fcose (force, label-aware)</option>
 					<option value="cose">cose (force)</option>
 					<option value="concentric">concentric (by degree)</option>
 					<option value="breadthfirst">breadthfirst</option>
@@ -66,9 +98,12 @@
 		<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="./js_autogenerated/graph_data.js"></script>
+	<script src="./js_autogenerated/kind_descriptions.js"></script>
 	<script src="https://unpkg.com/cytoscape@3/dist/cytoscape.min.js"></script>
+	<script src="https://unpkg.com/layout-base/layout-base.js"></script>
+	<script src="https://unpkg.com/cose-base/cose-base.js"></script>
+	<script src="https://unpkg.com/cytoscape-fcose/cytoscape-fcose.js"></script>
 	<script src="./js/app.js"></script>
 </body>
 </html>