Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
feat(ask): graph-rank + IDF + body indexing, and fix silent 32KB parse drop
Shrish Dwivedicdec18e56065
diff --git a/package-lock.json b/package-lock.jsonindex 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.jsonindex 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.tsindex 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 = {}): AskResulconst 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.tsnew file mode 100644index 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.tsindex 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): ExtracparentId: 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: RawEdexported: 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.tsindex 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 triggerchars?: 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.tsindex 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.tsnew file mode 100644index 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 });+ }+});