ts-knowledge-graph 0.1.4 → 0.1.6

package/contribs/{web_visualisation → webview}/web/js/app.js

@@ -37,10 +37,11 @@ const EDGE_COLORS = {
 	READS_CONFIG: '#65a30d',
 	CALLS_EXTERNAL: '#e11d48',
 	HANDLES: '#0ea5e9',
+	CALLS_RUNTIME: '#be123c',
 };
 
 /* One-line descriptions per node/edge kind, generated from src/schema into
-   data/kind_descriptions.js. Absent (empty) when that file has not been built. */
+   js_autogenerated/kind_descriptions.js. Absent (empty) when that file has not been built. */
 const KIND_DESCRIPTIONS = window.KIND_DESCRIPTIONS ?? { nodes: {}, edges: {} };
 
 /* Heat ramp for runtime self-time: cool slate → yellow → red ("red = hot"). */
@@ -50,11 +51,11 @@ const HEAT_STOPS = [
 	{ at: 1, color: [220, 38, 38] },
 ];
 
-/* Un-measured nodes render at a neutral baseline, distinct from a cheap-but-measured node. */
-const RUNTIME_UNMEASURED_COLOR = '#243044';
-const RUNTIME_UNMEASURED_BORDER = '#475569';
 const HOTSPOTS_LIMIT = 12;
 
+/* Persisted theme override ('light' | 'dark'); absent means follow the OS. */
+const THEME_STORAGE_KEY = 'ktg.theme';
+
 /** @type {AppState} */
 const state = {
 	nodes: [],
@@ -62,13 +63,22 @@ const state = {
 	cy: undefined,
 	hiddenNodeKinds: new Set(),
 	hiddenEdgeKinds: new Set(),
+	hiddenCommunities: new Set(),
 	hideIsolated: false,
 	onlyMeasured: false,
 	droppedFiles: { nodes: undefined, edges: undefined },
 	encoding: 'structural',
 	runtime: { maxSelfMs: 0, measuredCount: 0, totalSelfMs: 0 },
+	communities: [],
+	communityLabels: new Map(),
 };
 
+/* Register the fcose layout extension (loaded as a CDN global, see index.html) so the
+   label-aware force layout is selectable. Guarded so a missing script never breaks the viewer. */
+if (window.cytoscapeFcose !== undefined) {
+	cytoscape.use(window.cytoscapeFcose);
+}
+
 /**
  * Looks up a required element by id, throwing when it is absent so a missing
  * template node fails loudly here instead of as a later `null` dereference.
@@ -122,18 +132,32 @@ const asInput = (target) => {
 	return target;
 };
 
+/**
+ * Narrows a change-event target to a `<select>` so `.value` can be read inside
+ * the encoding-selector handler.
+ * @param {EventTarget | null} target
+ * @returns {HTMLSelectElement}
+ */
+const asSelect = (target) => {
+	if ((target instanceof HTMLSelectElement) === false) {
+		throw new Error('event target is not a select');
+	}
+	return target;
+};
+
 /* ---------- data loading ---------- */
 
 function boot() {
 	setupDropzone();
 	setupFolds();
+	setupTheme();
 	el('hide-isolated').addEventListener('change', (event) => {
 		state.hideIsolated = asInput(event.target).checked;
 		applyFilters();
 	});
 	el('relayout').addEventListener('click', () => runLayout());
-	el('runtime-heat').addEventListener('change', (event) => {
-		state.encoding = asInput(event.target).checked === true ? 'runtime' : 'structural';
+	el('encoding-select').addEventListener('change', (event) => {
+		state.encoding = encodingFromValue(asSelect(event.target).value);
 		if (state.cy !== undefined) {
 			state.cy.style(cyStyle());
 		}
@@ -166,12 +190,12 @@ function boot() {
 async function tryFetch() {
 	try {
 		const [nodesText, edgesText] = await Promise.all([
-			fetch('../../../outputs/graph/nodes.jsonl').then((r) => r.ok === true ? r.text() : Promise.reject(new Error(String(r.status)))),
-			fetch('../../../outputs/graph/edges.jsonl').then((r) => r.ok === true ? r.text() : Promise.reject(new Error(String(r.status)))),
+			fetch('../../../.ts_knowledge_graph/graph/nodes.jsonl').then((r) => r.ok === true ? r.text() : Promise.reject(new Error(String(r.status)))),
+			fetch('../../../.ts_knowledge_graph/graph/edges.jsonl').then((r) => r.ok === true ? r.text() : Promise.reject(new Error(String(r.status)))),
 		]);
-		setData(parseJsonl(nodesText), parseJsonl(edgesText), 'fetched ../../../outputs/graph/*.jsonl');
+		setData(parseJsonl(nodesText), parseJsonl(edgesText), 'fetched ../../../.ts_knowledge_graph/graph/*.jsonl');
 	} catch {
-		el('status').textContent = 'no data — generate data/graph_data.js or drop the JSONL files here';
+		el('status').textContent = 'no data — generate js_autogenerated/graph_data.js or drop the JSONL files here';
 	}
 }
 
@@ -272,6 +296,83 @@ function setupFolds() {
 	}
 }
 
+/* ---------- theme ---------- */
+
+/**
+ * Reads a CSS custom property off the document root, trimmed. The Cytoscape
+ * style pulls its theme-dependent colours from the same variables the stylesheet
+ * uses, so switching theme is a single attribute flip plus a graph re-style.
+ * @param {string} name
+ * @returns {string}
+ */
+function cssVar(name) {
+	return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+}
+
+/**
+ * Reads the persisted theme override, or `null` when none is set or storage is unavailable.
+ * @returns {'light' | 'dark' | null}
+ */
+function storedTheme() {
+	try {
+		const value = localStorage.getItem(THEME_STORAGE_KEY);
+		return value === 'light' || value === 'dark' ? value : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Resolves the active theme: an explicit stored choice wins, otherwise the OS
+ * `prefers-color-scheme`, otherwise dark.
+ * @returns {'light' | 'dark'}
+ */
+function resolveTheme() {
+	const stored = storedTheme();
+	if (stored !== null) {
+		return stored;
+	}
+	return window.matchMedia('(prefers-color-scheme: light)').matches === true ? 'light' : 'dark';
+}
+
+/**
+ * Applies a theme: flips the `data-theme` attribute the stylesheet keys off,
+ * updates the toggle glyph, and re-styles the graph so its canvas-drawn colours
+ * (labels, selection ring, node borders) track the theme.
+ * @param {'light' | 'dark'} theme
+ */
+function applyTheme(theme) {
+	document.documentElement.setAttribute('data-theme', theme);
+	const toggle = el('theme-toggle');
+	toggle.textContent = theme === 'dark' ? '☀' : '☾';
+	toggle.title = theme === 'dark' ? 'Switch to light theme' : 'Switch to dark theme';
+	if (state.cy !== undefined) {
+		state.cy.style(cyStyle());
+	}
+}
+
+/**
+ * Wires the theme toggle: clicking persists and applies the opposite theme, and
+ * — while no explicit choice is stored — the viewer follows later OS changes.
+ */
+function setupTheme() {
+	applyTheme(resolveTheme());
+	el('theme-toggle').addEventListener('click', () => {
+		const next = document.documentElement.getAttribute('data-theme') === 'dark' ? 'light' : 'dark';
+		try {
+			localStorage.setItem(THEME_STORAGE_KEY, next);
+		} catch {
+			/* storage unavailable (private mode, file://) — apply for this session only */
+		}
+		applyTheme(next);
+	});
+	window.matchMedia('(prefers-color-scheme: light)').addEventListener('change', (event) => {
+		if (storedTheme() === null) {
+			applyTheme(event.matches === true ? 'light' : 'dark');
+		}
+	});
+}
+
 /* ---------- graph construction ---------- */
 
 /**
@@ -305,11 +406,13 @@ function setData(nodes, edges, sourceLabel) {
 		maxSelfMs = Math.max(maxSelfMs, selfMs);
 	}
 	state.runtime = { maxSelfMs, measuredCount, totalSelfMs };
+	state.communities = communityCounts(nodes);
+	state.communityLabels = communityLabels(nodes);
 
 	const elements = [
 		...nodes.map((node) => ({
 			group: 'nodes',
-			data: { id: node.id, name: node.name, kind: node.kind, filePath: node.filePath, startLine: node.range === undefined ? 0 : node.range.startLine, exported: node.exported === true, degree: degree.get(node.id) ?? 0, runtime: nodeRuntime(node) },
+			data: { id: node.id, name: node.name, kind: node.kind, filePath: node.filePath, startLine: node.range === undefined ? 0 : node.range.startLine, exported: node.exported === true, degree: degree.get(node.id) ?? 0, runtime: nodeRuntime(node), community: nodeCommunity(node) },
 		})),
 		...edges
 			.filter((edge) => nodeIds.has(edge.from) === true && nodeIds.has(edge.to) === true)
@@ -326,7 +429,7 @@ function setData(nodes, edges, sourceLabel) {
 		container: el('cy'),
 		elements,
 		style: cyStyle(),
-		layout: { name: 'cose', animate: false, padding: 30 },
+		layout: layoutOptions('fcose'),
 	});
 	state.cy.on('tap', 'node', (event) => select(event.target));
 	state.cy.on('tap', (event) => {
@@ -337,21 +440,31 @@ function setData(nodes, edges, sourceLabel) {
 
 	buildLegends();
 	renderRuntime();
+	renderCommunities();
+	syncEncodingOptions();
 	applyFilters();
 	el('status').textContent = `${sourceLabel} — ${nodes.length} nodes, ${edges.length} edges`;
 }
 
 function cyStyle() {
+	const unmeasuredFill = cssVar('--unmeasured-fill');
+	const unmeasuredBorder = cssVar('--unmeasured-border');
+	const nodeBorder = cssVar('--graph-node-border');
+	const nodeBorderWidth = parseFloat(cssVar('--graph-node-border-width')) || 0;
+	const labelColor = cssVar('--graph-label');
+	const labelBg = cssVar('--graph-label-bg');
+	const selBorder = cssVar('--graph-sel-border');
 	/** @param {CyCollection} node */
 	const nodeColor = (node) => {
-		if (state.encoding !== 'runtime') {
-			return NODE_COLORS[node.data('kind')] ?? '#9ca3af';
+		if (state.encoding === 'runtime') {
+			const runtime = node.data('runtime');
+			return runtime === undefined || runtime === null ? unmeasuredFill : heatColor(runtimeFraction(runtime.selfMs));
 		}
-		const runtime = node.data('runtime');
-		if (runtime === undefined || runtime === null) {
-			return RUNTIME_UNMEASURED_COLOR;
+		if (state.encoding === 'community') {
+			const community = node.data('community');
+			return community === undefined || community === null ? unmeasuredFill : communityColor(community);
 		}
-		return heatColor(runtimeFraction(runtime.selfMs));
+		return NODE_COLORS[node.data('kind')] ?? '#9ca3af';
 	};
 	/** @param {CyCollection} node */
 	const nodeSize = (node) => {
@@ -364,8 +477,15 @@ function cyStyle() {
 		}
 		return 12 + runtimeFraction(runtime.selfMs) * 40;
 	};
-	/** @param {CyCollection} node */
-	const isUnmeasured = (node) => node.data('runtime') === undefined || node.data('runtime') === null;
+	/**
+	 * Whether the active encoding has no value for this node — un-measured in
+	 * runtime mode, or unassigned to a community in community mode. Such nodes get
+	 * the muted fill and a dashed border so the gap reads as "no data", not a colour.
+	 * @param {CyCollection} node
+	 */
+	const isUnencoded = (node) =>
+		(state.encoding === 'runtime' && (node.data('runtime') === undefined || node.data('runtime') === null))
+		|| (state.encoding === 'community' && (node.data('community') === undefined || node.data('community') === null));
 	return [
 		{
 			selector: 'node',
@@ -373,15 +493,19 @@ function cyStyle() {
 				'background-color': nodeColor,
 				'width': nodeSize,
 				'height': nodeSize,
-				'border-width': (/** @type {CyCollection} */ node) => state.encoding === 'runtime' && isUnmeasured(node) === true ? 1 : 0,
-				'border-color': RUNTIME_UNMEASURED_BORDER,
-				'border-style': 'dashed',
+				'border-width': (/** @type {CyCollection} */ node) => isUnencoded(node) === true ? 1 : nodeBorderWidth,
+				'border-color': (/** @type {CyCollection} */ node) => isUnencoded(node) === true ? unmeasuredBorder : nodeBorder,
+				'border-style': (/** @type {CyCollection} */ node) => isUnencoded(node) === true ? 'dashed' : 'solid',
 				'label': 'data(name)',
-				'color': '#cbd5e1',
+				'color': labelColor,
 				'font-size': 8,
 				'min-zoomed-font-size': 7,
 				'text-valign': 'bottom',
 				'text-margin-y': 3,
+				'text-background-color': labelBg,
+				'text-background-opacity': 0.5,
+				'text-background-shape': 'roundrectangle',
+				'text-background-padding': 2,
 			},
 		},
 		{
@@ -397,21 +521,36 @@ function cyStyle() {
 			},
 		},
 		{ selector: '.hidden', style: { display: 'none' } },
-		{ selector: '.faded', style: { opacity: 0.08, 'text-opacity': 0 } },
-		{ selector: 'node.sel', style: { 'border-width': 3, 'border-color': '#ffffff', 'border-style': 'solid' } },
+		{ selector: '.faded', style: { opacity: 0.08, 'text-opacity': 0, 'text-background-opacity': 0 } },
+		{ selector: 'node.sel', style: { 'border-width': 3, 'border-color': selBorder, 'border-style': 'solid' } },
 	];
 }
 
+/**
+ * Builds Cytoscape layout options for the given layout name. The force layouts
+ * (`fcose`, `cose`) are made label-aware via `nodeDimensionsIncludeLabels`, so each
+ * node's label box is factored into spacing and labels overlap their neighbours less.
+ * @param {string} name
+ * @returns {Record<string, unknown>}
+ */
+function layoutOptions(name) {
+	const base = { name, animate: false, padding: 30 };
+	if (name === 'fcose' || name === 'cose') {
+		return { ...base, nodeDimensionsIncludeLabels: true };
+	}
+	if (name === 'concentric') {
+		return { ...base, concentric: (/** @type {CyCollection} */ node) => node.degree(), levelWidth: () => 2 };
+	}
+	return base;
+}
+
 function runLayout() {
 	const cy = state.cy;
 	if (cy === undefined) {
 		return;
 	}
 	const name = selectEl('layout-select').value;
-	const options = name === 'concentric'
-		? { name, concentric: (/** @type {CyCollection} */ node) => node.degree(), levelWidth: () => 2, animate: false, padding: 30 }
-		: { name, animate: false, padding: 30 };
-	cy.elements(':visible').layout(options).run();
+	cy.elements(':visible').layout(layoutOptions(name)).run();
 }
 
 /* ---------- edge weighting ---------- */
@@ -612,7 +751,9 @@ function applyFilters() {
 			const hiddenByKind = state.hiddenNodeKinds.has(node.data('kind')) === true;
 			const unmeasured = node.data('runtime') === undefined || node.data('runtime') === null;
 			const hiddenByMeasure = state.onlyMeasured === true && unmeasured === true;
-			node.toggleClass('hidden', hiddenByKind === true || hiddenByMeasure === true);
+			const community = node.data('community');
+			const hiddenByCommunity = community !== undefined && community !== null && state.hiddenCommunities.has(community) === true;
+			node.toggleClass('hidden', hiddenByKind === true || hiddenByMeasure === true || hiddenByCommunity === true);
 		});
 		cy.edges().forEach((edge) => {
 			edge.toggleClass('hidden', state.hiddenEdgeKinds.has(edge.data('kind')) === true);
@@ -729,7 +870,6 @@ function focusNode(id) {
 /** Renders the coverage line and the ranked hotspots list from the loaded runtime metrics. */
 function renderRuntime() {
 	const section = el('runtime');
-	const toggle = inputEl('runtime-heat');
 	const measured = state.nodes
 		.map((node) => ({ node, runtime: nodeRuntime(node) }))
 		.filter((entry) => entry.runtime !== undefined)
@@ -738,20 +878,13 @@ function renderRuntime() {
 	if (measured.length === 0) {
 		section.classList.add('empty');
 		el('coverage').textContent = 'no runtime data — run `enrich` to measure self-time';
-		toggle.checked = false;
-		toggle.disabled = true;
-		state.encoding = 'structural';
 		state.onlyMeasured = false;
 		inputEl('only-measured').checked = false;
 		el('hotspots').innerHTML = '';
-		if (state.cy !== undefined) {
-			state.cy.style(cyStyle());
-		}
 		return;
 	}
 
 	section.classList.remove('empty');
-	toggle.disabled = false;
 	inputEl('only-measured').disabled = false;
 	el('coverage').textContent = `${state.runtime.measuredCount} / ${state.nodes.length} nodes measured · ${formatMs(state.runtime.totalSelfMs)} total self-time`;
 
@@ -766,6 +899,212 @@ function renderRuntime() {
 	}
 }
 
+/* ---------- community ---------- */
+
+/**
+ * Reads the integer community index `cluster` attaches as `metadata.community`,
+ * or `undefined` when the graph has not been clustered.
+ * @param {RawNode} node
+ * @returns {number | undefined}
+ */
+function nodeCommunity(node) {
+	if (node.metadata === undefined || node.metadata === null) {
+		return undefined;
+	}
+	const community = node.metadata.community;
+	return typeof community === 'number' ? community : undefined;
+}
+
+/**
+ * Reads the human-readable community label `cluster` attaches as
+ * `metadata.communityLabel`. Every clustered node carries one, written alongside
+ * its community index, so this is defined whenever {@link nodeCommunity} is.
+ * @param {RawNode} node
+ * @returns {string | undefined}
+ */
+function nodeCommunityLabel(node) {
+	if (node.metadata === undefined || node.metadata === null) {
+		return undefined;
+	}
+	const label = node.metadata.communityLabel;
+	return typeof label === 'string' ? label : undefined;
+}
+
+/**
+ * A stable, theme-independent colour per community index, spread around the hue
+ * circle by the golden angle so adjacent indices stay distinct. Fixed
+ * saturation/lightness keep it legible on both the light and dark canvas, like
+ * the kind palette.
+ * @param {number} index
+ * @returns {string}
+ */
+function communityColor(index) {
+	const hue = Math.round((index * 137.508) % 360);
+	return `hsl(${hue}, 65%, 55%)`;
+}
+
+/**
+ * Counts members per community across the loaded nodes, as `[index, count]`
+ * pairs sorted by size descending (the order `cluster` reports them in).
+ * @param {RawNode[]} nodes
+ * @returns {[number, number][]}
+ */
+function communityCounts(nodes) {
+	/** @type {Map<number, number>} */
+	const counts = new Map();
+	for (const node of nodes) {
+		const community = nodeCommunity(node);
+		if (community !== undefined) {
+			counts.set(community, (counts.get(community) ?? 0) + 1);
+		}
+	}
+	return [...counts.entries()].sort((a, b) => b[1] - a[1]);
+}
+
+/**
+ * Maps each community index to its label, read from the first member node seen —
+ * `cluster` writes the same label onto every member, so one read per community
+ * suffices.
+ * @param {RawNode[]} nodes
+ * @returns {Map<number, string>}
+ */
+function communityLabels(nodes) {
+	/** @type {Map<number, string>} */
+	const labels = new Map();
+	for (const node of nodes) {
+		const community = nodeCommunity(node);
+		if (community === undefined || labels.has(community) === true) {
+			continue;
+		}
+		const label = nodeCommunityLabel(node);
+		if (label !== undefined) {
+			labels.set(community, label);
+		}
+	}
+	return labels;
+}
+
+/**
+ * Renders the Communities legend as visibility filters — a checkbox + swatch +
+ * member count per community, plus a master "all" toggle — so a community can be
+ * shown or hidden on the graph, mirroring the node/edge kind legends. The section
+ * is hidden when the graph is un-clustered.
+ */
+function renderCommunities() {
+	const section = el('communities');
+	const container = el('community-legend');
+	container.innerHTML = '';
+	if (state.communities.length === 0) {
+		section.classList.add('empty');
+		return;
+	}
+	section.classList.remove('empty');
+
+	const indices = state.communities.map(([index]) => index);
+	/** @type {HTMLInputElement[]} */
+	const childCheckboxes = [];
+
+	const master = document.createElement('input');
+	master.type = 'checkbox';
+	const syncMaster = () => {
+		const hiddenCount = indices.filter((index) => state.hiddenCommunities.has(index) === true).length;
+		master.checked = hiddenCount === 0;
+		master.indeterminate = hiddenCount > 0 && hiddenCount < indices.length;
+	};
+	master.addEventListener('change', () => {
+		const allVisible = indices.every((index) => state.hiddenCommunities.has(index) === false);
+		for (const index of indices) {
+			if (allVisible === true) {
+				state.hiddenCommunities.add(index);
+			} else {
+				state.hiddenCommunities.delete(index);
+			}
+		}
+		for (const child of childCheckboxes) {
+			child.checked = state.hiddenCommunities.has(Number(child.dataset.community)) === false;
+		}
+		syncMaster();
+		applyFilters();
+	});
+	const masterLabel = document.createElement('label');
+	masterLabel.className = 'master';
+	masterLabel.title = 'show or hide every community';
+	const spacer = document.createElement('span');
+	spacer.className = 'swatch spacer';
+	const masterText = document.createElement('span');
+	masterText.textContent = 'all';
+	masterLabel.append(master, spacer, masterText);
+	container.appendChild(masterLabel);
+
+	for (const [index, count] of state.communities) {
+		const row = document.createElement('label');
+		const checkbox = document.createElement('input');
+		checkbox.type = 'checkbox';
+		checkbox.dataset.community = String(index);
+		checkbox.checked = state.hiddenCommunities.has(index) === false;
+		checkbox.addEventListener('change', () => {
+			if (checkbox.checked === true) {
+				state.hiddenCommunities.delete(index);
+			} else {
+				state.hiddenCommunities.add(index);
+			}
+			syncMaster();
+			applyFilters();
+		});
+		childCheckboxes.push(checkbox);
+		const swatch = document.createElement('span');
+		swatch.className = 'swatch';
+		swatch.style.background = communityColor(index);
+		const text = document.createElement('span');
+		text.textContent = /** @type {string} */ (state.communityLabels.get(index));
+		const countSpan = document.createElement('span');
+		countSpan.className = 'count';
+		countSpan.textContent = String(count);
+		row.append(checkbox, swatch, text, countSpan);
+		container.appendChild(row);
+	}
+
+	syncMaster();
+}
+
+/**
+ * Enables the `self-time` and `community` colour modes only when the loaded
+ * graph carries that data, falls back to `structural` if the active mode lost
+ * its data, mirrors the choice into the `<select>`, and re-applies the style.
+ */
+function syncEncodingOptions() {
+	const select = selectEl('encoding-select');
+	/**
+	 * @param {string} value
+	 * @param {boolean} enabled
+	 */
+	const setEnabled = (value, enabled) => {
+		const option = select.querySelector(`option[value="${value}"]`);
+		if (option instanceof HTMLOptionElement) {
+			option.disabled = enabled === false;
+		}
+	};
+	setEnabled('runtime', state.runtime.measuredCount > 0);
+	setEnabled('community', state.communities.length > 0);
+	if ((state.encoding === 'runtime' && state.runtime.measuredCount === 0)
+		|| (state.encoding === 'community' && state.communities.length === 0)) {
+		state.encoding = 'structural';
+	}
+	select.value = state.encoding;
+	if (state.cy !== undefined) {
+		state.cy.style(cyStyle());
+	}
+}
+
+/**
+ * Narrows an arbitrary `<select>` value to a known encoding mode, defaulting to `structural`.
+ * @param {string} value
+ * @returns {'structural' | 'runtime' | 'community'}
+ */
+function encodingFromValue(value) {
+	return value === 'runtime' || value === 'community' ? value : 'structural';
+}
+
 /* ---------- search ---------- */
 
 function renderSearchResults() {

package/contribs/{web_visualisation/web/data → webview/web/js_autogenerated}/kind_descriptions.js

@@ -33,6 +33,7 @@ window.KIND_DESCRIPTIONS = {
 		"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)."
+		"HANDLES": "Links an HTTP endpoint to the function that handles it (route to handler).",
+		"CALLS_RUNTIME": "A call observed at runtime in a CPU profile: the source function or method was on the stack directly above the target. Captures dynamic dispatch that static CALLS cannot see."
 	}
 };

package/contribs/{web_visualisation → webview}/web/types/app_globals.d.ts

@@ -33,7 +33,7 @@ interface RawNode {
 	filePath: string;
 	range?: RawRange;
 	exported?: boolean;
-	metadata?: { runtime?: NodeRuntime | null; [key: string]: unknown } | null;
+	metadata?: { runtime?: NodeRuntime | null; community?: number | null; communityLabel?: string | null; [key: string]: unknown } | null;
 }
 
 /** A graph edge as serialised in `edges.jsonl`; mirrors `GraphEdgeSchema`. */
@@ -57,7 +57,7 @@ interface KindDescriptions {
 	edges: Record<string, string>;
 }
 
-/** GitHub permalink descriptor; mirrors `GitHubSource` in `src/commands/web_command.ts`. */
+/** GitHub permalink descriptor; mirrors `GitHubSource` in `src/commands/webview_command.ts`. */
 interface GitHubSource {
 	baseUrl: string;
 	commit: string;
@@ -76,11 +76,14 @@ interface AppState {
 	cy: CyCore | undefined;
 	hiddenNodeKinds: Set<string>;
 	hiddenEdgeKinds: Set<string>;
+	hiddenCommunities: Set<number>;
 	hideIsolated: boolean;
 	onlyMeasured: boolean;
 	droppedFiles: { nodes: RawNode[] | undefined; edges: RawEdge[] | undefined };
-	encoding: 'structural' | 'runtime';
+	encoding: 'structural' | 'runtime' | 'community';
 	runtime: { maxSelfMs: number; measuredCount: number; totalSelfMs: number };
+	communities: [number, number][];
+	communityLabels: Map<number, string>;
 }
 
 /* ---------- Cytoscape.js (loaded as a CDN global, untyped) ---------- */
@@ -136,6 +139,10 @@ interface CytoscapeOptions {
 }
 
 declare function cytoscape(options?: CytoscapeOptions): CyCore;
+declare namespace cytoscape {
+	/** Registers a Cytoscape extension (such as the fcose layout) loaded as a CDN global. */
+	function use(extension: unknown): void;
+}
 
 /* ---------- globals injected into the page ---------- */
 
@@ -143,4 +150,5 @@ interface Window {
 	GRAPH_DATA?: GraphData;
 	KIND_DESCRIPTIONS?: KindDescriptions;
 	GRAPH_SOURCE?: GraphSource | null;
+	cytoscapeFcose?: unknown;
 }

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAmBA,qBAAa,GAAG;IACf,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;CAyBhC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAqBA,qBAAa,GAAG;IACf,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;CA2BhC"}

package/dist/cli.js

@@ -3,6 +3,7 @@ import { Command } from 'commander';
 import { BenchmarkCommand } from './commands/benchmark_command.js';
 import { BlastRadiusCommand } from './commands/blast_radius_command.js';
 import { CallsCommand } from './commands/calls_command.js';
+import { ClusterCommand } from './commands/cluster_command.js';
 import { CostCommand } from './commands/cost_command.js';
 import { DeadExportsCommand } from './commands/dead_exports_command.js';
 import { EnrichCommand } from './commands/enrich_command.js';
@@ -13,8 +14,9 @@ import { InstallCommand } from './commands/install_command.js';
 import { LoadCommand } from './commands/load_command.js';
 import { NeighborsCommand } from './commands/neighbors_command.js';
 import { ReferencesCommand } from './commands/references_command.js';
+import { ReportCommand } from './commands/report_command.js';
 import { VerifyCommand } from './commands/verify_command.js';
-import { WebCommand } from './commands/web_command.js';
+import { WebviewCommand } from './commands/webview_command.js';
 import { WhoCallsCommand } from './commands/who_calls_command.js';
 export class Cli {
     static run(argv) {
@@ -25,6 +27,7 @@ export class Cli {
         ExtractCommand.register(program);
         LoadCommand.register(program);
         EnrichCommand.register(program);
+        ClusterCommand.register(program);
         FindCommand.register(program);
         WhoCallsCommand.register(program);
         CallsCommand.register(program);
@@ -36,7 +39,8 @@ export class Cli {
         BlastRadiusCommand.register(program);
         NeighborsCommand.register(program);
         ReferencesCommand.register(program);
-        WebCommand.register(program);
+        ReportCommand.register(program);
+        WebviewCommand.register(program);
         InstallCommand.register(program);
         void program.parseAsync(argv);
     }