Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

Reuse PageRank topology across scopes (#203)

Buseong Kim03d83e6beb0b
diff --git a/node_modules b/node_modules
new file mode 120000
index 00000000..9cf9293f
--- /dev/null
+++ b/node_modules
@@ -0,0 +1 @@
+/Users/shrishdwivedi/Documents/Context graphs/context-graph-engine/node_modules
\ No newline at end of file
diff --git a/src/ask/ask.ts b/src/ask/ask.ts
index 9afff109..8fc16cca 100644
--- a/src/ask/ask.ts
+++ b/src/ask/ask.ts
@@ -41,7 +41,11 @@ import {
type RankedFile,
} from "./file-rank.js";
import { fileFirstRoundRobin, roundRobinQueues } from "./file-selection.js";
-import { personalizedPageRank } from "./graphrank.js";
+import {
+ personalizedPageRank,
+ personalizedPageRankPrepared,
+ preparePageRankPartitions,
+} from "./graphrank.js";
import { readSourceFile } from "../util/source.js";
import { counts, tokenize, type AskIndex, type AskIndexDoc } from "./index-file.js";
@@ -690,12 +694,20 @@ function lexical(
// can be ordered by score. Same scoring functions and blend as the
// single-scope path; the combination itself lives in fuse.ts. ──
const byScope = new Map<string, typeof symbolDocs>();
+ const scopeById = new Map<string, string>();
for (const d of symbolDocs) {
const s = scopeOf(d.n.path, scopes).prefix;
+ scopeById.set(d.n.id, s);
const list = byScope.get(s);
if (list) list.push(d);
else byScope.set(s, [d]);
}
+ // Lazily build every scope's PageRank topology in one node/edge pass. The
+ // old nodeFilter path rebuilt the full repo adjacency once per matching
+ // scope; on large multi-project repos that turned one query into hundreds
+ // of full graph scans before the participation gate could run. Waiting for
+ // the first walk keeps no-match and graphRank:false queries edge-scan free.
+ let pageRankByScope: ReturnType<typeof preparePageRankPartitions> | undefined;
let collapsedComponents: ScopeRankCandidate[] = [];
let collapsedComponentById: Map<string, ScopeRankCandidate> | undefined;
let collapsedFileByRepresentative: Map<string, RankedFile> | undefined;
@@ -740,15 +752,14 @@ function lexical(
for (const t of q.keys()) if (hasTerm(name, t) || hasTerm(path, t)) return true;
return false;
}),
- walk: (s, seeds) =>
- graphRank
- ? personalizedPageRank(graph!, seeds, {
- nodeFilter: (id) => {
- const path = byId.get(id)?.path ?? "";
- return scopeOf(path, scopes).prefix === s && (!inPrefix || pathUnderPrefix(path, inPrefix));
- },
- })
- : new Map<string, number>(),
+ walk: (s, seeds) => {
+ if (!graphRank) return new Map<string, number>();
+ pageRankByScope ??= preparePageRankPartitions(graph!, (id) => scopeById.get(id));
+ const topology = pageRankByScope?.get(s);
+ return topology
+ ? personalizedPageRankPrepared(topology, seeds)
+ : new Map<string, number>();
+ },
rankFactor: (_s, id) => testFactor(byId.get(id)?.path ?? ""),
collapseCandidates: fileComplement
? (candidates) => {
diff --git a/src/ask/graphrank.ts b/src/ask/graphrank.ts
index 6abcd608..3e850fe0 100644
--- a/src/ask/graphrank.ts
+++ b/src/ask/graphrank.ts
@@ -31,6 +31,84 @@ export interface PageRankOptions {
nodeFilter?: (id: string) => boolean;
}
+/** Immutable graph topology consumed by the PageRank iteration. Preparing it
+ * separately lets a multi-scope query partition one large graph once, instead
+ * of rescanning every node and edge for every scope. */
+export interface PageRankTopology {
+ ids: ReadonlySet<string>;
+ adjacency: ReadonlyMap<string, readonly string[]>;
+}
+
+export type PageRankRunOptions = Pick<PageRankOptions, "alpha" | "iters">;
+
+interface MutablePageRankTopology {
+ ids: Set<string>;
+ adjacency: Map<string, string[]>;
+}
+
+const emptyTopology = (): PageRankTopology => ({
+ ids: new Set<string>(),
+ adjacency: new Map<string, readonly string[]>(),
+});
+
+const link = (adjacency: Map<string, string[]>, source: string, target: string): void => {
+ const neighbours = adjacency.get(source);
+ if (neighbours) neighbours.push(target);
+ else adjacency.set(source, [target]);
+};
+
+/** Build independent PageRank topologies in one node pass and one edge pass.
+ * Edges crossing partitions are excluded, exactly like applying a nodeFilter
+ * for each partition independently. Returning `undefined` omits a node. */
+export function preparePageRankPartitions(
+ graph: GraphV1,
+ partitionOfId: (id: string) => string | undefined,
+): Map<string, PageRankTopology> {
+ const partitionById = new Map<string, string>();
+ const mutable = new Map<string, MutablePageRankTopology>();
+
+ for (const node of graph.nodes) {
+ const partition = partitionOfId(node.id);
+ if (partition === undefined) continue;
+ partitionById.set(node.id, partition);
+ const topology = mutable.get(partition);
+ if (topology) topology.ids.add(node.id);
+ else mutable.set(partition, { ids: new Set([node.id]), adjacency: new Map() });
+ }
+
+ for (const edge of graph.edges) {
+ if (!WALK_RELATIONS.has(edge.relation)) continue;
+ const partition = partitionById.get(edge.source);
+ if (partition === undefined || partitionById.get(edge.target) !== partition) continue;
+ const topology = mutable.get(partition)!;
+ link(topology.adjacency, edge.source, edge.target);
+ link(topology.adjacency, edge.target, edge.source);
+ }
+
+ return new Map(mutable);
+}
+
+/** Prepare one optionally filtered topology. Kept public for callers/tests that
+ * reuse the same graph across multiple seed sets. */
+export function preparePageRankTopology(
+ graph: GraphV1,
+ nodeFilter?: (id: string) => boolean,
+): PageRankTopology {
+ const ids = new Set(
+ graph.nodes.map((node) => node.id).filter((id) => !nodeFilter || nodeFilter(id)),
+ );
+ if (ids.size === 0) return emptyTopology();
+
+ const adjacency = new Map<string, string[]>();
+ for (const edge of graph.edges) {
+ if (!WALK_RELATIONS.has(edge.relation)) continue;
+ if (!ids.has(edge.source) || !ids.has(edge.target)) continue;
+ link(adjacency, edge.source, edge.target);
+ link(adjacency, edge.target, edge.source);
+ }
+ return { ids, adjacency };
+}
+
/**
* Personalized PageRank over the wiring graph.
*
@@ -47,28 +125,24 @@ export function personalizedPageRank(
seeds: Map<string, number>,
opts: PageRankOptions = {},
): Map<string, number> {
- const alpha = opts.alpha ?? 0.25;
- const iters = opts.iters ?? 25;
-
- // Real node ids, restricted to the subgraph when a filter is given. Every
- // downstream `ids.has(...)` check (edge endpoints, seeds) then naturally
- // stays within the filtered subgraph, so no other site needs to know about
- // `nodeFilter` — the walk simply never sees the excluded nodes or edges.
- const ids = new Set(
- graph.nodes.map((n) => n.id).filter((id) => !opts.nodeFilter || opts.nodeFilter(id)),
+ return personalizedPageRankPrepared(
+ preparePageRankTopology(graph, opts.nodeFilter),
+ seeds,
+ opts,
);
+}
- // Undirected adjacency over walk relations, endpoints restricted to real nodes.
- const adj = new Map<string, string[]>();
- const link = (a: string, b: string) => {
- (adj.get(a) ?? adj.set(a, []).get(a)!).push(b);
- };
- for (const e of graph.edges) {
- if (!WALK_RELATIONS.has(e.relation)) continue;
- if (!ids.has(e.source) || !ids.has(e.target)) continue;
- link(e.source, e.target);
- link(e.target, e.source);
- }
+/** Run PageRank on an already prepared topology. This is numerically identical
+ * to {@link personalizedPageRank}; it only removes repeated topology scans. */
+export function personalizedPageRankPrepared(
+ topology: PageRankTopology,
+ seeds: Map<string, number>,
+ opts: PageRankRunOptions = {},
+): Map<string, number> {
+ const alpha = opts.alpha ?? 0.25;
+ const iters = opts.iters ?? 25;
+ const ids = topology.ids;
+ const adjacency = topology.adjacency;
// Restart distribution: seed weights, restricted to real nodes, normalized.
let seedTotal = 0;
@@ -89,7 +163,7 @@ export function personalizedPageRank(
// O(nodes + seeds) instead of O(dangling × seeds).
let dangling = 0;
for (const [id, mass] of rank) {
- const nbrs = adj.get(id);
+ const nbrs = adjacency.get(id);
if (!nbrs || nbrs.length === 0) {
dangling += mass;
continue;
diff --git a/test/graphrank.test.ts b/test/graphrank.test.ts
index 1555ac4e..d17de253 100644
--- a/test/graphrank.test.ts
+++ b/test/graphrank.test.ts
@@ -15,7 +15,11 @@ import { join } from "node:path";
import { tmpdir } from "node:os";
import { buildGraph } from "../src/graph/build.js";
import { ask } from "../src/ask/ask.js";
-import { personalizedPageRank } from "../src/ask/graphrank.js";
+import {
+ personalizedPageRank,
+ personalizedPageRankPrepared,
+ preparePageRankPartitions,
+} from "../src/ask/graphrank.js";
import type { GraphV1, NodeV1, EdgeV1, Relation } from "../src/graph/types.js";
// ── Unit: personalizedPageRank ───────────────────────────────────────────────
@@ -175,6 +179,71 @@ test("PageRank: seeds outside the filter are ignored without error", () => {
});
});
+test("PageRank: prepared partitions exactly match independent nodeFilter walks", () => {
+ const g = graphOf(
+ ["a.hub", "a.left", "a.right", "b.hub", "b.left", "outside"],
+ [
+ edge("a.hub", "a.left"),
+ edge("a.hub", "a.left"), // Duplicate multiplicity/order must survive preparation.
+ edge("a.hub", "a.right"),
+ edge("b.hub", "b.left"),
+ edge("a.right", "b.left"), // Cross-partition: excluded from both walks.
+ edge("a.hub", "missing", "imports"),
+ ],
+ );
+ const partitionOf = (id: string) => id.startsWith("a.") ? "a" : id.startsWith("b.") ? "b" : undefined;
+ const prepared = preparePageRankPartitions(g, partitionOf);
+
+ for (const scope of ["a", "b"]) {
+ const seeds = new Map([
+ [`${scope}.hub`, 2],
+ [`${scope}.left`, 1],
+ [scope === "a" ? "b.hub" : "a.hub", 50], // Out-of-scope seed is ignored.
+ ]);
+ const filtered = personalizedPageRank(g, seeds, {
+ nodeFilter: (id) => partitionOf(id) === scope,
+ });
+ const reused = personalizedPageRankPrepared(prepared.get(scope)!, seeds);
+ assert.deepEqual(
+ [...reused],
+ [...filtered],
+ `${scope}: prepared topology must preserve entry order and exact floating-point scores`,
+ );
+ }
+});
+
+test("PageRank: preparing many partitions reads graph topology only once", () => {
+ const backing = graphOf(
+ ["a.hub", "a.leaf", "b.hub", "b.leaf"],
+ [edge("a.hub", "a.leaf"), edge("b.hub", "b.leaf")],
+ );
+ let nodeReads = 0;
+ let edgeReads = 0;
+ let partitionCalls = 0;
+ const counted: GraphV1 = {
+ meta: backing.meta,
+ get nodes() {
+ nodeReads += 1;
+ return backing.nodes;
+ },
+ get edges() {
+ edgeReads += 1;
+ return backing.edges;
+ },
+ };
+
+ const prepared = preparePageRankPartitions(counted, (id) => {
+ partitionCalls += 1;
+ return id[0];
+ });
+ personalizedPageRankPrepared(prepared.get("a")!, new Map([["a.hub", 1]]));
+ personalizedPageRankPrepared(prepared.get("b")!, new Map([["b.hub", 1]]));
+
+ assert.equal(nodeReads, 1, "all partitions share one node pass");
+ assert.equal(edgeReads, 1, "all partitions share one edge pass");
+ assert.equal(partitionCalls, backing.nodes.length, "each node is assigned once");
+});
+
// ── Integration: ask() with and without graph-rank ──────────────────────────
/** A fixture with a same-word collision: `fooHandler` (wired to two helpers)