[sundaysebasidian-byte]

Summary

Closes #44.

callers currently exits successfully with "No callers found" for an unindexed file, an ambiguous path or a missing symbol, making those errors indistinguishable from a found symbol with zero callers. Share the existing MCP file resolver in QueryEngine and reuse it in callers, context, impact and summary. Lookup errors now go to stderr with exit 1; ambiguous paths include sorted candidate paths and the existing longer-path hint. A found symbol with zero callers still succeeds, and the MCP error response contract remains unchanged.

Update the documented CLI behavior and changelog. Add 21 cases using real temporary Python indexes and SQLite storage, covering missing/ambiguous input, missing symbols, zero callers, actual callers, project-relative resolution from a different working directory, and the shared MCP response contract.

Type of change

• Bug fix
• New feature or improvement
• Performance
• Documentation only
• Refactor, tests or tooling (no behaviour change)

How was it tested?

Checks ran on macOS with the existing Python 3.14.6 development environment, against main 6ee2ff6251af85f32dce90320b5ed956b98b1fa3:

• Upstream full-suite baseline: 764 passed, 1 skipped.
• Run the new CLI regression cases on the old implementation: 11 failed, 6 passed, 4 shared-resolver API cases deselected. Those failures reproduce misleading error handling; the new API cases are excluded from the before-fix result.
• Focused CLI/MCP/query compatibility suites: 173 passed, 1 skipped.
• python -m pytest tests/ -q --cov=codeprism --cov-report=term-missing --cov-fail-under=80 --tb=short: 785 passed, 1 skipped; total coverage 89.18%.
• ruff check codeprism/ tests/ and ruff format --check codeprism/ tests/: passed.
• Touched-file mypy checks with --follow-imports=silent retain the same 34 pre-existing upstream diagnostics after normalizing line offsets; no new diagnostics, including in the new test file.
• Independent review read the complete diff and issue requirements, reran all 21 new cases successfully, and compared the mypy diagnostic multisets with upstream. No blocking findings remained.

Checklist

• Tests added or updated for all changed behaviour.
• ruff check and ruff format --check pass.
• No new mypy errors in the files changed.
• All existing tests pass (one existing skip).
• Docstrings added or updated for public functions.
• docs/changelog.md updated.
• README updated for the changed CLI behavior.
• Commit follows Conventional Commits.

Notes for reviewers

AI assistance: implementation, tests and documentation were prepared with Codex and independently reviewed by a separate Codex agent. No dependencies were added or installed. Python 3.12/3.13 and Windows were not run locally; assess those separately from CI or platform testing. Mypy is not fully green upstream; the check above verifies that this change does not add diagnostics in touched files.

[knight22-21]

LGTM! Excellent work sharing the file resolver between CLI and MCP, properly surfacing query lookup errors with candidate hints.

[knight22-21]

Merged, thank you @sundaysebasidian-byte! This properly distinguishes query lookup errors from true zero-caller results and aligns the CLI experience with the MCP server.