Repository navigation
fix(find): honest description, body-text scoring tagged (body) - #293
Merged
Merged
Conversation
`codemap find` is BM25 over path and function/type name tokens. The MCP tool, CLI help, README and skills presented it as a way to locate the code a bug report describes, which it does poorly. Descriptions now say it ranks by path and symbol names, is good for "where is X defined", also scores file contents, and that free-text symptoms still need a body grep. Run now always scans the indexed source files under 1 MB for the query tokens, scores each file containing at least two distinct query tokens (one for a one-word query) by the idf of those tokens, and adds that to the name score. A file matching in names and body outranks a body-only file; hits that matched only in a body are tagged "matched: (body)". Rank (names only) is unchanged. Measured on shallow clones, rank of the fix file and warm wall time of `codemap find --limit 1000 --json`, before (034d16c) -> after: - werkzeug 05ff3fe, "rule match converter values wrong parameter order many converters segment", src/werkzeug/routing/matcher.py: rank 9 -> 5, 0.18 s -> 0.20 s - yt-dlp f9eee6b, "redirect Location header relative dot segments urllib", yt_dlp/networking/_urllib.py: rank 4 -> 6, 0.99 s -> 1.17 s (body-only yt_dlp/utils/_utils.py enters at 3) Closes #286 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8AjoCA1yjN3T59vk46
There was a problem hiding this comment.
🟡 Changes recommended
Active documentation inconsistencies and a cancellation-handling bug remain, including ignored body-scan cancellation and stale successful results.
7 open issues
What changed in this PR
This pull request extends codemap find with body-text scoring while clarifying that name and path matching remain its primary purpose. Body-only matches are tagged (body), and related CLI, MCP, README, and skill documentation is updated.
Changes:
- Added body-text scoring, ranking integration, size limits, and cancellation handling.
- Added regression coverage for body-only and combined name/body matches.
- Updated user-facing search descriptions and generated skill documentation.
| File | Summary |
|---|---|
skills/builtin/explore.md |
Updates exploration guidance; the find description still needs to mention body scoring and (body) results. |
skills/builtin/codemap.md |
Documents the revised find behavior; body scoring and tagging should be stated explicitly. |
README.md |
Revises user-facing descriptions and command reference; both find descriptions need body-scoring details. |
plugins/codemap/skills/explore/SKILL.md |
Updates plugin exploration guidance; the find description is inconsistent with body-text fallback behavior. |
plugins/codemap/skills/codemap/SKILL.md |
Updates plugin command guidance; body scoring and (body) tagging remain undocumented. |
mcp/main.go |
Updates the MCP tool description; the status inventory still omits body scoring and tagging. |
main.go |
Updates top-level CLI help text. |
find/find.go |
Implements body scoring and ranking, but cancellation errors are not propagated and the scan lacks an aggregate budget for large repositories. |
find/find_test.go |
Adds coverage for body-only fallback and name-plus-body ranking. |
find_cmd.go |
Updates detailed CLI help for body scoring and symptom searches. |
.claude/skills/explore/SKILL.md |
Updates Claude exploration guidance; the find description is inconsistent with body-text fallback behavior. |
.claude/skills/codemap/SKILL.md |
Updates Claude command guidance; body scoring and (body) tagging remain undocumented. |
This pull request requires changes.
Review effort: Lite
bodyHits returned nil when the context was cancelled mid-walk, so Run treated it as "no body matches", ignored the graph error that followed, and returned partial hits as success. bodyHits now returns ctx.Err() and Run propagates it. README, the package comment, the CLI usage line and the explore/codemap skills now say find ranks by names first, then body text, and that body-only hits are tagged "(body)". Skill copies regenerated with go generate ./skills. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8AjoCA1yjN3T59vk46
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #286.
codemap findis BM25 over path and identifier tokens. It is a good symbol finder and a poor bug-report-to-file locator, but the MCP description and skill text presented it as the latter.--help, README,skills/builtin/{codemap,explore}.md, regenerated host copies): ranks files by path and function/type names; good for "where is X defined"; also scores file contents, body-only hits are tagged(body); for a free-text symptom grep the body text too.find/find.go: body scoring always on, over the files the scanner already indexed (ignore rules apply), files > 1 MB skipped, cancellation honoured. A file needs 2+ distinct query words in its body to score (1 for a one-word query); name matches keep their BM25 score so name+body outranks body-only.TestRunFallsBackToBodyText.Measured on real clones (median of 3 warm runs,
--limit 1000 --json):routing/matcher.pynetworking/_urllib.pyA wash on two samples; weights were deliberately not tuned to them. The honest description is the real fix; body scoring stays because it is cheap and stops
findfrom being blind to body text.go test ./find/ ./cmd/ ./mcp/ ./skills/,gofmt -lclean.🤖 Generated with Claude Code
https://claude.ai/code/session_01FWQw8AjoCA1yjN3T59vk46