feat(config): surface matches hidden by extension filters

[reneleonhardt]

What does this PR do?

• Make MCP file searches respect the project's only and exclude filters.
• Apply those filters consistently to context, structure, project-statistics, dependency, and file-graph scans.
• When only hides real matches, report them and explain how to include or suppress their extensions.
• Enable extension hints by default with guidance.missing_extension_hints; set it to false to disable them.
• Allow selected hints to be suppressed with guidance.ignored_extensions.

Type of change

• Bug fix
• New feature
• New language support
• Documentation
• Other (describe below)

Checklist

• I've tested this locally with go build && ./codemap .
• I've read CONTRIBUTING.md (for new language support)
• I've updated documentation if needed

Additional notes

Repository languages evolve after initial setup. Actionable misses prevent agents from repeatedly failing or silently falling back to raw filesystem searches, without rescanning or changing config automatically.

Focused MCP, context, dependency, and file-graph tests pass with the full race
suite, formatting, module verification, vet, staticcheck, and a built-binary
parity probe. The probe confirmed the CLI context, MCP structure, and MCP project
statistics all report the same configured file count.

Reviewer setup:

set -euo pipefail

ROOT=$PWD
BRANCH=feat/config-only-fallback
REVIEW_ROOT=$(mktemp -d "${TMPDIR:-/tmp}/codemap-config-fallback.XXXXXX")
WT="$REVIEW_ROOT/worktree"
DEBUG_BIN="$REVIEW_ROOT/codemap-debug"
COVERAGE_OUT="$REVIEW_ROOT/coverage.out"

git worktree add --detach "$WT" "$BRANCH"

cleanup() {
  cd "$ROOT"
  git worktree remove --force "$WT"
  rm -rf "$REVIEW_ROOT"
}
trap cleanup EXIT

cd "$WT"
go fmt ./...
git diff --exit-code
go mod verify
go vet ./...
staticcheck ./...
go test -race -coverprofile="$COVERAGE_OUT" ./...
go build -gcflags='all=-N -l' -o "$DEBUG_BIN" .
"$DEBUG_BIN" .
cleanup
trap - EXIT

Developed with carefully directed, manually reviewed AI assistance. Allow edits by maintainers is enabled, so maintainers are welcome to fix wording or make minor cleanup directly; broader review feedback will be incorporated.

Co-Authored-By: GPT-5.6 Sol codex@openai.com

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[JordanCoin]

Reviewed the logic and tests carefully — the core filter/hint design is sound. Hinted files must fail only but pass exclude, so explicitly excluded paths are never leaked; the hint is bounded (5 paths + "and N more"); and I especially appreciated TestHandleFindFileExplainsOnlyFilteredMatches asserting config.json is byte-identical after the call. Default-on for guidance.missing_extension_hints is reasonable since it only fires on zero-result searches and never mutates config. Full suite passes with -race, and the tests genuinely encode the new behavior (they fail against main's implementation).

Approving, with a few comments — mostly things I want on the record:

1. Scope is broader than the title suggests. Beyond find_file hints, this makes get_structure, get_diff, project stats, BuildFileGraph/ScanForDeps, the CLI context envelope, hooks, and blast-radius output all apply config only/exclude. I think that's the right behavior, but it's a real change on filtered repos, and it creates a gap: ScanConfiguredFiles/filterConfiguredAnalyses do a hidden config.Load inside the scanner, so --deps/--importers now apply config filters with no way for CLI --only/--exclude to override — at odds with the documented "CLI flags always override config values." A follow-up plumbing filters as parameters (or documenting the exception) would be welcome.
2. Hint wording (mcp/find_guidance.go): the response says "Tell your agent: 'include suggestions for proto…'" — but the reader of that text is the agent, and the quoted phrase doesn't map to a concrete action. Suggest actionable wording like: "To surface these, add "proto" to only in .codemap/config.json".
3. Minor: analyses get filtered twice (ScanForDeps and BuildFileGraphFromAnalyses), with three config.Load disk reads per graph build — worth consolidating sometime.

None of these block the merge. Thanks for the thorough test coverage — the entrypoint parity test is a nice touch.