Skip to content

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

feat(ask): graphrank accepts a node filter for subgraph walks

Shrish Dwivedi215ac21e7565
diff --git a/src/ask/graphrank.ts b/src/ask/graphrank.ts
index e984fb88..6abcd608 100644
--- a/src/ask/graphrank.ts
+++ b/src/ask/graphrank.ts
@@ -23,6 +23,12 @@ export interface PageRankOptions {
alpha?: number;
/** Power-iteration count. 25 is plenty to converge on graphs this size. */
iters?: number;
+ /** Restrict the walk to a subgraph: when present, an edge counts only when
+ * BOTH endpoints pass, and only passing ids can hold rank mass or seed
+ * weight. Seeds outside the filter are silently ignored (same as a seed
+ * naming a non-existent node). Omit for the full-graph walk (unchanged
+ * behavior). */
+ nodeFilter?: (id: string) => boolean;
}
/**
@@ -44,7 +50,13 @@ export function personalizedPageRank(
const alpha = opts.alpha ?? 0.25;
const iters = opts.iters ?? 25;
- const ids = new Set(graph.nodes.map((n) => n.id));
+ // 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)),
+ );
// Undirected adjacency over walk relations, endpoints restricted to real nodes.
const adj = new Map<string, string[]>();
diff --git a/test/graphrank.test.ts b/test/graphrank.test.ts
index a2f9fdd5..1555ac4e 100644
--- a/test/graphrank.test.ts
+++ b/test/graphrank.test.ts
@@ -121,6 +121,60 @@ test("PageRank: broad seeds on a large mostly-dangling graph complete fast", ()
assert.ok(ms < 3000, `took ${ms}ms — dangling redistribution must not be O(dangling × seeds)`);
});
+test("PageRank: nodeFilter restricted to component A matches running on component A alone", () => {
+ // Two disjoint components: A (hub/a/b/c) and B (x/y/z). A filter that keeps
+ // only component A must produce ranks identical to a graph containing only
+ // component A — the other component's nodes and edges must not leak in.
+ const componentAIds = ["hub", "a", "b", "c"];
+ const edgesA: EdgeV1[] = [edge("hub", "a"), edge("hub", "b"), edge("hub", "c")];
+ const edgesB: EdgeV1[] = [edge("x", "y"), edge("y", "z")];
+ const full = graphOf([...componentAIds, "x", "y", "z"], [...edgesA, ...edgesB]);
+ const onlyA = graphOf(componentAIds, edgesA);
+
+ const seeds = new Map([["hub", 1], ["a", 0.5]]);
+ const filtered = personalizedPageRank(full, seeds, {
+ nodeFilter: (id) => componentAIds.includes(id),
+ });
+ const reference = personalizedPageRank(onlyA, seeds);
+
+ assert.equal(filtered.size, reference.size);
+ for (const [id, v] of reference) {
+ assert.ok(filtered.has(id), `filtered result missing ${id}`);
+ assert.equal(filtered.get(id), v, `mismatched rank for ${id}`);
+ }
+ assert.equal(filtered.has("x"), false, "filtered-out component must not appear");
+});
+
+test("PageRank: no filter (opts omitted) reproduces exact pre-existing output", () => {
+ // Snapshot of the dangling-mass fixture's known values (see the dedicated
+ // dangling-mass test above) — proves omitting nodeFilter is byte-stable.
+ const g = graphOf(["a", "b", "c", "d", "e"], [edge("a", "b"), edge("b", "c")]);
+ const seeds = new Map([["a", 2], ["d", 1]]);
+ const out = personalizedPageRank(g, seeds);
+ const EXPECTED_A = 0.9577162737326514;
+ const EXPECTED_B = 1;
+ const EXPECTED_C = 0.37462976423958994;
+ const EXPECTED_D = 0.29154325474653076;
+ assert.ok(Math.abs((out.get("a") ?? 0) - EXPECTED_A) < 1e-9, `a: ${out.get("a")}`);
+ assert.equal(out.get("b"), EXPECTED_B);
+ assert.ok(Math.abs((out.get("c") ?? 0) - EXPECTED_C) < 1e-9, `c: ${out.get("c")}`);
+ assert.ok(Math.abs((out.get("d") ?? 0) - EXPECTED_D) < 1e-9, `d: ${out.get("d")}`);
+ assert.equal(out.get("e"), undefined);
+});
+
+test("PageRank: seeds outside the filter are ignored without error", () => {
+ const g = graphOf(
+ ["hub", "a", "b", "outside"],
+ [edge("hub", "a"), edge("hub", "b")],
+ );
+ const seeds = new Map([["hub", 1], ["outside", 5]]);
+ assert.doesNotThrow(() => {
+ const pr = personalizedPageRank(g, seeds, { nodeFilter: (id) => id !== "outside" });
+ assert.equal(pr.has("outside"), false, "filtered-out seed never appears in output");
+ assert.ok((pr.get("hub") ?? 0) > 0, "in-filter seed still ranked");
+ });
+});
+
// ── Integration: ask() with and without graph-rank ──────────────────────────
/** A fixture with a same-word collision: `fooHandler` (wired to two helpers)