explore returns 260 symbols / 124 files for a 6-word natural-language query on a 636-file project

[jcrabapple]

codegraph explore returns excessive results on broad natural-language queries — 260 symbols for a 636-file project

Related: #765 (explore noise on multi-language repos), #982 (generic token name-match overboosting). This report adds a data point from a single-language project where the noise is not from cross-language conflation but from query breadth.

Reproduction

# Project: Android Mastodon client, 636 Java source files (27k total including XML resources)
codegraph init .
codegraph explore "publish status to mastodon API"

Result

Found 260 symbols across 124 files.

That's 40% of the project's Java files (124/636) and includes clearly unrelated symbols:

• GetNotificationsV1 — notification fetching, not status publishing
• GetOauthToken — OAuth, not status publishing
• BarcodeScanner / Status (Google Play Services com.google.android.gms.common.api.Status) — barcode scanner API, not Mastodon status
• SetPrivateNote — unrelated API request
• ModuleInstallResponse / ModuleAvailabilityResponse — Google Play Services module installation

The correct symbols (ComposeFragment.publish, actuallyPublish, CreateStatus, EditStatus) are present and ranked first, but a user or agent has to wade through 260 symbols to confirm there's nothing else relevant.

Contrast with targeted queries

The same tool with a symbol-name query works well:

codegraph explore "actuallyPublish send status to API endpoint"
# → Found 171 symbols across 89 files — still broad, but the dynamic boundary
#   detection correctly identifies the Otto event bus dispatch

codegraph callers publish
# → 3 callers, all correct. Tight and accurate.

Analysis

The issue is that codegraph_explore's token matching is too permissive for natural-language queries. Words like "status", "publish", "API" match a large fraction of symbols in any API-heavy codebase. The existing isDistinctiveIdentifier demotion (#982) fires for single common words but doesn't adequately constrain the result set when multiple common words combine.

Suggestion

Two non-exclusive options:

1. Tighter initial filter: When the query is natural-language (vs known symbol names), apply a higher relevance threshold before returning results. The 260→171 drop from adding one specific token ("actuallyPublish") suggests the filter is binary (match/no-match) rather than graduated.

2. Result cap with expansion hint: Cap at N symbols (e.g., 50) with a note: "Showing top 50 of 260 matches. Refine your query or use codegraph_search for broader results." This prevents context bloat when the agent is using the MCP tool.

Environment

• CodeGraph v1.1.2 (linux-x64, bundled install)
• Project: Moshidon/Tootsie fork (Mastodon Android client), 636 Java files

[colbymchenry]

Fixed in #1053 (merged to main) — thanks for the careful writeup, and especially for confirming that the correct symbols are present and ranked first. That observation is what scoped the fix.

What I changed: the "Found N symbols across M files" header was reporting the raw candidate gather — every symbol the search swept in while ranking — not the curated set that actually renders. A broad query FTS-matches a huge pool ("status"/"publish"/"api" hit a large fraction of any API-heavy repo), so you got "260 across 124" even though only the few correctly-ranked files are shown with source. The header now counts just the files explore returns source for, so the number matches what you see (e.g. "Found 19 symbols across 3 files"). Overflow relevant files are still listed by name under "Not shown above", so nothing is hidden.

What I deliberately did not change (yet): the underlying gather/ranking. That's the part that's heavily benchmarked, and since the right answer already ranks first, tightening the initial filter (your suggestion #1) risks regressing the validated retrieval behavior without a full small/medium/large A/B pass — a bigger, separate piece of work, not a quick fix. Your suggestion #2 (cap + expansion hint) is effectively how rendering already works — the budget caps what's shown and "Not shown above" + the budget note are the expansion hints — so this change mostly makes the header honest about that existing cap.

So: the misleading count is gone now; the deeper "narrow the candidate pool for natural-language queries" idea is noted as a follow-up. This ships in the next release (it's on main, not in v1.1.2).