Skip to content

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

feat(ask): graph-rank + IDF + body indexing, and fix silent 32KB parse drop

Shrish Dwivedicdec18e56065
diff --git a/package-lock.json b/package-lock.json
index 86ebc4ce..ebcd845c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,13 @@
{
"name": "@nanonets/graft",
- "version": "0.3.2",
+ "version": "0.4.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@nanonets/graft",
- "version": "0.3.2",
+ "version": "0.4.0",
+ "hasInstallScript": true,
"license": "MIT",
"dependencies": {
"commander": "^15.0.0",
diff --git a/package.json b/package.json
index 14d05f79..040e1d09 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@nanonets/graft",
- "version": "0.3.2",
+ "version": "0.4.0",
"description": "Build a repo's context graph as a folder of linked markdown files that live in the repo and stay in sync with the code through git.",
"keywords": [
"ai",
diff --git a/src/ask/ask.ts b/src/ask/ask.ts
index f5cbf4e8..b9f2abd5 100644
--- a/src/ask/ask.ts
+++ b/src/ask/ask.ts
@@ -19,6 +19,7 @@ import matter from "gray-matter";
import { contextDirFor } from "../context/node-file.js";
import { readGraph, wiringPath } from "../graph/write.js";
import type { EdgeV1, GraphV1, NodeV1, Relation } from "../graph/types.js";
+import { personalizedPageRank } from "./graphrank.js";
export interface AskHit {
kind: "concept" | "symbol" | "caller" | "callee";
@@ -116,12 +117,59 @@ function loadCorpus(outDir: string): Corpus {
return { concepts, graph: readGraph(wiringPath(outDir)) };
}
-/** Score a document's token counts against the query counts (name field pre-weighted by caller). */
-function score(query: Map<string, number>, doc: Map<string, number>): number {
+/** Score a document's token counts against the query counts (name field
+ * pre-weighted by caller). Each shared term is weighted by its inverse document
+ * frequency (`idf`), so a word that appears in many nodes — "overlay" across a
+ * whole widget subsystem, or a repeated word in a pasted issue body — counts for
+ * far less than a rare, discriminating identifier ("scrolling"). Without idf,
+ * pure term-frequency lets an incidental common word dominate the ranking; this
+ * is the lexical half of the keyword-collision fix (graph-rank is the other). */
+function score(
+ query: Map<string, number>,
+ doc: Map<string, number>,
+ idf: Map<string, number>,
+): number {
let s = 0;
for (const [t, qn] of query) {
const dn = doc.get(t);
- if (dn) s += qn * dn;
+ if (dn) s += qn * dn * (idf.get(t) ?? 1);
+ }
+ return s;
+}
+
+/** Inverse document frequency over the scored corpus. `df` counts how many
+ * documents (concept nodes + symbol nodes) contain each token; N is the corpus
+ * size. `log(1 + N/(1+df))` is the smoothed standard form: monotonically
+ * decreasing in df, always positive, ~0 extra weight for a token in every doc. */
+function computeIdf(docBags: Array<Set<string>>): Map<string, number> {
+ const n = docBags.length;
+ const df = new Map<string, number>();
+ for (const bag of docBags)
+ for (const t of bag) df.set(t, (df.get(t) ?? 0) + 1);
+ const idf = new Map<string, number>();
+ for (const [t, d] of df) idf.set(t, Math.log(1 + n / (1 + d)));
+ return idf;
+}
+
+/** BM25 term score for a document field, used for the (potentially large) body
+ * field. Unlike raw term-frequency, BM25 saturates repeated occurrences (`k1`)
+ * and normalizes by document length (`b`, against the corpus-average length
+ * `avgdl`), so a big definition — a sprawling test class — can't outrank a
+ * tight, on-point function merely by containing more words. Standard params. */
+function bm25(
+ query: Map<string, number>,
+ doc: Map<string, number>,
+ idf: Map<string, number>,
+ dl: number,
+ avgdl: number,
+): number {
+ const k1 = 1.2;
+ const b = 0.75;
+ const norm = k1 * (1 - b + (b * dl) / (avgdl || 1));
+ let s = 0;
+ for (const t of query.keys()) {
+ const tf = doc.get(t);
+ if (tf) s += (idf.get(t) ?? 1) * ((tf * (k1 + 1)) / (tf + norm));
}
return s;
}
@@ -199,16 +247,60 @@ function structural(query: string, graph: GraphV1, limit: number): AskResult | n
// ── Lexical rank ─────────────────────────────────────────────────────────────
-function lexical(query: string, corpus: Corpus, limit: number): AskResult {
- const q = counts(tokenize(query));
- const scored: AskHit[] = [];
-
- for (const c of corpus.concepts) {
- const nameScore = score(q, counts(tokenize(c.name))) * 3;
- const bodyScore = score(q, counts(tokenize(c.text)));
- const total = nameScore + bodyScore;
+/** How much a node's graph-centrality (0..1) can lift its blended score. A
+ * lexically-perfect node scores 1.0 on the lexical axis; a graph weight of 0.5
+ * lets connectivity reorder near-ties and separate a connected hit from an
+ * isolated same-word collision, without letting structure override a clear
+ * lexical winner. */
+const GRAPH_WEIGHT = 0.5;
+
+/** A node the query never word-matched is pulled into the results only if the
+ * walk gives it at least this share of the top node's mass — i.e. it is
+ * genuinely central to the matched cluster, not incidentally reachable. This is
+ * what surfaces the config/helper a task depends on but didn't name. */
+const RESCUE_FLOOR = 0.15;
+
+function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolean): AskResult {
+ // Binary query terms: a word repeated in a pasted issue body counts once, so a
+ // ranty description can't linearly amplify an incidental word.
+ const q = new Map([...counts(tokenize(query)).keys()].map((t) => [t, 1]));
+ const graph = corpus.graph;
+
+ // ── Pass 1: tokenize every scored field once, and collect per-document token
+ // bags so IDF can down-weight words that occur across the whole corpus. ──
+ const conceptDocs = corpus.concepts.map((c) => ({
+ c,
+ name: counts(tokenize(c.name)),
+ body: counts(tokenize(c.text)),
+ }));
+ // Symbols AND file nodes are scored: a symbol's body_text is its definition;
+ // a file's body_text is the module-level residual (imports/constants not in
+ // any symbol). Including files closes the recall gap where a gold file's only
+ // query-relevant text lives outside every function/class.
+ const symbolDocs = (graph?.nodes ?? []).map((n) => ({
+ n,
+ name: counts(tokenize(n.name)),
+ path: counts(tokenize(n.path)),
+ // The body (indexed at build) joins the signature + summary as the low-weight
+ // body field, so a term that appears only in the code — not the name/signature
+ // — still makes the node findable. IDF (from these same bags) keeps a word
+ // common across many bodies from dominating.
+ body: counts(tokenize(`${n.signature ?? ""} ${n.summary ?? ""} ${n.body_text ?? ""}`)),
+ }));
+ const docBags: Array<Set<string>> = [];
+ for (const d of conceptDocs) docBags.push(new Set([...d.name.keys(), ...d.body.keys()]));
+ for (const d of symbolDocs)
+ docBags.push(new Set([...d.name.keys(), ...d.path.keys(), ...d.body.keys()]));
+ const idf = computeIdf(docBags);
+
+ // ── Concepts (prose nodes; not in the wiring graph) ──
+ const conceptHits: AskHit[] = [];
+ let maxConcept = 0;
+ for (const { c, name, body } of conceptDocs) {
+ const total = score(q, name, idf) * 3 + score(q, body, idf);
if (total > 0) {
- scored.push({
+ maxConcept = Math.max(maxConcept, total);
+ conceptHits.push({
kind: "concept",
title: c.name || c.slug,
pointer: c.sources.join(", ") || c.slug,
@@ -219,23 +311,65 @@ function lexical(query: string, corpus: Corpus, limit: number): AskResult {
}
}
- for (const n of corpus.graph?.nodes ?? []) {
- if (n.kind === "file") continue;
- const nameScore = score(q, counts(tokenize(n.name))) * 3;
- const pathScore = score(q, counts(tokenize(n.path))) * 2;
- const bodyScore = score(q, counts(tokenize(`${n.signature ?? ""} ${n.summary ?? ""}`)));
- const total = nameScore + pathScore + bodyScore;
+ // ── Symbols (wiring graph): lexical score per node, keyed by id ──
+ const byId = new Map((graph?.nodes ?? []).map((n) => [n.id, n]));
+ const bodyLen = (m: Map<string, number>) => {
+ let s = 0;
+ for (const v of m.values()) s += v;
+ return s;
+ };
+ const avgBodyLen = symbolDocs.length
+ ? symbolDocs.reduce((a, d) => a + bodyLen(d.body), 0) / symbolDocs.length
+ : 0;
+ const lex = new Map<string, number>(); // node id → lexical score (>0 only)
+ let maxLex = 0;
+ for (const { n, name, path, body } of symbolDocs) {
+ // Name and path are short identifiers → plain idf-weighted overlap; the body
+ // is length-normalized via BM25 so long definitions don't win on bulk.
+ const total =
+ score(q, name, idf) * 3 +
+ score(q, path, idf) * 2 +
+ bm25(q, body, idf, bodyLen(body), avgBodyLen);
if (total > 0) {
- scored.push({
- kind: "symbol",
- title: `${n.name} · ${n.kind}`,
- pointer: `${n.path}:${n.span}`,
- snippet: n.summary?.split("\n")[0].trim() ?? n.signature ?? "",
- score: total,
- });
+ lex.set(n.id, total);
+ maxLex = Math.max(maxLex, total);
}
}
+ // ── Graph-rank: let connectivity to the matched set reorder and rescue ──
+ const pr = graphRank && graph && lex.size > 0
+ ? personalizedPageRank(graph, lex)
+ : new Map<string, number>();
+
+ // Candidate symbols = everything the query word-matched, plus nodes the walk
+ // found strongly central even without a word match (RESCUE_FLOOR).
+ const candidates = new Set<string>(lex.keys());
+ for (const [id, p] of pr) if (p >= RESCUE_FLOOR) candidates.add(id);
+
+ const symbolHits: AskHit[] = [];
+ for (const id of candidates) {
+ const n = byId.get(id);
+ if (!n) continue;
+ const lexN = maxLex > 0 ? (lex.get(id) ?? 0) / maxLex : 0;
+ const blended = lexN + GRAPH_WEIGHT * (pr.get(id) ?? 0);
+ if (blended <= 0) continue;
+ symbolHits.push({
+ kind: "symbol",
+ title: `${n.name} · ${n.kind}`,
+ // A file node points at the whole file (locator, no span) so `--source`
+ // never inlines an entire file; symbol nodes keep their exact span.
+ pointer: n.kind === "file" ? n.path : `${n.path}:${n.span}`,
+ snippet: n.summary?.split("\n")[0].trim() ?? n.signature ?? "",
+ score: blended,
+ });
+ }
+
+ // Concepts and symbols live on comparable 0..~1.5 scales so they merge fairly:
+ // concept scores are normalized to their own max, symbol scores are the
+ // lexical-normalized + graph-weighted blend.
+ for (const h of conceptHits) h.score = maxConcept > 0 ? h.score / maxConcept : 0;
+
+ const scored = [...conceptHits, ...symbolHits];
scored.sort((a, b) => b.score - a.score || a.title.localeCompare(b.title));
return {
query,
@@ -251,6 +385,10 @@ export interface AskOptions {
/** Inline the source at each `path:Lx-Ly` hit, sliced from `dir`. Turns the
* pack from a locator into a retriever so the agent needn't re-open the file. */
source?: boolean;
+ /** Re-rank lexical hits by graph connectivity (personalized PageRank over the
+ * wiring edges), demoting same-word collisions and rescuing strongly-connected
+ * neighbours the query didn't name. On by default; set false for pure lexical. */
+ graphRank?: boolean;
}
/** Parse a `path:Lx-Ly` pointer into its parts, or null if it isn't one
@@ -329,13 +467,14 @@ export function ask(dir: string, query: string, opts: AskOptions = {}): AskResul
const outDir = contextDirFor(root, opts.contextDir);
const limit = opts.limit ?? 8;
const corpus = loadCorpus(outDir);
+ const graphRank = opts.graphRank ?? true;
let result: AskResult;
if (corpus.graph) {
const s = structural(query, corpus.graph, limit);
- result = s ?? lexical(query, corpus, limit);
+ result = s ?? lexical(query, corpus, limit, graphRank);
} else {
- result = lexical(query, corpus, limit);
+ result = lexical(query, corpus, limit, graphRank);
}
if (opts.source) {
inlineSource(root, result.hits);
diff --git a/src/ask/graphrank.ts b/src/ask/graphrank.ts
new file mode 100644
index 00000000..9507b6ab
--- /dev/null
+++ b/src/ask/graphrank.ts
@@ -0,0 +1,109 @@
+/**
+ * Graph-rank re-ranking for `graft ask` — the fix for lexical keyword-collision.
+ *
+ * Pure term-overlap ranking treats every node independently, so a node that
+ * merely shares a word with the query (a window "overlay" widget) can outrank
+ * the node the query is actually about (a scroll-"overlay" config) purely on
+ * word count. The graph knows better: the right node is the one wired into the
+ * cluster of code the query touches.
+ *
+ * This module runs personalized PageRank (random-walk-with-restart) over the
+ * wiring graph, seeded by the lexical scores. Mass concentrates on nodes that
+ * are edge-connected to the matched set; a lexically-matched but structurally
+ * isolated node keeps only its own restart mass and sinks. "Lexical proposes,
+ * graph disposes." Deterministic, $0, no embeddings — a lexical-seed →
+ * graph-rank pipeline, the established alternative to vector search for code.
+ */
+import type { GraphV1, Relation } from "../graph/types.js";
+
+/**
+ * Edges that carry meaning-flow for the walk. `contains` is deliberately
+ * excluded: a file node contains every symbol defined in it, so walking it
+ * would make every same-file symbol a neighbour and let a file act as a hub
+ * that connects otherwise-unrelated code — the flooding a graph walk must avoid.
+ */
+const WALK_RELATIONS = new Set<Relation>([
+ "calls",
+ "references",
+ "imports",
+ "implements",
+ "extends",
+]);
+
+export interface PageRankOptions {
+ /** Restart probability — the mass that teleports back to the seed set each
+ * step. Higher keeps the walk closer to the seeds. 0.25 is the standard value. */
+ alpha?: number;
+ /** Power-iteration count. 25 is plenty to converge on graphs this size. */
+ iters?: number;
+}
+
+/**
+ * Personalized PageRank over the wiring graph.
+ *
+ * `seeds` maps node id → restart weight (a node's lexical score; only positive
+ * weights matter). The graph is treated as UNDIRECTED — for "understand this
+ * area" a callee is as relevant as a caller. Returns a score per node
+ * normalized so the top node is 1; nodes untouched by the walk are absent.
+ *
+ * Edges whose endpoints aren't both real nodes (e.g. an unresolved import
+ * module string) are ignored, so only genuine symbol-to-symbol wiring counts.
+ */
+export function personalizedPageRank(
+ graph: GraphV1,
+ seeds: Map<string, number>,
+ opts: PageRankOptions = {},
+): Map<string, number> {
+ const alpha = opts.alpha ?? 0.25;
+ const iters = opts.iters ?? 25;
+
+ const ids = new Set(graph.nodes.map((n) => n.id));
+
+ // 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);
+ }
+
+ // Restart distribution: seed weights, restricted to real nodes, normalized.
+ let seedTotal = 0;
+ for (const [id, w] of seeds) if (ids.has(id) && w > 0) seedTotal += w;
+ if (seedTotal <= 0) return new Map();
+ const restart = new Map<string, number>();
+ for (const [id, w] of seeds)
+ if (ids.has(id) && w > 0) restart.set(id, w / seedTotal);
+
+ // Power iteration from the restart distribution.
+ let rank = new Map(restart);
+ for (let i = 0; i < iters; i++) {
+ const next = new Map<string, number>();
+ // Teleport: every step, alpha of the mass returns to the seed set.
+ for (const [id, r] of restart) next.set(id, alpha * r);
+ for (const [id, mass] of rank) {
+ const nbrs = adj.get(id);
+ if (!nbrs || nbrs.length === 0) {
+ // Dangling node: return its mass to the seed set (conserves probability
+ // and keeps it personalized — mass never escapes to the whole graph).
+ for (const [sid, r] of restart)
+ next.set(sid, (next.get(sid) ?? 0) + (1 - alpha) * mass * r);
+ continue;
+ }
+ const share = ((1 - alpha) * mass) / nbrs.length;
+ for (const nb of nbrs) next.set(nb, (next.get(nb) ?? 0) + share);
+ }
+ rank = next;
+ }
+
+ let max = 0;
+ for (const v of rank.values()) if (v > max) max = v;
+ if (max <= 0) return new Map();
+ const out = new Map<string, number>();
+ for (const [id, v] of rank) out.set(id, v / max);
+ return out;
+}
diff --git a/src/graph/extract.ts b/src/graph/extract.ts
index ead49ba7..93632938 100644
--- a/src/graph/extract.ts
+++ b/src/graph/extract.ts
@@ -43,6 +43,45 @@ export interface ExtractResult {
rawEdges: RawEdge[];
}
+/** Max chars of normalized body stored per symbol for search. Large enough that
+ * essentially every real definition is stored whole — only a rare giant function
+ * is clipped — while bounding how much the committed graph can grow. */
+const MAX_BODY_CHARS = 5000;
+
+/** Cap for a file node's module-level residual (imports, constants, module
+ * docstring — everything not inside a symbol). Higher than the per-symbol cap
+ * because a data-heavy module (constant tables, big config dicts) is legitimate
+ * residual, and it's the recall play — but still bounded. */
+const MAX_FILE_BODY_CHARS = 16000;
+
+/** The searchable body of a definition: its source text, whitespace-collapsed
+ * so every identifier becomes a token, capped at `max`. Search-only — the agent
+ * still reads verbatim source via `ask --source`, which slices the file from
+ * disk, so nothing here reaches the agent's context. */
+function searchBody(text: string, max = MAX_BODY_CHARS): string {
+ const norm = text.replace(/\s+/g, " ").trim();
+ return norm.length > max ? norm.slice(0, max) : norm;
+}
+
+/** A file's module-level residual: the lines NOT covered by any symbol span.
+ * Symbol bodies are already indexed on their own nodes, so this captures only
+ * what they miss — top-of-file imports, module constants, module docstrings —
+ * making a file findable by a term that lives outside every function/class.
+ * `symbols` are the file's emitted nodes (with `Lx-Ly` spans); `source` is the
+ * whole file. Far leaner than storing full-file bodies (no symbol duplication). */
+function fileResidual(source: string, symbols: NodeV1[]): string {
+ const lines = source.split("\n");
+ const covered = new Uint8Array(lines.length + 2);
+ for (const s of symbols) {
+ const m = s.span.match(/^L(\d+)-L(\d+)$/);
+ if (!m) continue;
+ for (let r = Number(m[1]); r <= Number(m[2]) && r < covered.length; r++) covered[r] = 1;
+ }
+ const kept: string[] = [];
+ for (let i = 0; i < lines.length; i++) if (!covered[i + 1]) kept.push(lines[i]);
+ return searchBody(kept.join(" "), MAX_FILE_BODY_CHARS);
+}
+
const TS_KINDS: Record<string, Kind> = {
class_declaration: "class",
abstract_class_declaration: "class",
@@ -91,9 +130,19 @@ interface DefDescriptor {
hashNode: Parser.SyntaxNode; // node whose text forms body_hash / span
}
+/** tree-sitter's string `parse()` fails with "Invalid argument" on any input
+ * ≥ 32 KB, which silently drops large files — often the most important ones (a
+ * 2000-line command module, a core tab implementation). The callback form has
+ * no such limit as long as each returned chunk is under 32 KB, so we always feed
+ * the source in <32 KB slices. Code-unit indexing matches `String.slice`. */
+const PARSE_CHUNK = 16384;
+function parseSource(source: string): Parser.SyntaxNode {
+ return parser.parse((index: number) => source.slice(index, index + PARSE_CHUNK)).rootNode;
+}
+
export function extractFile(rel: string, source: string, lang: Language): ExtractResult {
parser.setLanguage(GRAMMARS[lang] as never);
- const root = parser.parse(source).rootNode;
+ const root = parseSource(source);
const nodes: NodeV1[] = [
{
@@ -124,6 +173,9 @@ export function extractFile(rel: string, source: string, lang: Language): Extrac
parentId: rel,
};
for (const child of root.namedChildren) walk(child, ctx, nodes, rawEdges);
+ // nodes[0] is the file node; the rest are its symbols. Index the module-level
+ // residual on the file node so a term outside every symbol still surfaces it.
+ nodes[0].body_text = fileResidual(source, nodes.slice(1));
return { nodes, rawEdges };
}
@@ -141,6 +193,7 @@ function walk(node: Parser.SyntaxNode, ctx: WalkCtx, out: NodeV1[], edges: RawEd
exported: ctx.lang === "python" ? !desc.name.startsWith("_") : tsExported(node),
origin: "ast",
body_hash: contentHash(desc.hashNode.text),
+ body_text: searchBody(desc.hashNode.text),
summary_state: "pending",
summary: null,
crux: null,
diff --git a/src/graph/types.ts b/src/graph/types.ts
index fd17bfb9..fdcd4a81 100644
--- a/src/graph/types.ts
+++ b/src/graph/types.ts
@@ -49,6 +49,11 @@ export interface NodeV1 {
body_hash: string; // sha256 of the definition text; the Tier-2 re-run trigger
chars?: number; // byte length of the WHOLE file (file nodes only); the baseline
// `ask` uses to estimate tokens saved vs reading the file whole
+ body_text?: string; // searchable whitespace-normalized definition body (Tier-1,
+ // symbol nodes only, capped). Ranks `ask` queries so a term in
+ // the code — not just the name/signature — is findable; never
+ // emitted to the agent (that reads verbatim source via `--source`).
+ // Absent on file nodes and on graphs built before this field.
// meaning (Tier-2, one LLM call)
summary_state: SummaryState;
diff --git a/test/ask.test.ts b/test/ask.test.ts
index 7795897d..88cc6c09 100644
--- a/test/ask.test.ts
+++ b/test/ask.test.ts
@@ -37,6 +37,68 @@ test("ask without source returns pointers but no inlined code", async () => {
}
});
+test("ask finds a symbol by a term that appears only in its body (body-indexing)", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "graft-ask-body-"));
+ try {
+ // "stripe" is nowhere in the name/signature — only inside the body.
+ writeFileSync(
+ join(dir, "pay.ts"),
+ `export function checkout(amount: number): string {\n` +
+ ` const token = createStripeCharge(amount);\n` +
+ ` return token;\n` +
+ `}\n`,
+ );
+ await buildGraph(dir);
+ const r = ask(dir, "stripe");
+ const hit = r.hits.find((h) => h.title.startsWith("checkout"));
+ assert.ok(hit, "checkout is findable via a term that only appears in its body");
+ assert.match(hit.pointer, /^pay\.ts:L\d+-L\d+$/);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("ask surfaces a file by a term only in its module-level code (file-body indexing)", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "graft-ask-file-"));
+ try {
+ // "telemetry" appears only in a module-level constant — inside no function
+ // or class — so only file-level residual indexing can make it findable.
+ writeFileSync(
+ join(dir, "settings.ts"),
+ `export const FEATURE_FLAG_TELEMETRY = false;\n\n` +
+ `export function init(): number {\n return 1;\n}\n`,
+ );
+ await buildGraph(dir);
+ const r = ask(dir, "telemetry");
+ const hit = r.hits.find((h) => h.pointer === "settings.ts");
+ assert.ok(hit, "the file surfaces via a term that lives only in module-level code");
+ assert.ok(hit.title.endsWith("· file"), "it is the file node, pointed at the whole file (no span)");
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("ask indexes a symbol past the 32KB tree-sitter boundary (chunked parse)", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "graft-ask-big-"));
+ try {
+ // Build a >32KB Python file with the distinctive symbol AFTER the 32KB mark,
+ // so it is only reachable if the whole file parsed (string parse caps at 32KB).
+ let body = "";
+ for (let i = 0; body.length < 40000; i++) body += `def filler_${i}():\n return ${i}\n\n`;
+ body += `def zzz_needle_marker():\n return "found"\n`;
+ assert.ok(body.length > 32768, "fixture must exceed the 32KB parse limit");
+ writeFileSync(join(dir, "big.py"), body);
+ await buildGraph(dir);
+ const r = ask(dir, "zzz_needle_marker");
+ assert.ok(
+ r.hits.find((h) => h.title.startsWith("zzz_needle_marker")),
+ "a symbol defined past the 32KB boundary is indexed and findable",
+ );
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
test("ask with source inlines the actual span from disk", async () => {
const dir = makeFixture();
try {
diff --git a/test/graphrank.test.ts b/test/graphrank.test.ts
new file mode 100644
index 00000000..d1c5d903
--- /dev/null
+++ b/test/graphrank.test.ts
@@ -0,0 +1,160 @@
+/**
+ * Tests for the graph-rank re-ranking stage of `graft ask`.
+ *
+ * The unit tests exercise {@link personalizedPageRank} directly on hand-built
+ * graphs; the integration tests drive the whole `ask` path on real fixtures
+ * built by {@link buildGraph}, proving the keyword-collision fix end-to-end:
+ * a lexically-matched but structurally isolated node is demoted below a
+ * lexically-equal node that is wired into the query's cluster, and strongly
+ * connected neighbours the query never named are rescued into the results.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+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 type { GraphV1, NodeV1, EdgeV1, Relation } from "../src/graph/types.js";
+
+// ── Unit: personalizedPageRank ───────────────────────────────────────────────
+
+function node(id: string): NodeV1 {
+ return {
+ id,
+ name: id,
+ kind: "function",
+ path: `${id}.ts`,
+ span: "L1-L1",
+ signature: null,
+ exported: true,
+ origin: "ast",
+ body_hash: id,
+ summary_state: "pending",
+ summary: null,
+ crux: null,
+ };
+}
+function edge(source: string, target: string, relation: Relation = "calls"): EdgeV1 {
+ return { source, target, relation, confidence: "extracted" };
+}
+function graphOf(nodes: string[], edges: EdgeV1[]): GraphV1 {
+ return {
+ meta: { version: 1, nodeCount: nodes.length, edgeCount: edges.length, languages: ["ts"] },
+ nodes: nodes.map(node),
+ edges,
+ };
+}
+
+test("PageRank: a seed wired to the cluster outranks an isolated seed", () => {
+ // hub calls a, b, c; lone is a disconnected seed with equal restart weight.
+ const g = graphOf(
+ ["hub", "a", "b", "c", "lone"],
+ [edge("hub", "a"), edge("hub", "b"), edge("hub", "c")],
+ );
+ const pr = personalizedPageRank(g, new Map([["hub", 1], ["lone", 1]]));
+ assert.ok((pr.get("hub") ?? 0) > (pr.get("lone") ?? 0), "connected seed beats isolated seed");
+ assert.equal([...pr.values()].some((v) => v === 1), true, "top node normalized to 1");
+});
+
+test("PageRank: neighbours of a seed accrue mass even with zero restart weight", () => {
+ const g = graphOf(["hub", "a", "b"], [edge("hub", "a"), edge("hub", "b")]);
+ const pr = personalizedPageRank(g, new Map([["hub", 1]]));
+ assert.ok((pr.get("a") ?? 0) > 0, "a neighbour of the only seed gets walk mass");
+ assert.ok((pr.get("b") ?? 0) > 0);
+});
+
+test("PageRank: empty or all-zero seeds yield an empty map", () => {
+ const g = graphOf(["a", "b"], [edge("a", "b")]);
+ assert.equal(personalizedPageRank(g, new Map()).size, 0);
+ assert.equal(personalizedPageRank(g, new Map([["a", 0]])).size, 0);
+});
+
+test("PageRank: edges to non-node targets (unresolved imports) are ignored", () => {
+ // "react" is an import module string, not a node id — must not crash or count.
+ const g = graphOf(["a"], [edge("a", "react", "imports")]);
+ const pr = personalizedPageRank(g, new Map([["a", 1]]));
+ assert.equal(pr.get("a"), 1, "sole seed with no real neighbours stays at 1");
+ assert.equal(pr.has("react"), false, "the module string never becomes a ranked node");
+});
+
+// ── Integration: ask() with and without graph-rank ──────────────────────────
+
+/** A fixture with a same-word collision: `fooHandler` (wired to two helpers)
+ * and `fooWidget` (isolated) both match the token "foo" equally. */
+function makeCollisionFixture(): string {
+ const dir = mkdtempSync(join(tmpdir(), "graft-graphrank-"));
+ writeFileSync(
+ join(dir, "connected.ts"),
+ `export function fooHandler() {\n helperAlpha();\n helperBeta();\n}\n` +
+ `export function helperAlpha() { return 1; }\n` +
+ `export function helperBeta() { return 2; }\n`,
+ );
+ writeFileSync(join(dir, "isolated.ts"), `export function fooWidget() { return 0; }\n`);
+ return dir;
+}
+
+const rank = (dir: string, gr: boolean) =>
+ ask(dir, "foo", { graphRank: gr }).hits.map((h) => h.title.split(" ·")[0]);
+
+test("ask (graphRank off): pure lexical does not favour the connected hit", async () => {
+ const dir = makeCollisionFixture();
+ try {
+ await buildGraph(dir);
+ const titles = rank(dir, false);
+ // Both same-word hits are present, no un-matched helper is rescued, and —
+ // the key point — connectivity plays no role: the graph-connected fooHandler
+ // is NOT lifted above the isolated fooWidget on pure lexical scoring.
+ assert.ok(titles.includes("fooHandler") && titles.includes("fooWidget"));
+ assert.ok(!titles.includes("helperAlpha"), "no rescue without graph-rank");
+ assert.ok(
+ titles.indexOf("fooHandler") >= titles.indexOf("fooWidget"),
+ "without graph-rank the connected hit gets no ranking advantage",
+ );
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("ask (graphRank on): connected hit outranks the isolated collision", async () => {
+ const dir = makeCollisionFixture();
+ try {
+ await buildGraph(dir);
+ const titles = rank(dir, true);
+ const iHandler = titles.indexOf("fooHandler");
+ const iWidget = titles.indexOf("fooWidget");
+ assert.ok(iHandler >= 0 && iWidget >= 0, "both same-word hits still present");
+ assert.ok(iHandler < iWidget, "the graph-connected fooHandler ranks above isolated fooWidget");
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("ask (graphRank on): a strongly-connected neighbour is rescued in", async () => {
+ const dir = makeCollisionFixture();
+ try {
+ await buildGraph(dir);
+ const titles = rank(dir, true);
+ // helperAlpha/helperBeta never contain "foo", but are called by the matched
+ // fooHandler — graph-rank surfaces them so the agent gets the whole cluster.
+ assert.ok(
+ titles.includes("helperAlpha") || titles.includes("helperBeta"),
+ "a helper the query never named is rescued via connectivity",
+ );
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("ask: graph-rank is on by default (same as graphRank:true)", async () => {
+ const dir = makeCollisionFixture();
+ try {
+ await buildGraph(dir);
+ const def = ask(dir, "foo").hits.map((h) => h.title);
+ const on = ask(dir, "foo", { graphRank: true }).hits.map((h) => h.title);
+ assert.deepEqual(def, on, "default ordering equals explicit graphRank:true");
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});