openidea/java/java-usages/CONFIGURATION.md

# Spring configuration navigation

`openidea.java.configuration` bridges YAML / properties to the existing JDT LS
Java model. It is bundled with the Java usages extension; it does not install a
second language server, run a build, change the application's dependencies, or
connect to external configuration services.

## Editor behavior

- **Go to Definition** on a YAML / properties key opens binding members and
  literal consumers in Java. Multiple matches use the existing location chooser.
- **Go to Definition** inside a Java `@Value` placeholder or a constant
  `Environment.getProperty` / `getRequiredProperty` argument opens matching
  configuration keys. Ordinary Java definition navigation remains native.
- **Find Usages** joins configuration declarations, property consumers, and Java
  references to associated binding members. Java's existing reference results and
  read/write classifications are retained.
- Open editor contents take precedence over disk. All matching profiles/documents
  are shown; navigation does not claim to know the runtime effective value.
- Missing or older extension bundles preserve native language-server behavior.
  YAML aliases still use the YAML server's anchor navigation.

## Association sources

The Java command resolves annotation and method identities with JDT bindings:

- `@ConfigurationProperties` on classes and factory methods, including inherited
  members, nested objects, records, constructor-only parameters / `@Name`, arrays,
  collections and maps. Binder keys use relaxed spelling while retaining path
  boundaries. Indexed collection positions and arbitrary map keys use wildcards.
- `@Value("${key:default}")`, including constant annotation values and nested
  default placeholders.
- Literal or compile-time constant keys passed to Spring's `PropertyResolver`
  methods, including through `Environment`. Unrelated methods with the same name
  and non-Spring annotations are excluded.
- Dependency JAR `META-INF/spring-configuration-metadata.json` and
  `additional-spring-configuration-metadata.json`. The closest group, source
  type, and source method locate a member or its owning class. Source attachments
  and JDT class-file/decompiler navigation use the existing virtual-document path.
- The same metadata files in source roots and `src/main/resources`.

YAML key ranges come from the bundled tree-sitter grammar, including nested/flow
mappings, sequences, quoted keys and multiple documents. Properties support
escaped keys, Unicode escapes and logical-line continuations. Ranges crossing
IPC are UTF-16. No new IPC type or frontend provider is required.

## Scope and costs

The command uses the selected JDT project's resolved package roots, including
source dependencies and its dependency JARs. Configuration search includes those
modules, skips nested independent modules and build output, and honors ignore
files for disk discovery. It does not guess a global association from matching
text in unrelated projects.

Trusted projects with a Maven/Gradle/Eclipse build file at the root start Java a
moment after opening, even without a Java editor open. Once JDT reports
ServiceReady and compiler defaults are applied, the app asks the extension to warm
the configuration index (`openidea.java.configuration.warmup`). A low-priority
system job waits for workspace builds, then builds the same snapshot navigation
uses, one Java project at a time: modules with open YAML/properties files first,
then modules with open Java editors. At most 64 modules are queued, each attempt
has a cooperative 30-second budget, repeated readiness does not repeat finished
work, and warming only fills free room within the retention limits below (it never
evicts an index a lookup built). A snapshot outdated while it was being built is
dropped. Untrusted projects do not start Java; anything warming skips keeps
on-demand indexing.

Otherwise indexing is lazy. The first explicit navigation/search builds a compact snapshot;
ordinary typing, code-lens probes, bulk scoped reference analysis, and Java Go to Definition / Ctrl+hover outside a `@Value` or property-lookup argument (checked with the bundled tree-sitter grammar) do not start indexing. At most eight project snapshots are
retained, with a shared 100,000-association retention cap. Records contain property names, element handles and source locations;
ASTs and bindings are discarded after indexing. A lexical prefilter avoids AST
construction for ordinary Java units, but every accepted association is resolved
semantically. Builds hold a per-project lock that a waiting lookup can cancel, so a
background build of one project never delays another, and a lookup in the same
project reuses the result. Warm requests reuse the snapshot. Java model changes (sources on
disk, classpath, archives) invalidate it conservatively, including dependent-type
changes; a fingerprint of working copies with unsaved changes covers edits before
they are saved. Opening or closing an editor, reconciling, building, and non-Java
resource changes (configuration files are parsed by the client; metadata files are
checked by timestamp) keep it. This is **snapshot invalidation**, not a fully
incremental Java semantic index.

In YAML/properties, ⌘/Ctrl-hover underlines the whole key, hyphens and dots
included, and doesn't open the documentation popup. Hover and Go to Definition share
one request per key: a click after the hover reuses its answer. The editor keeps up
to 128 answers / 4,096 locations, drops them on edits, file and project changes,
workspace edits and language-server restarts, and expires them after 30 seconds as a
backstop. Empty answers and errors are not kept, since the import may still be in
progress.

Metadata/JAR timestamps are checked before reuse. The client caches parsed disk
configuration files by modification time and size (at most 100,000 cached keys), overlays open buffers, and
performs bounded discovery/parsing on a blocking worker. It does not continuously
watch or parse an additional copy of the entire workspace.

Bounds: 20,000 Java units, 100,000 associations per snapshot, 2 MiB per candidate
metadata/configuration file (Java source: 2M UTF-16 units), 1,024-character property names, 2,000 configuration files/results, 50,000 filesystem
entries per root, and depth limits on recursive bindings/YAML. Java requests and
references are cancellable. File/association scan limits and unreadable files carry the
existing incomplete-result indicator; unsupported syntax keys are omitted. Navigation before warming finishes can take seconds on a
cold project; classpath import and source download remain owned by JDT LS.

## Deliberate limits

This is Java/Spring property navigation, not full IntelliJ Spring support. It
cannot infer dynamically constructed names, custom configuration APIs/annotations,
remote-only configuration, arbitrary SpEL evaluation, YAML merge/alias expansion,
or custom Spring converters that change the binding shape. Kotlin is not indexed
by this Java bundle. YAML-only quoted-string escape forms that cannot be decoded
safely are skipped. Properties surrogate-pair escapes are not decoded as keys.
A missing source attachment may navigate to the decompiled owning class when JDT
cannot provide an exact member range. Binding members are navigation candidates;
the feature does not validate whether Spring will successfully bind a bean at
runtime or resolve profile/precedence rules.

## Verification

Use the JDT LS distribution / Java version documented in [README](README.md).

```sh
python3 java/java-usages/build.py /path/to/jdtls
python3 java/java-usages/tests/configuration.py /path/to/jdtls
OPENIDEA_CONFIGURATION_STRESS=1 python3 java/java-usages/tests/configuration.py /path/to/jdtls
OPENIDEA_SPRING_BOOT_JAR=/path/to/spring-boot-autoconfigure.jar python3 java/java-usages/tests/configuration.py /path/to/jdtls
cargo test -p ide-language -p ide-lsp
```

The isolated real-server harness covers custom bindings, inheritance, nesting,
collections/maps, records, constructor aliases, factory methods, consumers,
constant keys, negative identity matches, dependency metadata/source locations,
reverse queries, warming (queued once, reused by the first lookup, cancellable), and
unsaved-change/close invalidation. Optional stress fixtures
add 3,000 ordinary units and 100 binding classes; output includes cold/warm/edit
latencies for the JDT command only, excluding server import, UI and configuration-file discovery. The optional actual Spring Boot JAR checks `server.port`,
`spring.datasource.url` and `spring.jackson.date-format` through dependency
metadata. No user's project is compiled or modified by the harness.

Rust tests cover configuration syntax/ranges and the actual manager bridge:
YAML navigation without YAML definition capabilities, Java native fallback,
reference merging, profiles, open-buffer overlays and sibling-module exclusion.
Existing Java usages / read-write integration harnesses remain regression checks.