Add "projectOnly" scope to java.search.scope setting to exclude JDK and library references

[angelozerr]

Add "projectOnly" scope to java.search.scope setting to exclude JDK and library references

Summary

The textDocument/references operation currently returns all references including those from the JDK and external libraries, which can result in thousands of irrelevant results. This issue proposes adding a new value to the java.search.scope setting to filter results and return only references from project sources.

Current Behavior

When using textDocument/references on a common JDK class like java.util.Optional, the LSP returns all references including:

• Project source files (relevant)
• JDK internal classes (not relevant for most use cases)
• External libraries (not relevant for most use cases)

Example

Searching for references to java.util.Optional in a small project:

• Total references returned: 1,167
• References in project sources: 4 (0.3%)
• References in JDK/libraries: 1,163 (99.7%)
• Response size: 129 KB

File: jdt://contents/java.net.http/jdk.internal.net.http/Exchange.java (2 references)
File: jdt://contents/java.base/sun.net.www.protocol.https/AbstractDelegateHttpsURLConnection.java (2 references)
File: jdt://contents/java.base/java.lang.invoke/VarHandleBytes.java (4 references)
... (1,160+ more JDK/library files)
File: src/main/java/app/AppConfig.java (4 references) ← ONLY relevant results

Problem

1. Performance: Large response payloads (100+ KB) slow down the operation
2. Noise: 99%+ of results are irrelevant for typical refactoring/analysis tasks
3. Client-side filtering burden: Clients must filter out JDK/library references themselves
4. UX degradation: Users are overwhelmed with thousands of irrelevant results

Proposed Solution

Add a new value to the existing java.search.scope setting to filter references by source type.

Current values

• all - Search in all files (current default behavior)
• main - Search in main source files only (?)

Proposed new value

• projectOnly - Search only in project source files, excluding:
  • JDK classes (jdt://contents/java.base/*, etc.)
  • External library classes (JAR files, Maven/Gradle dependencies)
  • Test files (optional, could be controlled separately)

Implementation

The setting would be applied to the following LSP operations:

• textDocument/references
• textDocument/implementation
• workspace/symbol (potentially)

API Example

{
  "java.search.scope": "projectOnly"
}

When textDocument/references is called with this setting:

• ✅ Include: file:///path/to/project/src/main/java/app/AppConfig.java
• ❌ Exclude: jdt://contents/java.base/java.util/Optional.java
• ❌ Exclude: jdt://contents/external-lib/com.example/SomeClass.java

Use Cases

1. Refactoring

When renaming a method or class, developers only care about references in their own code, not in libraries they cannot modify.

2. Impact Analysis

Understanding the impact of changing an interface requires seeing where it's used in the project, not in the JDK.

3. Code Navigation

Finding usages of a project class should focus on project code, not library internals.

4. AI/LLM Integration

Language models using LSP for code analysis get overwhelmed with irrelevant library references. A focused result set improves:

• Token efficiency (smaller responses)
• Analysis accuracy (less noise)
• Response time (faster processing)

Expected Benefits

Performance

• Response size: 129 KB → ~1-2 KB (99% reduction in the Optional example)
• Result count: 1,167 → 4 (99.7% reduction)
• Processing time: Faster for both server and client

Developer Experience

• Clearer, more actionable results
• Reduced cognitive load
• Better IDE responsiveness

Backwards Compatibility

• Default value remains all (no breaking changes)
• Users opt-in by setting java.search.scope: "projectOnly"

Alternative Approaches Considered

1. Client-side filtering

Problem: Clients still pay the cost of large payloads and must implement filtering logic themselves.

2. Separate setting (e.g., java.search.excludeLibraries)

Problem: More settings to manage. Better to extend the existing java.search.scope.

3. Per-request parameter

Problem: LSP spec doesn't have a standard way to pass search scope per request. Settings are the established pattern.

Related Settings

This proposal builds on the existing java.search.scope setting pattern used in JDT.LS and aligns with similar functionality in other language servers.

Benchmark Comparison

Based on real-world testing with java.util.Optional references:

Metric	Current (all)	Proposed (projectOnly)	Improvement
Result count	1,167	4	99.7% reduction
Response size	129 KB	~1.5 KB	98.8% reduction
Relevant results	0.3%	100%	Signal-to-noise

Conclusion

Adding a projectOnly value to java.search.scope would significantly improve the developer experience for common operations like textDocument/references by reducing noise, improving performance, and providing more actionable results.

This enhancement would be particularly valuable for:

• Refactoring workflows
• AI-powered code analysis tools
• Large codebases where filtering is critical

---

Would you like me to submit a PR for this enhancement?