trace tool: CLI integration and legacy method deprecation

[HumanBean17]

Summary

Once the trace MCP tool is proven in production, reuse its engine to add a java-codebase-rag trace CLI command and deprecate the legacy find_callers/find_callees methods in kuzu_queries.py.

Background

find_callers and find_callees in kuzu_queries.py already implement multi-hop BFS with depth, confidence filtering, and module/microservice scoping. They serve the CLI (java-codebase-rag commands), not the MCP surface. The new trace engine (from PR #234) is strictly more capable: it adds role-based pruning, fan-out throttling, trivial chain collapsing, cross-service seamless traversal, and structured path output.

Plan

Phase 1: Add trace CLI command

Add a java-codebase-rag trace subcommand that reuses the mcp_trace.py engine:

java-codebase-rag trace --from <fqn-or-id> --direction out --edge-types CALLS --max-depth 3

Output: text/JSON rendering of TraceOutput (same structure as MCP tool result).

This gives CLI users the same pruning and path-structuring benefits that MCP users get.

Phase 2: Deprecate find_callers/find_callees

• Mark KuzuGraph.find_callers and KuzuGraph.find_callees as deprecated with a warnings.warn(DeprecationWarning).
• Update any CLI subcommands that use them to use the new trace engine instead.
• Update docs/JAVA-CODEBASE-RAG-CLI.md to recommend trace over the legacy commands.

Phase 3: Remove legacy methods

• Remove find_callers and find_callees from kuzu_queries.py.
• Remove the CallEdge dataclass if no longer needed.
• Clean up any tests that test only the legacy path.

Acceptance criteria

• java-codebase-rag trace command works with all pruning parameters
• Existing CLI functionality that relied on find_callers/find_callees is preserved via the trace engine
• find_callers/find_callees emit DeprecationWarning before removal
• Tests pass with the new engine for CLI use cases

Dependencies

• Requires trace MCP tool v1 to be shipped (PR propose: trace tool — multi-hop navigation shortcut #234)
• Requires mcp_trace.py to have a clean public API reusable by CLI

[HumanBean17]

Additional consideration from second review (PR #234)

Cross-service hops consume max_depth slots in CLI too

The CLI trace command will have the same scaffolding edge behavior as the MCP tool: internal edges like DECLARES_CLIENT, EXPOSES consume hop slots. CLI users need clear output when max_depth is exhausted mid-cross-service traversal.

Consider: when the CLI command detects a cross-service boundary was reached but max_depth ran out, print a suggestion like:

Note: cross-service boundary detected at depth 4/4. Downstream route found but handler not resolved. Re-run with --max-depth 5 or use 'java-codebase-rag neighbors' on the discovered Route.

This should be implemented in Phase 1 alongside the CLI command itself, not deferred.