fix(retrieve): preserve helper source when file evidence wins

[mohanagy]

When stronger matches elsewhere in a file win snippet selection, a selected helper can lose its implementation even though its declared source fits the excerpt limit. Preserve scored symbol evidence or a real bounded source fragment when the scored list is empty, then admit file context while keeping that fragment intact. Existing selection order, source attribution and excerpt limits remain.

Validation on the current head: 110 focused tests, six unchanged consumer reproductions, typecheck, build and a zero-vulnerability audit pass. The complete product diff is byte-identical to the previously reviewed source-preservation fix; the branch also includes the merged fast-uri dependency repair from next.

The prior exposed 72-case comparison improved raw helper-source retention from 57/108 to 108/108 and compact retention from 54/108 to 102/108, without selected-ID/order or frozen-fact regressions. That comparison has not been repeated as a fresh holdout. Compact allocation, owner-input completeness and discovery limitations remain. Refs #740.

Summary by CodeRabbit

• Bug Fixes

  • Improved evidence snippets for symbol-level results so they preserve representative source excerpts when file-level context is included.
  • Maintained relevant line numbers, ordering, scope information, and snippet size limits.
  • Existing file-level result behavior remains unchanged.

• Tests

  • Added coverage for multiline implementations, helper symbols, long matching content, split-file excerpts, and workflow matches.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 975fe8f9-a25a-4481-b287-530453bd7188

📥 Commits

Reviewing files that changed from the base of the PR and between 1e64e75 and ae2d022.

📒 Files selected for processing (2)

• src/runtime/retrieve.ts
• tests/unit/retrieve-source-preservation.test.ts

Included review availability: 0 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

---

📝 Walkthrough

Walkthrough

readQueryEvidenceSnippet now preserves representative symbol evidence when non-file selection expands to source-file scope. New tests cover symbol selection, fallback fragments, ordering, limits, line numbers, scopes, and temporary fixture cleanup.

Changes

Source evidence preservation

Layer / File(s)	Summary
Evidence selection and validation src/runtime/retrieve.ts, tests/unit/retrieve-source-preservation.test.ts	The retrieval logic combines representative symbol-level evidence with non-overlapping file-level evidence within snippet limits. Unit tests cover single-line and multiline symbols, helper placement, split-file excerpts, ordering, scopes, line limits, and cleanup.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to ae2d0

This change preserves selected helper source when file-level evidence is also included, with coverage for the relevant selection and rendering limits. No current merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: preserving helper source when file evidence wins snippet selection.
Description check	✅ Passed	The description explains the behavior change, validation performed, known limitations, related issue, and dependency context. It does not use the template headings or explicitly complete every checkli…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/740-preserve-unscored-symbol-source

---

_{Comment @coderabbitai help to get the list of available commands.}

[mohanagy]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[mohanagy]

Integration complete on ae2d0221b39474077793c54c564ddf2aaa9a1f6e: FINAL-GO-747, actual CodeRabbit review complete, and all six first-attempt CI jobs pass. Exact candidate/checkout trees match. Full validation and remaining product limits. Ready for the separate exact-head merge decision.

[mohanagy]

Merged as 214f70bf4c4edf820a0c7651ccd81dba3ca7ac1e with exact approved-tree equality. All six first-attempt post-merge CI jobs passed. Completion and remaining scope.