pi-graphnav 0.2.0 → 0.2.2

package/README.md

@@ -33,6 +33,13 @@ A [pi](https://github.com/earendil-works/pi-coding-agent) extension.
   phrases, string literals or in docs and config (`*.md`, `--type yaml`, …) are never touched,
   nor symbols already looked up with CodeGraph. Searches a codemode script makes with literal
   `tools.bash({ command })` / `tools.grep({ pattern })` are gated the same way.
+  A pattern only counts as a symbol when it has code shape (`parseConfig`, `ParseConfig`,
+  `start_scan`, `Foo::new`) or symbol syntax (`fn summary`, `summary(`); plain words like
+  `summary`, `cache` or `Success` are text. Before blocking, the gate asks the index (one
+  `codegraph_search`, 2 s limit, fails open) and lets the search through when the index does
+  not define the name. When it does, the block message already says where (`path:line
+  (kind)`), so one blocked call still answers the question. A search inside named files
+  (`rg start_scan src/app.rs`) is only nudged: the agent has already found the code.
 * **Nudges file-name lookups.** `fd UserService`, `find . -name '*ParseConfig*'` and pi's `find`
   tool with a camelCase or snake_case name run, with a hint to `codegraph_search` (never blocked).
 * **Hints after blind reading.** Reading several source files before any CodeGraph call adds

package/extensions/core/gate.ts

@@ -228,7 +228,7 @@ const QUALIFIED = /^[A-Za-z_$][\w$]*(?:(?:::|\.|#|->)[A-Za-z_$][\w$]*)*$/;
 const NOT_SYMBOLS = new Set(["todo", "fixme", "hack", "xxx", "note", "bug", "deprecated", "error", "warn", "warning", "info", "debug"]);
 
 /** Strip regex syntax that does not change what is being looked for. */
-function normalizeAlternative(raw: string): string {
+function normalizeAlternative(raw: string): { s: string; declared: boolean } {
 	let s = raw.trim();
 	s = s.replace(/\\[bB<>]/g, "").replace(/\[\[:<:\]\]|\[\[:>:\]\]/g, "");
 	s = s.replace(/^\^/, "").replace(/\$$/, "");
@@ -236,10 +236,23 @@ function normalizeAlternative(raw: string): string {
 		prev = s;
 		s = s.replace(/^\((?:\?:)?/, "").replace(/\)$/, "");
 	}
+	const bare = s;
 	s = s.replace(DECL, "");
+	const declared = s !== bare;
 	s = s.replace(/(?:\\?\(|\\?<|\s*\\s\*\\?\(|\s*\\s\*)$/, "");
+	const called = s !== bare && !declared && /\(\s*$|\\\(/.test(bare);
 	s = s.replace(/^(?:\.\*|\\s\*|\\s\+)+|(?:\.\*|\\s\*|\\s\+)+$/g, "");
-	return s.trim();
+	return { s: s.trim(), declared: declared || called };
+}
+
+/**
+ * Does a bare identifier look like code rather than a word? A plain `summary`, `cache`,
+ * `Success` or `ERROR` is as likely prose or a log string as a symbol, so it only counts when
+ * the search says "symbol": a declaration keyword (`fn summary`) or call syntax (`summary(`).
+ * Otherwise it needs shape: camelCase/PascalCase humps, an inner underscore, or a qualifier.
+ */
+export function isSymbolShaped(s: string): boolean {
+	return /::|\.|#|->/.test(s) || /[a-z0-9][A-Z]/.test(s) || /^[A-Z][a-z0-9]+[A-Z]/.test(s) || /[A-Za-z0-9]_[A-Za-z0-9]/.test(s);
 }
 
 /**
@@ -252,11 +265,13 @@ export function symbolsIn(pattern: string | undefined): string[] | undefined {
 	const alternatives = pattern.split(/\\?\|/);
 	const out: string[] = [];
 	for (const alt of alternatives) {
-		const s = normalizeAlternative(alt);
+		const { s, declared } = normalizeAlternative(alt);
 		if (s.length < 3 || !QUALIFIED.test(s) || KEYWORDS.has(s)) return undefined;
+		if (!declared && !isSymbolShaped(s)) return undefined;
 		const parts = s.split(/::|\.|#|->/);
 		if (parts.some((p) => NOT_SYMBOLS.has(p.toLowerCase()))) return undefined;
 		if (/^[A-Z0-9_]+$/.test(s) && s.length <= 4) return undefined;
+		if (/^_+$|^[a-z]+_$/.test(s)) return undefined;
 		out.push(s);
 	}
 	return out.length > 0 ? out : undefined;
@@ -284,21 +299,64 @@ export interface GateMemory {
 	lookedUp: Set<string>;
 	/** Commands blocked once: running the same command again is the agent's explicit override. */
 	blocked: Set<string>;
+	/** Lower-cased words the index was asked about and does not define: text, not symbols. */
+	unindexed: Set<string>;
+	/** Lower-cased leaf → where the index defines it (`path:line (kind)`), from the gate's probe. */
+	defined: Map<string, string[]>;
 }
 
-export const newMemory = (): GateMemory => ({ lookedUp: new Set(), blocked: new Set() });
+export const newMemory = (): GateMemory => ({ lookedUp: new Set(), blocked: new Set(), unindexed: new Set(), defined: new Map() });
+
+/** Last segment of a qualified name, lower-cased: what the index is keyed by. */
+export const leafOf = (symbol: string): string => symbol.toLowerCase().split(/::|\.|#|->/).pop()!;
 
 const known = (symbol: string, mem: GateMemory) => {
 	const s = symbol.toLowerCase();
+	if (mem.unindexed.has(leafOf(s))) return true;
 	if (mem.lookedUp.has(s)) return true;
 	const last = s.split(/::|\.|#|->/).pop()!;
 	return mem.lookedUp.has(last);
 };
 
+/**
+ * Does a `codegraph_search` answer define `symbol`? Reads the `**name** (kind)` headings and
+ * compares the last path segment, case-insensitively.
+ */
+export function indexDefines(searchText: string, symbol: string): boolean {
+	return definitionsIn(searchText, symbol).length > 0;
+}
+
+/** Where a `codegraph_search` answer defines `symbol`: `path:line (kind)`, at most `max`. */
+export function definitionsIn(searchText: string, symbol: string, max = 5): string[] {
+	const leaf = leafOf(symbol);
+	const out: string[] = [];
+	for (const m of searchText.matchAll(/^\*\*(.+?)\*\* \(([^)\n]*)\)[ \t]*\n([^\n`*]*)/gm)) {
+		if (m[1]!.toLowerCase() !== leaf) continue;
+		const at = m[3]!.trim();
+		out.push(at ? `${at} (${m[2]})` : `(${m[2]})`);
+		if (out.length >= max) break;
+	}
+	return out;
+}
+
+/** Does every search name only files (not directories), so it reads code already pinned down? */
+const onlyNamedFiles = (s: Search): boolean => s.paths.length > 0 && s.paths.every((p) => extOf(p) !== undefined && !/[*?{[]/.test(p));
+
+/** Symbols a search set would be gated on (not yet looked up, not known to be text). */
+export function candidateSymbols(searches: Search[], mem: GateMemory): string[] {
+	const out = new Set<string>();
+	for (const s of searches) {
+		if (s.files || targetsOnlyNonCode(s)) continue;
+		for (const sym of symbolsIn(s.pattern) ?? []) if (!known(sym, mem)) out.add(sym);
+	}
+	return [...out];
+}
+
 export function suggestion(symbols: string[]): string {
 	const q = symbols.join(" ");
 	const one = symbols[0]!;
 	return [
+		`codegraph_node({ symbol: "${one}", includeCode: true }) for its source`,
 		`codegraph_search({ query: "${one}" }) for the definition`,
 		`codegraph_callers({ symbol: "${one}" }) for usages`,
 		`codegraph_explore({ query: "${q}" }) for the code around it`,
@@ -313,9 +371,14 @@ export function decide(mode: Mode, searches: Search[], key: string, mem: GateMem
 	if (mode === "off") return { action: "allow" };
 	const symbols = new Set<string>();
 	const names = new Set<string>();
+	let scoped = true;
 	for (const s of searches) {
 		if (targetsOnlyNonCode(s)) continue;
-		for (const sym of (s.files ? fileSymbolIn(s.pattern) : symbolsIn(s.pattern)) ?? []) if (!known(sym, mem)) (s.files ? names : symbols).add(sym);
+		for (const sym of (s.files ? fileSymbolIn(s.pattern) : symbolsIn(s.pattern)) ?? []) {
+			if (known(sym, mem)) continue;
+			(s.files ? names : symbols).add(sym);
+			if (!s.files && !onlyNamedFiles(s)) scoped = false;
+		}
 	}
 	if (symbols.size === 0 && names.size === 0) return { action: "allow" };
 	if (symbols.size === 0) {
@@ -326,8 +389,14 @@ export function decide(mode: Mode, searches: Search[], key: string, mem: GateMem
 		};
 	}
 	const list = [...symbols];
-	const hint = `"${list.join('", "')}" ${list.length === 1 ? "looks like a symbol" : "look like symbols"}: CodeGraph answers this structurally. Use ${suggestion(list)}.`;
-	if (mode === "nudge") return { action: "nudge", hint: `[codegraph] ${hint}` };
+	const where = list.flatMap((sym) => {
+		const at = mem.defined.get(leafOf(sym));
+		return at && at.length > 0 ? [`${sym} is defined at ${at.join(", ")}`] : [];
+	});
+	const found = where.length > 0 ? ` ${where.join("; ")}.` : "";
+	const hint = `"${list.join('", "')}" ${list.length === 1 ? "looks like a symbol" : "look like symbols"}: CodeGraph answers this structurally.${found} Use ${suggestion(list)}.`;
+	// A search inside named files reads code the agent already pinned down: hint, do not block.
+	if (mode === "nudge" || scoped) return { action: "nudge", hint: `[codegraph] ${hint}` };
 	if (mem.blocked.has(key)) return { action: "allow", override: true };
 	mem.blocked.add(key);
 	return {

package/extensions/core/tools.ts

@@ -114,7 +114,7 @@ export const isCodeGraphTool = (name: string): boolean => TOOL_NAMES.includes(na
 
 /** Guidelines added to the system prompt while the tools are active (static: they never break the prompt cache). */
 export const GUIDELINES = [
-	"Understand code through CodeGraph first: codegraph_explore for how something works or where to change it, codegraph_search to find a definition, codegraph_callers/codegraph_callees for relations, codegraph_impact before changing a signature, codegraph_files for structure.",
+	"Understand code through CodeGraph first: codegraph_explore for how something works or where to change it, codegraph_search to find a definition, codegraph_node with includeCode for a symbol's body (instead of rg -A), codegraph_callers/codegraph_callees for relations, codegraph_impact before changing a signature, codegraph_files for structure.",
 	"Do not grep (rg, grep, git grep) for symbol names: such searches are redirected to CodeGraph. Text search is for string literals, comments, config and docs, or after CodeGraph came up empty.",
 	"Read a file once CodeGraph has told you where to look, with offset/limit around the reported lines.",
 ];

package/extensions/graphnav.ts

@@ -17,10 +17,13 @@ import { completions, parseCommand } from "./command/parse.ts";
 import { type Config, DEFAULT_CONFIG, type ProjectOverrides, readConfig, readProjectConfig, saveConfig } from "./core/config.ts";
 import {
 	codemodeSearches,
+	candidateSymbols,
 	decide,
 	findFileSearches,
 	findSearches,
 	type GateMemory,
+	definitionsIn,
+	leafOf,
 	isSourceFile,
 	lookupWords,
 	newMemory,
@@ -131,6 +134,15 @@ export interface Deps {
 	breaker?: { threshold: number; resetMs: number };
 }
 
+const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T> =>
+	new Promise((resolve, reject) => {
+		const t = setTimeout(() => reject(new Error("timeout")), ms);
+		p.then(
+			(v) => (clearTimeout(t), resolve(v)),
+			(e) => (clearTimeout(t), reject(e)),
+		);
+	});
+
 export function createExtension(deps: Deps = {}) {
 	const run = deps.run ?? defaultRunner;
 	return function (pi: ExtensionAPI) {
@@ -198,6 +210,9 @@ export function createExtension(deps: Deps = {}) {
 					index = status;
 					lastError = error;
 					state = error ? "error" : status.initialized ? "ready" : "missing";
+					// the index changed: earlier probe answers may be stale
+					mem.unindexed.clear();
+					mem.defined.clear();
 				})
 				.finally(() => {
 					job = undefined;
@@ -300,6 +315,24 @@ export function createExtension(deps: Deps = {}) {
 			if (!config.enabled || config.mode === "off" || state !== "ready" || unavailable()) return;
 			const searches = searchesOf(event.toolName, event.input ?? {});
 			if (searches.length === 0) return;
+			// Gate only what the index defines: a word it has never heard of is text, not a symbol.
+			const root = project?.root;
+			if (root) {
+				const unknown = candidateSymbols(searches, mem).filter((sym) => !mem.defined.has(leafOf(sym)));
+				await Promise.all(
+					unknown.map(async (sym) => {
+						try {
+							const res = await withTimeout(server(root).call("codegraph_search", { query: leafOf(sym), limit: 25, projectPath: root }), 2000);
+							if (res.isError) return;
+							const at = definitionsIn(resultText(res), sym);
+							if (at.length === 0) mem.unindexed.add(leafOf(sym));
+							else mem.defined.set(leafOf(sym), at);
+						} catch {
+							// index unreachable or slow: fail open to the usual gate rather than guess
+						}
+					}),
+				);
+			}
 			const d = decide(config.mode, searches, `${event.toolName}\u0000${JSON.stringify(event.input)}`, mem);
 			if (d.action === "block") {
 				counts.blocked++;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-graphnav",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "CodeGraph-first code navigation for pi: persistent index, auto init/sync, and a gate that steers structural searches to codegraph_* tools.",
   "keywords": [
     "pi-package",