fix: align Java LSP navigation tool contracts

[wenyt (wenytang-ms)]

Summary

Align the two experimental Java navigation tools with the capabilities and ranges actually returned by their providers. This fixes misleading tool contracts; it does not introduce a new LSP protocol or claim improved token savings.

Motivation

• JDT's WorkspaceSymbolHandler searches types and conditionally source methods. Method search requires java.symbols.includeSourceMethodDeclarations (off by default); there is no corresponding field-search branch.
• JDTUtils.toLocation(IJavaElement) defaults to NAME_RANGE. Turning that navigation location into readFileInput can return only a declaration name rather than its implementation.
• Java server initialization readiness is not a per-query guarantee of indexing completeness. An empty result must not be presented as proof that a symbol does not exist.
• Slicing workspace-symbol results limits the output sent to the model, not the work already performed by providers.

Changes

• Align manifest descriptions, the Java instruction file and the skill: type-name lookup first; known-container outline or text search for members; never change Java settings implicitly.
• Separate navigation from implementation reads. Symbol lookup returns selectionRange (1-based inclusive navigation lines); document outlines retain full declaration readFileRange values. Resolve an outline only after selecting a candidate, not eagerly for every search result.
• Preserve documentUri and provide absolute file paths only for eligible workspace file locations. Report outlineSupported and unsupportedReason for dependency, virtual, remote and outside-workspace locations. Reject ambiguous multi-root display-name paths.
• Distinguish missing files, permission failures and unavailable file systems. Unexpected failures still propagate. Preserve the existing local-workspace access boundary.
• Replace the misleading indexingInProgress reason with serverNotFullyReady, and explicitly report count/depth truncation.
• Add client-observed initialQueryDurationMs and retryQueryDurationMs alongside total duration, without recording query text, source paths or symbol names.
• Add an isolated contract-test suite and a dedicated npm run test-lsp-tools entry point; also wire the suite into npm test.

Experimental output migration

• findSymbol removes readFileInput and the old top-level startLine, endLine, and formatted range fields. Use selectionRange only for navigation. For implementation reads, use documentUri -> file outline -> selected member's readFileRange.
• Returned file paths are absolute rather than workspace-display-relative. Unsupported outline locations have no file field.
• Empty file outlines now return { symbols: [], reason, message }; expected file-access errors return { error, errorCode, hint }.
• Consumers that classify empty reasons must recognize serverNotFullyReady instead of indexingInProgress.
• Tool descriptions, instructions and skill guidance are updated together. Reader parameters still need adaptation to the actual Native/CLI reader schema.

Validation

• npm run compile passed (TypeScript and webpack).
• npm run tslint passed.
• npm run test-lsp-tools passed: 21 tests on Windows in a VS Code 1.138.0 test host.
• git diff --check passed.

Tests use real VS Code URI, range, filesystem-error and tool-result types while mocking providers, workspace membership, readiness and telemetry. They cover URI/path round trips, multi-root ambiguity, unsupported locations, full member ranges, known and unexpected errors, initialization states, normalization/retry behavior, provider timing fields, and count/depth truncation.

The full Java-project integration suite and live JDT/agent scenarios have not been run for this draft.

Follow-up / not included

• No field-search backend, new query filters, user-setting changes, arbitrary document reader, or rollout change.
• No server-side bounded search or cancellation change. The existing workspace-symbol command can aggregate multiple providers; this PR does not add Java-provider filtering.
• Before rollout, exercise real cold/warm JDT projects and both Native and CLI reader handoffs, including multi-root and dependency source scenarios.
• Evaluate a fixed task set using correct source acquisition, fallback frequency, end-to-end latency and full-chain context cost. Output character counts and call volume alone do not establish token savings.

Keeping this as a draft for review of the experimental contract migration and the remaining integration work.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🔵 Needs a closer look

The breaking experimental contract migration still requires live JDT and Native/CLI reader integration validation.

Pull request overview

Aligns experimental Java navigation tools with actual provider behavior and source-range semantics.

Changes:

• Separates navigation ranges from full declaration read ranges.
• Adds URI/access/error/truncation handling and telemetry.
• Updates contracts, guidance, and isolated tests.

File summaries

File	Description
src/copilot/tools/javaContextTools.ts	Revises navigation contracts and error handling.
package.json	Updates schemas and test scripts.
resources/skills/java-lsp-tools/SKILL.md	Documents revised workflow and fallbacks.
resources/instruments/javaLspContext.instructions.md	Aligns Java navigation guidance.
test/lsp-tools-suite/javaContextTools.test.ts	Adds contract coverage.
test/lsp-tools-suite/index.ts	Adds Mocha suite runner.
test/runLspToolsTests.ts	Adds isolated VS Code test launcher.
test/index.ts	Integrates tests into npm test.
CONTRIBUTING.md	Documents testing and telemetry.

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.