fix(explore): stop NL-question words from hijacking the named-symbol tier when they collide with real callables (#1252)

handleExplore's named-symbol seeding treats every identifier-shaped query
token as "a symbol the agent named" and grants its definition the
named-FIRST sort tier. Natural-language questions broke this assumption:
ordinary words exact-matched unrelated callables ("check" ->
WalCheckpointValve.check, "serve" -> query-worker serve, "initialize" ->
DatabaseConnection.initialize), and those collisions outranked — and within
the per-repo file budget fully displaced — the corroborated answer files,
forcing the agent back to Read/Grep. The >3-def single-pick fallback had
the same hole: on grpc, the #1064 flagship query "add a parameter to
NewClient" itself tiered balancerStateAggregator.add's file to slot #1.

Guard: a shape-precise token (camelCase, PascalCase, snake_case,
qualified) seeds unconditionally — it is an unambiguous symbol reference.
A bare lowercase word seeds only defs whose file another query token
co-names (that token is itself an exact symbol name defined in the same
file — the "check drain fire" sibling-bag shape), which an incidental
English-word collision never is. Applied by filtering cands ahead of both
branches so the overloaded-name fallback is covered too.

Validated per the retrieval playbook: deterministic probes on this repo
(collision queries fixed; sibling-bag and single-camelCase retained), and
baseline-vs-fixed probes on the #1064 repos — Alamofire and excalidraw
byte-identical, grpc improved (the add-collision file drops out and
clientconn.go + dialoptions.go lead). Full suite green.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

CHANGELOG.md

@@ -11,6 +11,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixes
 
+- `codegraph_explore` no longer lets ordinary English words in a natural-language question hijack the ranking when they happen to match a code symbol's name. A question like "how does the upgrade flow check the latest version" used to treat "check" as a symbol the agent asked for by name, rank that unrelated definition's file first, and crowd the files the question is actually about out of the answer entirely. Precisely written symbol names (camelCase, PascalCase, snake_case, qualified names) still get top billing exactly as before, as do plain-word symbol bags whose words belong together in the same file.
 - PHP method calls made through a class property — `$this->dep->method()`, the dominant call shape in constructor-injection codebases (Symfony, Laravel) — now resolve to the method on the property's declared type, so callers and impact analysis see production call sites instead of reporting a DI-heavy method as uncalled or test-only. Promoted constructor parameters, typed properties, classic constructor assignment (including multi-line signatures), and typed setter injection all count; interface-typed properties resolve to the interface method, and inherited methods resolve through the type hierarchy. Only property-shaped declarations are consulted — a same-named local variable or parameter elsewhere can never mistype the property — and a property whose type can't be recovered statically stays unlinked rather than guessed. Thanks @w0lan. (#1220)
 - `codegraph upgrade` now also refreshes what previous versions installed into your agents — the CodeGraph section in CLAUDE.md / AGENTS.md / GEMINI.md and the MCP entry — so upgrading no longer leaves agents following instructions written for tools that have since been renamed or removed. Refresh-only: agents you never configured are not touched, and your permission and hook choices are preserved. Also available manually as `codegraph install --refresh`, and skippable with `CODEGRAPH_NO_INSTALL_REFRESH=1`. (#1238)
 - `codegraph upgrade` on an npm install now upgrades through npm again instead of quietly creating a second copy that never wins the PATH race — previously `codegraph --version` kept reporting the old version forever, no matter how many times you upgraded. (#1238)

__tests__/explore-nl-stopword-collision.test.ts

@@ -0,0 +1,125 @@
+/**
+ * codegraph_explore — NL-stopword collision guard (named-symbol seeding).
+ *
+ * handleExplore's named-symbol seeding treats every identifier-shaped query
+ * token as "a symbol the agent named" and grants its definition the
+ * named-FIRST sort tier. But explore also takes natural-language questions,
+ * whose ordinary English words collide with real callables: on this repo the
+ * query "…check the latest version…" exact-matched the lone `check()` method
+ * of an unrelated WAL-valve class, which then outranked (and, within the
+ * per-repo file budget, fully displaced) the upgrade module the corroboration
+ * ranking had correctly scored — so the agent fell back to Read/Grep.
+ *
+ * The guard: a shape-precise token (camelCase, PascalCase, snake_case,
+ * qualified) seeds unconditionally — it is an unambiguous symbol reference.
+ * A BARE lowercase word seeds only definitions whose file another query token
+ * co-names (that other token is itself a symbol defined in the same file, the
+ * "check drain fire" sibling-bag shape) — which an incidental English-word
+ * collision never is.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import CodeGraph from '../src/index';
+import { ToolHandler } from '../src/mcp/tools';
+
+/** Paths explore rendered as full-body ``**`<path>`** —`` source sections, in order. */
+function sourcedFiles(text: string): string[] {
+  const out: string[] = [];
+  for (const line of text.split('\n')) {
+    const m = line.match(/^\*\*`(.+?)`\*\* —/);
+    if (m) out.push(m[1].trim());
+  }
+  return out;
+}
+
+describe('codegraph_explore — NL-stopword collision guard', () => {
+  let testDir: string;
+  let cg: CodeGraph;
+  let handler: ToolHandler;
+
+  beforeEach(async () => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-stopword-'));
+
+    // --- The collision file: an unrelated class whose methods are ordinary
+    // English words ("check", "drain", "fire" — the only defs of those names).
+    // Substantive bodies + an internal call mesh so it isn't skipped as a stub.
+    const dbDir = path.join(testDir, 'src', 'db');
+    fs.mkdirSync(dbDir, { recursive: true });
+    fs.writeFileSync(path.join(dbDir, 'valve.ts'),
+      `export class Valve {\n` +
+      `  private open = false;\n` +
+      `  check(): void {\n` +
+      `    if (this.open) {\n` +
+      `      this.fire();\n` +
+      `    }\n` +
+      `  }\n` +
+      `  fire(): void {\n` +
+      `    this.drain();\n` +
+      `    this.open = false;\n` +
+      `  }\n` +
+      `  drain(): void {\n` +
+      `    this.open = true;\n` +
+      `  }\n` +
+      `}\n`);
+
+    // --- The answer file: the upgrade module the query is actually about.
+    // Its path and symbol names match the query's topic terms (upgrade,
+    // latest, version), so the corroboration ranking scores it — the bug was
+    // the collision file's named tier sorting ABOVE it anyway.
+    const upDir = path.join(testDir, 'src', 'upgrade');
+    fs.mkdirSync(upDir, { recursive: true });
+    fs.writeFileSync(path.join(upDir, 'updater.ts'),
+      `export function normalizeVersion(v: string): string {\n` +
+      `  return v.startsWith('v') ? v : 'v' + v;\n` +
+      `}\n` +
+      `export function resolveLatestVersion(): string {\n` +
+      `  return normalizeVersion('9.9.9');\n` +
+      `}\n` +
+      `export function runUpgrade(): string {\n` +
+      `  const latest = resolveLatestVersion();\n` +
+      `  return latest;\n` +
+      `}\n`);
+
+    cg = CodeGraph.initSync(testDir, { config: { include: ['**/*.ts'], exclude: [] } });
+    await cg.indexAll();
+    handler = new ToolHandler(cg);
+  });
+
+  afterEach(() => {
+    if (cg) cg.destroy();
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  async function explore(query: string): Promise<string> {
+    const res = await handler.execute('codegraph_explore', { query });
+    expect(res.isError).toBeFalsy();
+    return res.content[0]!.text;
+  }
+
+  it('a bare English word ("check") does not tier its namesake above the corroborated answer file', async () => {
+    const text = await explore('how does the upgrade flow check the latest version');
+    const files = sourcedFiles(text);
+    const updater = files.findIndex((f) => f.endsWith('updater.ts'));
+    const valve = files.findIndex((f) => f.endsWith('valve.ts'));
+    // The upgrade module must render, and must rank above the collision file
+    // (pre-guard, valve.ts held the named-FIRST tier and sorted on top).
+    expect(updater).toBeGreaterThanOrEqual(0);
+    if (valve !== -1) expect(updater).toBeLessThan(valve);
+  });
+
+  it('a sibling bag of bare words ("check drain fire") still tiers their shared file first', async () => {
+    const text = await explore('check drain fire');
+    const files = sourcedFiles(text);
+    // Every token is co-named by the others in valve.ts — genuine bare-name
+    // symbol bags must keep the named tier.
+    expect(files[0]).toMatch(/valve\.ts$/);
+  });
+
+  it('a shape-precise token (camelCase) seeds unconditionally', async () => {
+    const text = await explore('runUpgrade');
+    const files = sourcedFiles(text);
+    expect(files[0]).toMatch(/updater\.ts$/);
+  });
+});

src/mcp/tools.ts

@@ -2611,6 +2611,36 @@ export class ToolHandler {
           const lc = ct.toLowerCase();
           return n.filePath.toLowerCase().includes(lc) || n.qualifiedName.toLowerCase().includes(lc);
         });
+      // NL-stopword guard: this seeding treats every token as "a symbol the
+      // agent named", but explore also takes natural-language questions, whose
+      // ordinary English words collide with real callables — "…check the latest
+      // version…" exact-matched a lone `check()` method, which then earned the
+      // named-FIRST sort tier and displaced the corroborated answer files from
+      // the whole render budget (the agent fell back to Read). A shape-precise
+      // token (camelCase, PascalCase, snake_case, qualified) is an unambiguous
+      // symbol reference and seeds unconditionally; a BARE lowercase word seeds
+      // only where the query corroborates the file — another query token is
+      // itself a symbol defined in that same file (the "check drain fire"
+      // sibling-bag case), which an incidental English-word collision never is.
+      const lcTokens = new Set(tokens.map((x) => x.toLowerCase()));
+      const isPreciseToken = (x: string) =>
+        /[._$]|::|\//.test(x) || /[a-z][A-Z]/.test(x) || /^[A-Z]/.test(x);
+      const fileNameSets = new Map<string, Set<string>>();
+      const coNamedInFile = (t: string, fp: string): boolean => {
+        let names = fileNameSets.get(fp);
+        if (!names) {
+          names = new Set<string>();
+          try {
+            for (const n of cg.getNodesInFile(fp)) names.add(n.name.toLowerCase());
+          } catch { /* unreadable file entry — treat as uncorroborated */ }
+          fileNameSets.set(fp, names);
+        }
+        const self = t.toLowerCase();
+        for (const o of lcTokens) {
+          if (o !== self && names.has(o)) return true;
+        }
+        return false;
+      };
       for (const t of tokens) {
         // Enumerate ALL defs of a bare token via the direct index, not FTS — a
         // 50+-overload name (tokio `poll`) ranks the wanted def (`Harness::poll`)
@@ -2619,9 +2649,17 @@ export class ToolHandler {
         // codegraph_node's findSymbolMatches.) Qualified tokens keep findAllSymbols.
         const isQual = /[.\/]|::/.test(t);
         const raw = isQual ? this.findAllSymbols(cg, t).nodes : cg.getNodesByName(t);
-        const cands = raw
+        let cands = raw
           .filter((n) => CALLABLE.has(n.kind) && !isTestPath(n.filePath))
           .sort((a, b) => (bodyLines(b) > 1 ? 1 : 0) - (bodyLines(a) > 1 ? 1 : 0) || bodyLines(b) - bodyLines(a));
+        // Bare lowercase words only seed defs their query-siblings corroborate
+        // (see the NL-stopword guard above). Filtering CANDS (not picks) applies
+        // the guard uniformly to both branches below, including the >3-def
+        // single-pick fallback — an uncorroborated bare `run` must not tier its
+        // most-substantive namesake any more than a 1-def `check` may.
+        if (!isPreciseToken(t)) {
+          cands = cands.filter((n) => coNamedInFile(t, n.filePath));
+        }
         // A specific name (<=3 defs) injects all its defs. An overloaded name
         // (`validate` = 10, `request` = 44) would flood the subgraph, so inject
         // only: the overloads whose file/class the query ALSO names (the agent