ts-knowledge-graph 0.1.2 → 0.1.6

package/dist/query/graph_query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_query.d.ts","sourceRoot":"","sources":["../../src/query/graph_query.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD,MAAM,MAAM,SAAS,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,IAAI,GAAG,KAAK,CAAC;CACxB,CAAC;AAOF,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;gBAEtB,KAAK,EAAE,SAAS;IAItB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAW1C,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAWvC,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAW5D,WAAW,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAiBnC,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAW9C,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAiBhD,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAYjD,OAAO,CAAC,MAAM,CAAC,MAAM;IAIrB,OAAO,CAAC,MAAM,CAAC,KAAK;IAUpB,OAAO,CAAC,MAAM,CAAC,UAAU;IAIzB,OAAO,CAAC,MAAM,CAAC,UAAU;CAUzB"}
+{"version":3,"file":"graph_query.d.ts","sourceRoot":"","sources":["../../src/query/graph_query.ts"],"names":[],"mappings":"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"}

package/dist/query/graph_query.js

@@ -1,5 +1,19 @@
-const REFERENCE_EDGE_KINDS = "['CALLS', 'IMPLEMENTS', 'EXTENDS', 'USES_TYPE', 'RETURNS', 'PARAM_TYPE', 'INSTANTIATES', 'READS']";
-const RETURN_REF = (variable) => `${variable}.id AS id, ${variable}.kind AS kind, ${variable}.name AS name, ${variable}.filePath AS filePath, ${variable}.startLine AS startLine`;
+import { REFERENCE_EDGE_KINDS } from '../schema/edge.js';
+import { RUNTIME_MANIFEST_KEY, RuntimeManifestSchema } from '../schema/runtime_manifest.js';
+/**
+ * The {@link REFERENCE_EDGE_KINDS} set rendered as a Cypher list literal — e.g.
+ * `['CALLS', 'EXTENDS', …]` — for interpolation into `kind IN …` predicates. The
+ * schema array is the single source of truth; this is its query-side projection.
+ */
+const REFERENCE_EDGE_KINDS_CYPHER = `[${REFERENCE_EDGE_KINDS.map((kind) => `'${kind}'`).join(', ')}]`;
+const RETURN_REF = (variable) => `${variable}.id AS id, ${variable}.kind AS kind, ${variable}.name AS name, ${variable}.filePath AS filePath, ${variable}.startLine AS startLine, ${variable}.metadata AS metadata`;
+/**
+ * Kùzu's hard ceiling on the upper bound of a variable-length relationship: a
+ * pattern like `-[e:Edge*1..N]-` with `N > 30` is rejected by the binder at query
+ * time. {@link GraphQuery.clampDepth} caps `--depth` here so the bound it
+ * interpolates into {@link GraphQuery.blastRadius} is always one Kùzu accepts.
+ */
+const KUZU_MAX_REL_BOUND = 30;
 export class GraphQuery {
     constructor(store) {
         this.store = store;
@@ -29,41 +43,576 @@ export class GraphQuery {
         const rows = await this.store.run(`MATCH (n:GraphNode)
 			WHERE n.exported = true
 			OPTIONAL MATCH (n)<-[selfRef:Edge]-(:GraphNode)
-			WHERE selfRef.kind IN ${REFERENCE_EDGE_KINDS}
+			WHERE selfRef.kind IN ${REFERENCE_EDGE_KINDS_CYPHER}
 			WITH n, count(selfRef) AS selfRefs
 			OPTIONAL MATCH (n)-[c:Edge]->(member:GraphNode)<-[memberRef:Edge]-(:GraphNode)
-			WHERE c.kind = 'CONTAINS' AND memberRef.kind IN ${REFERENCE_EDGE_KINDS}
+			WHERE c.kind = 'CONTAINS' AND memberRef.kind IN ${REFERENCE_EDGE_KINDS_CYPHER}
 			WITH n, selfRefs, count(memberRef) AS memberRefs
 			WHERE selfRefs = 0 AND memberRefs = 0
 			RETURN ${RETURN_REF('n')}
 			ORDER BY filePath, startLine`);
         return GraphQuery.toRefs(rows);
     }
+    /**
+     * Returns the call cycles in the graph: every strongly-connected component of
+     * the static `CALLS` graph with more than one member, as the list of its
+     * symbols, largest cycle first. A purely static structural signal — it needs no
+     * runtime data — that surfaces mutual-recursion tangles which are hard to spot
+     * by eye. Reuses the same SCC pass {@link GraphQuery.computeCostModel} relies on.
+     */
+    async strongCycles() {
+        const nodes = await this.store.readNodes();
+        const edges = await this.readCallEdges();
+        const indexOf = new Map();
+        nodes.forEach((node, index) => indexOf.set(node.id, index));
+        const successors = nodes.map(() => []);
+        for (const edge of edges) {
+            const from = indexOf.get(edge.fromId);
+            const to = indexOf.get(edge.toId);
+            if (from === undefined || to === undefined || from === to) {
+                continue;
+            }
+            successors[from].push(to);
+        }
+        const { componentOf, componentCount } = GraphQuery.stronglyConnectedComponents(successors);
+        const members = Array.from({ length: componentCount }, () => []);
+        componentOf.forEach((component, index) => members[component].push(index));
+        return members
+            .filter((group) => group.length > 1)
+            .map((group) => group.map((index) => GraphQuery.symbolOf(nodes[index])))
+            .sort((a, b) => b.length - a.length);
+    }
     async references(id) {
         const rows = await this.store.run(`MATCH (n:GraphNode {id: $id})<-[e:Edge]-(other:GraphNode)
-			WHERE e.kind IN ${REFERENCE_EDGE_KINDS}
-			RETURN ${RETURN_REF('other')}, e.kind AS edgeKind
+			WHERE e.kind IN ${REFERENCE_EDGE_KINDS_CYPHER}
+			RETURN ${RETURN_REF('other')}, e.kind AS edgeKind, e.metadata AS edgeMetadata
 			ORDER BY edgeKind, filePath, startLine`, { id });
         return rows.map((row) => GraphQuery.toNeighbor(row, 'in'));
     }
     async neighborhood(id) {
         const outgoing = await this.store.run(`MATCH (center:GraphNode {id: $id})-[e:Edge]->(other:GraphNode)
-			RETURN ${RETURN_REF('other')}, e.kind AS edgeKind`, { id });
+			RETURN ${RETURN_REF('other')}, e.kind AS edgeKind, e.metadata AS edgeMetadata`, { id });
         const incoming = await this.store.run(`MATCH (center:GraphNode {id: $id})<-[e:Edge]-(other:GraphNode)
-			RETURN ${RETURN_REF('other')}, e.kind AS edgeKind`, { id });
+			RETURN ${RETURN_REF('other')}, e.kind AS edgeKind, e.metadata AS edgeMetadata`, { id });
         return [
             ...outgoing.map((row) => GraphQuery.toNeighbor(row, 'out')),
             ...incoming.map((row) => GraphQuery.toNeighbor(row, 'in')),
         ];
     }
+    /**
+     * Resolves a search pattern to nodes, matching either a substring of the node
+     * name or an exact (case-insensitive) node kind. The kind match makes the
+     * system-level kinds discoverable as a set — `find Endpoint`, `find ConfigFlag`,
+     * `find ExternalAPI` — since their names are values (a route path, a host) rather
+     * than the kind itself. `Module` nodes are always excluded.
+     */
     async find(pattern) {
         const rows = await this.store.run(`MATCH (n:GraphNode)
-			WHERE n.kind <> 'Module' AND lower(n.name) CONTAINS lower($pattern)
+			WHERE n.kind <> 'Module' AND (lower(n.name) CONTAINS lower($pattern) OR lower(n.kind) = lower($pattern))
 			RETURN ${RETURN_REF('n')}
 			ORDER BY filePath, startLine
 			LIMIT 50`, { pattern });
         return GraphQuery.toRefs(rows);
     }
+    /**
+     * Ranks nodes by optimization leverage, returning the top-N for a chosen
+     * metric alongside the context needed to read the result.
+     *
+     * Runtime metrics (`self-time`, `samples`) read `metadata.runtime`; static
+     * metrics (`callers`, `call-count`, `blast-radius`) are derived from the
+     * inbound `CALLS` graph. The whole graph is read once (nodes, and the call
+     * edges when a static metric is used) and ranked in memory rather than per
+     * node, so `blast-radius` does not fan out into one traversal per node.
+     *
+     * The default metric is `self-time` on an enriched graph and `callers`
+     * otherwise. Asking for a runtime metric on an un-enriched graph does not
+     * return empty: it falls back to `callers` and flags `fellBack` so the caller
+     * can say so. Nodes that score zero on the chosen metric are omitted — a
+     * symbol nothing calls is not a fan-in hotspot.
+     */
+    async hotspots(options = {}) {
+        const nodes = await this.store.readNodes();
+        const enriched = nodes.some((node) => GraphQuery.hasRuntime(node.metadata));
+        const requested = options.by ?? (enriched === true ? 'self-time' : 'callers');
+        const fellBack = GraphQuery.isRuntimeMetric(requested) === true && enriched === false;
+        const metric = fellBack === true ? 'callers' : requested;
+        const measuredOnly = options.measuredOnly === true;
+        const limit = GraphQuery.clampLimit(options.limit);
+        const scores = await this.scoreNodes(nodes, metric);
+        const candidates = measuredOnly === true
+            ? nodes.filter((node) => GraphQuery.hasRuntime(node.metadata))
+            : nodes;
+        const hotspots = candidates
+            .map((node) => ({ node, score: scores.get(node.id) ?? 0 }))
+            .filter((entry) => entry.score > 0)
+            .sort((a, b) => b.score - a.score
+            || a.node.filePath.localeCompare(b.node.filePath)
+            || a.node.startLine - b.node.startLine)
+            .slice(0, limit)
+            .map((entry) => GraphQuery.toHotspot(entry.node, entry.score, metric));
+        return { metric, requested, enriched, fellBack, measuredOnly, hotspots };
+    }
+    /**
+     * Ranks nodes by **inclusive cost** — self cost plus the cost attributed from
+     * everything a node transitively calls — and reports each node's share of the
+     * graph's total self cost. This is the causal counterpart to {@link hotspots}'
+     * `self-time` ranking: where hotspots asks "where is time spent?", this asks
+     * "who is *responsible* for the time spent?".
+     *
+     * Cost propagates along `CALLS` edges, each callee's inclusive cost partitioned
+     * among its callers in proportion to call-site `count`, so cost is conserved (a
+     * diamond is not double-counted) and `shareOfTotal` is a true fraction. Call
+     * cycles are collapsed and their members share the cycle's total. The whole
+     * graph is read once and propagated in memory.
+     *
+     * Cost is inherently a runtime quantity: on an un-enriched graph there is no
+     * self cost to propagate, so `nodes` is empty and `enriched` is false — there is
+     * no static fallback (unlike {@link hotspots}).
+     */
+    async costRanking(options = {}) {
+        const nodes = await this.store.readNodes();
+        const enriched = nodes.some((node) => GraphQuery.hasRuntime(node.metadata));
+        const metric = options.by ?? 'self-time';
+        const limit = GraphQuery.clampLimit(options.limit);
+        const flow = await this.resolveFlowEdges(options.edges ?? 'static');
+        const manifest = await this.readRuntimeManifest();
+        const model = GraphQuery.computeCostModel(nodes, flow.edges, metric);
+        const ranked = nodes
+            .map((node) => GraphQuery.toCostRef(node, model))
+            .filter((ref) => ref.inclusiveCost > 0)
+            .sort((a, b) => b.inclusiveCost - a.inclusiveCost
+            || a.filePath.localeCompare(b.filePath)
+            || a.startLine - b.startLine)
+            .slice(0, limit);
+        return {
+            metric,
+            edges: flow.flow,
+            fellBack: flow.fellBack,
+            enriched,
+            totalSelf: model.totalSelf,
+            measuredNodes: model.measuredNodes,
+            coverage: GraphQuery.coverageFor(manifest, metric),
+            nodes: ranked,
+        };
+    }
+    /**
+     * Breaks one node's cost down causally: where its inclusive cost goes
+     * (`callees`, each carrying the cost its subtree contributes) and who is
+     * responsible for it (`callers`, how the node's cost is attributed upward by
+     * call-count share). Both are derived from the same propagation
+     * {@link costRanking} uses. Returns `node: null` when the id resolves to no node.
+     */
+    async costAttribution(id, options = {}) {
+        const nodes = await this.store.readNodes();
+        const enriched = nodes.some((node) => GraphQuery.hasRuntime(node.metadata));
+        const metric = options.by ?? 'self-time';
+        const flow = await this.resolveFlowEdges(options.edges ?? 'static');
+        const manifest = await this.readRuntimeManifest();
+        const model = GraphQuery.computeCostModel(nodes, flow.edges, metric);
+        const nodeById = new Map(nodes.map((node) => [node.id, node]));
+        const coverage = GraphQuery.coverageFor(manifest, metric);
+        const focal = nodeById.get(id);
+        if (focal === undefined) {
+            return { metric, edges: flow.flow, fellBack: flow.fellBack, enriched, totalSelf: model.totalSelf, coverage, node: null, callees: [], callers: [] };
+        }
+        const focalRef = GraphQuery.toCostRef(focal, model);
+        const focalComponent = model.componentOf.get(id);
+        const focalInclusive = focalRef.inclusiveCost;
+        const focalInbound = model.externalInbound.get(id) ?? 0;
+        const callees = [];
+        for (const edge of model.outEdges.get(id) ?? []) {
+            if (model.componentOf.get(edge.toId) === focalComponent) {
+                continue;
+            }
+            const callee = nodeById.get(edge.toId);
+            if (callee === undefined) {
+                continue;
+            }
+            const inbound = model.externalInbound.get(edge.toId) ?? 0;
+            const calleeInclusive = model.inclusiveCost.get(edge.toId) ?? 0;
+            const amount = inbound > 0 ? calleeInclusive * edge.count / inbound : 0;
+            const share = focalInclusive > 0 ? amount / focalInclusive : 0;
+            callees.push({ ...GraphQuery.symbolOf(callee), amount, share, callCount: edge.count });
+        }
+        const callers = [];
+        for (const edge of model.inEdges.get(id) ?? []) {
+            if (model.componentOf.get(edge.fromId) === focalComponent) {
+                continue;
+            }
+            const caller = nodeById.get(edge.fromId);
+            if (caller === undefined) {
+                continue;
+            }
+            const amount = focalInbound > 0 ? focalInclusive * edge.count / focalInbound : 0;
+            const share = focalInbound > 0 ? edge.count / focalInbound : 0;
+            callers.push({ ...GraphQuery.symbolOf(caller), amount, share, callCount: edge.count });
+        }
+        callees.sort((a, b) => b.amount - a.amount || a.filePath.localeCompare(b.filePath) || a.startLine - b.startLine);
+        callers.sort((a, b) => b.amount - a.amount || a.filePath.localeCompare(b.filePath) || a.startLine - b.startLine);
+        return { metric, edges: flow.flow, fellBack: flow.fellBack, enriched, totalSelf: model.totalSelf, coverage, node: focalRef, callees, callers };
+    }
+    /**
+     * Reads the runtime ingest manifest `enrich` records at the graph level, or
+     * null when the graph carries none (never enriched, or enriched before manifests
+     * were recorded). A stored value that fails validation is treated as absent.
+     */
+    async readRuntimeManifest() {
+        const raw = await this.store.readGraphMeta(RUNTIME_MANIFEST_KEY);
+        if (raw === null) {
+            return null;
+        }
+        const parsed = RuntimeManifestSchema.safeParse(raw);
+        return parsed.success === true ? parsed.data : null;
+    }
+    /** Builds a node-id → score map for the chosen metric, reading call edges only when a static metric needs them. */
+    async scoreNodes(nodes, metric) {
+        if (metric === 'self-time' || metric === 'samples') {
+            const key = metric === 'self-time' ? 'selfMs' : 'samples';
+            return new Map(nodes.map((node) => [node.id, GraphQuery.runtimeValue(node.metadata, key)]));
+        }
+        const edges = await this.readCallEdges();
+        if (metric === 'call-count') {
+            return GraphQuery.sumInbound(edges, (edge) => edge.count);
+        }
+        if (metric === 'blast-radius') {
+            return GraphQuery.blastRadiusSizes(nodes, edges);
+        }
+        return GraphQuery.sumInbound(edges, () => 1);
+    }
+    /** Reads every `CALLS` edge with its call-site `count` decoded from edge metadata. */
+    async readCallEdges() {
+        const rows = await this.store.run(`MATCH (caller:GraphNode)-[e:Edge]->(callee:GraphNode)
+			WHERE e.kind = 'CALLS'
+			RETURN caller.id AS fromId, callee.id AS toId, e.metadata AS metadata`);
+        return rows.map((row) => ({
+            fromId: String(row.fromId),
+            toId: String(row.toId),
+            count: GraphQuery.callCount(row.metadata),
+        }));
+    }
+    /**
+     * Resolves the call graph cost propagates along. `runtime` reads the
+     * `CALLS_RUNTIME` edges `enrich` records, weighted by sample flow; when the
+     * graph has none (un-enriched, or a profile that captured no in-project calls)
+     * it falls back to the static `CALLS` graph and flags it.
+     */
+    async resolveFlowEdges(requested) {
+        if (requested === 'runtime') {
+            const runtime = await this.readRuntimeCallEdges();
+            if (runtime.length > 0) {
+                return { edges: runtime, flow: 'runtime', fellBack: false };
+            }
+            return { edges: await this.readCallEdges(), flow: 'static', fellBack: true };
+        }
+        return { edges: await this.readCallEdges(), flow: 'static', fellBack: false };
+    }
+    /** Reads every `CALLS_RUNTIME` edge with its runtime `samples` as the propagation weight. */
+    async readRuntimeCallEdges() {
+        const rows = await this.store.run(`MATCH (caller:GraphNode)-[e:Edge]->(callee:GraphNode)
+			WHERE e.kind = 'CALLS_RUNTIME'
+			RETURN caller.id AS fromId, callee.id AS toId, e.metadata AS metadata`);
+        return rows.map((row) => ({
+            fromId: String(row.fromId),
+            toId: String(row.toId),
+            count: GraphQuery.edgeSamples(row.metadata),
+        }));
+    }
+    /** Sums a per-edge weight onto each edge's target, yielding inbound fan-in (`weight = 1`) or call-count (`weight = count`). */
+    static sumInbound(edges, weight) {
+        const totals = new Map();
+        for (const edge of edges) {
+            totals.set(edge.toId, (totals.get(edge.toId) ?? 0) + weight(edge));
+        }
+        return totals;
+    }
+    /** Computes, for every node, the number of distinct nodes that transitively reach it through inbound `CALLS`. */
+    static blastRadiusSizes(nodes, edges) {
+        const callers = new Map();
+        for (const edge of edges) {
+            const bucket = callers.get(edge.toId);
+            if (bucket === undefined) {
+                callers.set(edge.toId, [edge.fromId]);
+            }
+            else {
+                bucket.push(edge.fromId);
+            }
+        }
+        const sizes = new Map();
+        for (const node of nodes) {
+            sizes.set(node.id, GraphQuery.reachableCount(node.id, callers));
+        }
+        return sizes;
+    }
+    /** Counts the distinct ancestors of `start` over the reverse-call adjacency, cycle-safe and excluding `start` itself. */
+    static reachableCount(start, callers) {
+        const visited = new Set();
+        const stack = [...(callers.get(start) ?? [])];
+        while (stack.length > 0) {
+            const id = stack.pop();
+            if (id === undefined || visited.has(id) === true) {
+                continue;
+            }
+            visited.add(id);
+            for (const next of callers.get(id) ?? []) {
+                if (visited.has(next) === false) {
+                    stack.push(next);
+                }
+            }
+        }
+        visited.delete(start);
+        return visited.size;
+    }
+    /**
+     * Propagates self cost into inclusive cost over the whole graph in one pass.
+     *
+     * Self-edges and edges touching unknown nodes are dropped. Strongly-connected
+     * components (call cycles) are collapsed with Tarjan's algorithm, which numbers
+     * them in reverse-topological order (a callee's component before its caller's);
+     * processing components in that order lets each caller read its callees'
+     * already-computed inclusive cost. A callee's inclusive cost is partitioned
+     * among its callers by call-site `count` over the inbound weight from *outside*
+     * its component, so cost is conserved on the acyclic part and a cycle's members
+     * share the cycle's total.
+     */
+    static computeCostModel(nodes, edges, metric) {
+        const key = metric === 'self-time' ? 'selfMs' : 'samples';
+        const count = nodes.length;
+        const indexOf = new Map();
+        nodes.forEach((node, i) => indexOf.set(node.id, i));
+        const self = nodes.map((node) => GraphQuery.runtimeValue(node.metadata, key));
+        const successors = nodes.map(() => []);
+        const outEdges = nodes.map(() => []);
+        const inEdges = nodes.map(() => []);
+        for (const edge of edges) {
+            const from = indexOf.get(edge.fromId);
+            const to = indexOf.get(edge.toId);
+            if (from === undefined || to === undefined || from === to) {
+                continue;
+            }
+            successors[from].push(to);
+            outEdges[from].push({ to, count: edge.count });
+            inEdges[to].push({ from, count: edge.count });
+        }
+        const { componentOf, componentCount } = GraphQuery.stronglyConnectedComponents(successors);
+        const componentSize = new Array(componentCount).fill(0);
+        const selfByComponent = new Array(componentCount).fill(0);
+        const members = Array.from({ length: componentCount }, () => []);
+        for (let i = 0; i < count; i += 1) {
+            const comp = componentOf[i];
+            componentSize[comp] += 1;
+            selfByComponent[comp] += self[i];
+            members[comp].push(i);
+        }
+        const externalInbound = new Array(count).fill(0);
+        for (let to = 0; to < count; to += 1) {
+            for (const edge of inEdges[to]) {
+                if (componentOf[edge.from] !== componentOf[to]) {
+                    externalInbound[to] += edge.count;
+                }
+            }
+        }
+        const inclusiveByComponent = new Array(componentCount).fill(0);
+        for (let comp = 0; comp < componentCount; comp += 1) {
+            let inclusive = selfByComponent[comp];
+            for (const member of members[comp]) {
+                for (const edge of outEdges[member]) {
+                    const target = componentOf[edge.to];
+                    if (target === comp) {
+                        continue;
+                    }
+                    const inbound = externalInbound[edge.to];
+                    if (inbound > 0) {
+                        inclusive += inclusiveByComponent[target] * edge.count / inbound;
+                    }
+                }
+            }
+            inclusiveByComponent[comp] = inclusive;
+        }
+        const model = {
+            totalSelf: 0,
+            measuredNodes: 0,
+            selfCost: new Map(),
+            inclusiveCost: new Map(),
+            componentOf: new Map(),
+            cycleSize: new Map(),
+            externalInbound: new Map(),
+            outEdges: new Map(),
+            inEdges: new Map(),
+        };
+        for (let i = 0; i < count; i += 1) {
+            const node = nodes[i];
+            const comp = componentOf[i];
+            model.totalSelf += self[i];
+            if (GraphQuery.hasRuntime(node.metadata) === true) {
+                model.measuredNodes += 1;
+            }
+            model.selfCost.set(node.id, self[i]);
+            model.inclusiveCost.set(node.id, inclusiveByComponent[comp]);
+            model.componentOf.set(node.id, comp);
+            model.cycleSize.set(node.id, componentSize[comp]);
+            model.externalInbound.set(node.id, externalInbound[i]);
+            model.outEdges.set(node.id, outEdges[i].map((edge) => ({ fromId: node.id, toId: nodes[edge.to].id, count: edge.count })));
+            model.inEdges.set(node.id, inEdges[i].map((edge) => ({ fromId: nodes[edge.from].id, toId: node.id, count: edge.count })));
+        }
+        return model;
+    }
+    /**
+     * Tarjan's strongly-connected components over the index-based successor lists,
+     * iterative so a deep call chain cannot overflow the stack. Components are
+     * numbered in the order they are finalized, which is reverse-topological: every
+     * cross-component edge runs from a higher-numbered component to a lower one.
+     */
+    static stronglyConnectedComponents(successors) {
+        const count = successors.length;
+        const index = new Array(count).fill(-1);
+        const lowlink = new Array(count).fill(0);
+        const onStack = new Array(count).fill(false);
+        const componentOf = new Array(count).fill(-1);
+        const sccStack = [];
+        const workNode = [];
+        const workNext = [];
+        let counter = 0;
+        let componentCount = 0;
+        for (let start = 0; start < count; start += 1) {
+            if (index[start] !== -1) {
+                continue;
+            }
+            workNode.push(start);
+            workNext.push(0);
+            index[start] = counter;
+            lowlink[start] = counter;
+            counter += 1;
+            sccStack.push(start);
+            onStack[start] = true;
+            while (workNode.length > 0) {
+                const node = workNode[workNode.length - 1];
+                const position = workNext[workNext.length - 1];
+                const succ = successors[node];
+                if (position < succ.length) {
+                    workNext[workNext.length - 1] = position + 1;
+                    const next = succ[position];
+                    if (index[next] === -1) {
+                        index[next] = counter;
+                        lowlink[next] = counter;
+                        counter += 1;
+                        sccStack.push(next);
+                        onStack[next] = true;
+                        workNode.push(next);
+                        workNext.push(0);
+                    }
+                    else if (onStack[next] === true && index[next] < lowlink[node]) {
+                        lowlink[node] = index[next];
+                    }
+                    continue;
+                }
+                if (lowlink[node] === index[node]) {
+                    let member = -1;
+                    do {
+                        const popped = sccStack.pop();
+                        member = popped === undefined ? node : popped;
+                        onStack[member] = false;
+                        componentOf[member] = componentCount;
+                    } while (member !== node);
+                    componentCount += 1;
+                }
+                workNode.pop();
+                workNext.pop();
+                if (workNode.length > 0) {
+                    const parent = workNode[workNode.length - 1];
+                    if (lowlink[node] < lowlink[parent]) {
+                        lowlink[parent] = lowlink[node];
+                    }
+                }
+            }
+        }
+        return { componentOf, componentCount };
+    }
+    static toCostRef(node, model) {
+        const selfCost = model.selfCost.get(node.id) ?? 0;
+        const inclusiveCost = model.inclusiveCost.get(node.id) ?? 0;
+        const cycleSize = model.cycleSize.get(node.id) ?? 1;
+        return {
+            ...GraphQuery.symbolOf(node),
+            selfCost,
+            inclusiveCost,
+            shareOfTotal: model.totalSelf > 0 ? inclusiveCost / model.totalSelf : 0,
+            cyclic: cycleSize > 1,
+            cycleSize,
+        };
+    }
+    static symbolOf(node) {
+        return {
+            id: node.id,
+            kind: node.kind,
+            name: node.name,
+            filePath: node.filePath,
+            startLine: node.startLine,
+            metadata: node.metadata,
+        };
+    }
+    /**
+     * The fraction of profiled cost (in `metric`) the join attributed to graph
+     * nodes, from the manifest: matched ÷ total. Null when there is no manifest or
+     * the profile measured nothing in that metric.
+     */
+    static coverageFor(manifest, metric) {
+        if (manifest === null) {
+            return null;
+        }
+        if (metric === 'samples') {
+            return manifest.totalSamples > 0 ? manifest.matchedSamples / manifest.totalSamples : null;
+        }
+        return manifest.totalSelfMicros > 0 ? manifest.matchedSelfMicros / manifest.totalSelfMicros : null;
+    }
+    static toHotspot(node, score, metric) {
+        return {
+            id: node.id,
+            kind: node.kind,
+            name: node.name,
+            filePath: node.filePath,
+            startLine: node.startLine,
+            metadata: node.metadata,
+            score,
+            metric,
+        };
+    }
+    static isRuntimeMetric(metric) {
+        return metric === 'self-time' || metric === 'samples';
+    }
+    /** Reads a numeric metric out of `metadata.runtime`, defaulting to 0 when absent or non-numeric. */
+    static runtimeValue(metadata, key) {
+        const runtime = metadata.runtime;
+        if (typeof runtime !== 'object' || runtime === null) {
+            return 0;
+        }
+        const value = runtime[key];
+        return typeof value === 'number' ? value : 0;
+    }
+    static hasRuntime(metadata) {
+        const runtime = metadata.runtime;
+        return typeof runtime === 'object' && runtime !== null;
+    }
+    /** Decodes an edge's call-site `count`, defaulting to 1 (the minimum the builder records). */
+    static callCount(value) {
+        const metadata = GraphQuery.parseMetadata(value);
+        const count = metadata.count;
+        return typeof count === 'number' && count > 0 ? count : 1;
+    }
+    /** Decodes a runtime call edge's `samples` weight, defaulting to 1 when absent. */
+    static edgeSamples(value) {
+        const samples = GraphQuery.parseMetadata(value).samples;
+        return typeof samples === 'number' && samples >= 0 ? samples : 1;
+    }
+    static clampLimit(limit) {
+        if (limit === undefined || Number.isFinite(limit) === false) {
+            return 20;
+        }
+        const floored = Math.floor(limit);
+        if (floored < 1) {
+            return 20;
+        }
+        return floored > 1000 ? 1000 : floored;
+    }
     static toRefs(rows) {
         return rows.map((row) => GraphQuery.toRef(row));
     }
@@ -74,10 +623,35 @@ export class GraphQuery {
             name: String(row.name),
             filePath: String(row.filePath),
             startLine: Number(row.startLine),
+            metadata: GraphQuery.parseMetadata(row.metadata),
         };
     }
     static toNeighbor(row, direction) {
-        return { ...GraphQuery.toRef(row), edgeKind: String(row.edgeKind), direction };
+        return {
+            ...GraphQuery.toRef(row),
+            edgeKind: String(row.edgeKind),
+            edgeMetadata: GraphQuery.parseMetadata(row.edgeMetadata),
+            direction,
+        };
+    }
+    /**
+     * Decodes the JSON `metadata` column back into a record. A missing, empty, or
+     * malformed value decodes to an empty object so callers always receive a record.
+     */
+    static parseMetadata(value) {
+        if (typeof value !== 'string' || value.length === 0) {
+            return {};
+        }
+        try {
+            const parsed = JSON.parse(value);
+            if (typeof parsed === 'object' && parsed !== null) {
+                return parsed;
+            }
+            return {};
+        }
+        catch {
+            return {};
+        }
     }
     static clampDepth(depth) {
         if (Number.isFinite(depth) === false) {
@@ -87,7 +661,7 @@ export class GraphQuery {
         if (floored < 1) {
             return 1;
         }
-        return floored > 50 ? 50 : floored;
+        return floored > KUZU_MAX_REL_BOUND ? KUZU_MAX_REL_BOUND : floored;
     }
 }
 //# sourceMappingURL=graph_query.js.map