pi-graphnav 0.2.1 → 0.3.0

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
@@ -76,6 +83,7 @@ pi install npm:pi-graphnav
 | `/codegraph` or `/codegraph status` | project, index state, mode, blocked/nudged counts |
 | `/codegraph [on\|off]` | switch it all (remembered across sessions) |
 | `/codegraph mode <mode>` | symbol searches: `enforce` (default), `nudge` or `off` |
+| `/codegraph statusline <when>` | status line: `always` (default), `problems` or `never`; CodeGraph keeps working |
 | `/codegraph sync` | sync the index with changed files |
 | `/codegraph reindex` | rebuild the index from scratch |
 | `/codegraph init` | create the index (for a directory that is not a git repo) |
@@ -85,7 +93,7 @@ Settings live in `<pi agent dir>/codegraph.json` (`PI_CODING_AGENT_DIR`, else `~
 | Key | Default | |
 |---|---|---|
 | `enabled` | `true` | master switch |
-| `showStatus` | `true` | status line entry |
+| `showStatus` | `"always"` | status line entry: `"always"`, `"problems"` (only while indexing, or when the index is missing, failing or unavailable) or `"never"`; `true`/`false` still work |
 | `mode` | `"enforce"` | `enforce`, `nudge` or `off` |
 | `autoInit` | `true` | init a git repo that has no index |
 | `autoSync` | `true` | sync or rebuild a stale index at session start |

package/extensions/command/parse.ts

@@ -1,17 +1,18 @@
 /** `/codegraph ...`: parsing and argument completion. Pure: the handler in graphnav.ts acts on the result. */
-import { MODES, type Mode } from "../core/config.ts";
+import { MODES, type Mode, STATUS_SHOWS, type StatusShow } from "../core/config.ts";
 
 export type Command =
 	| { kind: "status" }
 	| { kind: "on" }
 	| { kind: "off" }
 	| { kind: "mode"; mode: Mode }
+	| { kind: "statusline"; show: StatusShow }
 	| { kind: "sync" }
 	| { kind: "reindex" }
 	| { kind: "init" }
 	| { kind: "invalid"; message: string };
 
-export const USAGE = "Usage: /codegraph [status] · on · off · mode <enforce|nudge|off> · sync · reindex · init";
+export const USAGE = "Usage: /codegraph [status] · on · off · mode <enforce|nudge|off> · statusline <always|problems|never> · sync · reindex · init";
 
 export function parseCommand(args: string | undefined): Command {
 	const [cmd, ...rest] = (args ?? "").trim().split(/\s+/).filter(Boolean);
@@ -31,6 +32,12 @@ export function parseCommand(args: string | undefined): Command {
 				? { kind: "mode", mode: m as Mode }
 				: { kind: "invalid", message: "Usage: /codegraph mode <enforce|nudge|off>" };
 		}
+		case "statusline": {
+			const v = rest[0]?.toLowerCase();
+			return STATUS_SHOWS.includes(v as StatusShow) && rest.length === 1
+				? { kind: "statusline", show: v as StatusShow }
+				: { kind: "invalid", message: "Usage: /codegraph statusline <always|problems|never>" };
+		}
 		case "sync":
 			return { kind: "sync" };
 		case "reindex":
@@ -55,6 +62,7 @@ const TOP_LEVEL: CompletionItem[] = [
 	{ value: "on", label: "on", description: "Turn CodeGraph-first on" },
 	{ value: "off", label: "off", description: "Turn CodeGraph-first off" },
 	{ value: "mode ", label: "mode", description: "Symbol searches: enforce, nudge or off" },
+	{ value: "statusline ", label: "statusline", description: "Status line: always, only problems, or never" },
 	{ value: "sync", label: "sync", description: "Sync the index with changed files" },
 	{ value: "reindex", label: "reindex", description: "Rebuild the index from scratch" },
 	{ value: "init", label: "init", description: "Create the index for this project" },
@@ -66,10 +74,16 @@ const MODE_ITEMS: CompletionItem[] = [
 	{ value: "mode off", label: "off", description: "Leave text searches alone" },
 ];
 
+const STATUSLINE_ITEMS: CompletionItem[] = [
+	{ value: "statusline always", label: "always", description: "Always show the CodeGraph status" },
+	{ value: "statusline problems", label: "problems", description: "Only while indexing, or when the index is missing, failing or unavailable" },
+	{ value: "statusline never", label: "never", description: "Never show it (CodeGraph keeps working)" },
+];
+
 /** `prefix` is the whole argument text typed so far (pi replaces it with `value`). */
 export function completions(prefix: string): CompletionItem[] | null {
 	const text = (prefix ?? "").toLowerCase().replace(/^\s+/, "");
-	const pool = text.startsWith("mode ") ? MODE_ITEMS : TOP_LEVEL;
+	const pool = text.startsWith("mode ") ? MODE_ITEMS : text.startsWith("statusline ") ? STATUSLINE_ITEMS : TOP_LEVEL;
 	const out = pool.filter((i) => i.value.startsWith(text));
 	return out.length > 0 ? out : null;
 }

package/extensions/core/config.ts

@@ -11,11 +11,22 @@ import { join } from "node:path";
 export type Mode = "enforce" | "nudge" | "off";
 export const MODES: readonly Mode[] = ["enforce", "nudge", "off"];
 
+/** Status line: always, only when something needs attention (indexing, missing, error, unavailable), or never. */
+export type StatusShow = "always" | "problems" | "never";
+export const STATUS_SHOWS: readonly StatusShow[] = ["always", "problems", "never"];
+
+/** `showStatus` from a config file: one of STATUS_SHOWS, or the 0.2 booleans (true = always, false = never). */
+export function parseStatusShow(v: unknown): StatusShow | undefined {
+	if (v === true) return "always";
+	if (v === false) return "never";
+	return STATUS_SHOWS.includes(v as StatusShow) ? (v as StatusShow) : undefined;
+}
+
 export interface Config {
 	/** Master switch: when false the extension adds no guidance, gates nothing and indexes nothing. */
 	enabled: boolean;
-	/** Show the status line entry. */
-	showStatus: boolean;
+	/** When to show the status line entry. */
+	showStatus: StatusShow;
 	/** Symbol searches with rg/grep: block once (`enforce`), only add a hint (`nudge`) or leave alone (`off`). */
 	mode: Mode;
 	/** Create the index (`codegraph init`) for a git repo that has none. */
@@ -32,7 +43,7 @@ export interface Config {
 
 export const DEFAULT_CONFIG: Config = {
 	enabled: true,
-	showStatus: true,
+	showStatus: "always",
 	mode: "enforce",
 	autoInit: true,
 	autoSync: true,
@@ -49,7 +60,7 @@ export function sanitizeConfig(raw: unknown): Config {
 	const d = DEFAULT_CONFIG;
 	return {
 		enabled: typeof r.enabled === "boolean" ? r.enabled : d.enabled,
-		showStatus: typeof r.showStatus === "boolean" ? r.showStatus : d.showStatus,
+		showStatus: parseStatusShow(r.showStatus) ?? d.showStatus,
 		mode: MODES.includes(r.mode as Mode) ? (r.mode as Mode) : d.mode,
 		autoInit: typeof r.autoInit === "boolean" ? r.autoInit : d.autoInit,
 		autoSync: typeof r.autoSync === "boolean" ? r.autoSync : d.autoSync,

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

@@ -14,13 +14,16 @@ import { homedir } from "node:os";
 import { resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { completions, parseCommand } from "./command/parse.ts";
-import { type Config, DEFAULT_CONFIG, type ProjectOverrides, readConfig, readProjectConfig, saveConfig } from "./core/config.ts";
+import { type Config, DEFAULT_CONFIG, type ProjectOverrides, readConfig, readProjectConfig, saveConfig, type StatusShow } from "./core/config.ts";
 import {
 	codemodeSearches,
+	candidateSymbols,
 	decide,
 	findFileSearches,
 	findSearches,
 	type GateMemory,
+	definitionsIn,
+	leafOf,
 	isSourceFile,
 	lookupWords,
 	newMemory,
@@ -51,6 +54,13 @@ export interface Status {
 	error?: string;
 }
 
+/** Does the status line show for this setting? `problems`: only when the user may need to act or wait. */
+export function showsStatus(show: StatusShow, s: Status): boolean {
+	if (show === "never") return false;
+	if (show === "always") return true;
+	return !!s.unavailable || s.state === "indexing" || s.state === "missing" || s.state === "error";
+}
+
 export function statusText(s: Status): string {
 	if (!s.config.enabled) return "codegraph: off";
 	if (s.unavailable) return `codegraph: unavailable · ${s.config.mode}`;
@@ -131,6 +141,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) {
@@ -158,7 +177,7 @@ export function createExtension(deps: Deps = {}) {
 		const guardNow = new Map<string, Guard>();
 		const unavailable = (root = project?.root) => (root ? (guardNow.get(root)?.open ?? false) : false);
 		const snapshot = (): Status => ({ config, project, state, index, error: lastError, ...counts, unavailable: unavailable(), overrides });
-		const refresh = () => ui?.setStatus("codegraph", config.enabled && config.showStatus ? statusText(snapshot()) : "");
+		const refresh = () => ui?.setStatus("codegraph", config.enabled && showsStatus(config.showStatus, snapshot()) ? statusText(snapshot()) : "");
 
 		const server = (root: string) => {
 			let s = servers.get(root);
@@ -198,6 +217,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 +322,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++;
@@ -388,6 +428,11 @@ export function createExtension(deps: Deps = {}) {
 					await persist();
 					ctx.ui.notify(`codegraph: mode ${cmd.mode}`, "info");
 					return;
+				case "statusline":
+					config.showStatus = base.showStatus = cmd.show;
+					await persist();
+					ctx.ui.notify(`codegraph: status line ${cmd.show}`, "info");
+					return;
 				case "sync":
 				case "reindex":
 				case "init": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-graphnav",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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",