[Bulk index][Java] Export compiler and JDT workspace snapshots without query fanout

[samchon]

Outcome

Export Java graph shards from the compiler invocation that already type-checks
the project, using the public javac plugin/tree/model APIs after attribution.
Preserve Gradle/Maven incremental state and use a JDT workspace route only when
the resident IDE model is the semantic owner. Do not run clean, query JDT once
per declaration, or type-check the same source a second time for enrichment.

Current master baseline

Current master registers scip-java for Java and Kotlin. For Java it publishes
semantic-index authority with contains and references. The PR #147 Gson
cold cell took 88.653 s, compared with 231.398 s through generic JDT LS
fan-out.

scip-java 0.13.x changed its architecture:

• the project moved to scip-code/scip-java;
• javac/kotlinc plugins emit SCIP directly rather than SemanticDB;
• the supported floor is Java 17 and Gradle 8;
• Scala/Zinc support was removed; and
• the default Gradle/Maven path performs a real build and includes clean.

Its artifact remains a useful navigation fallback, but SCIP has no call role.
Imports/accesses/implementation relationships are producer-specific, and the
order-based overload/constructor discriminator churns when declarations are
inserted or reordered.

Upstream mechanism

The public JDK compiler API is enough for the build-integrated route:

• Plugin
  is loaded by ServiceLoader on the processor path and receives the active
  JavacTask;
• a plugin registers a
  TaskListener
  for parse/enter/analyze/generate/compilation events; and
• Trees
  maps attributed TreePaths to Element, TypeMirror, source positions,
  scopes and declaration trees.

Elements/Types provide direct supertypes, member lookup and override checks.
No private javac AST parser is required for the initial strict provider.
Annotation-processor/generated source handling still needs lifecycle tests.

Decision: two semantic-owner lanes, one protocol

Build lane: javac plugin

Attach a versioned graph plugin to the project's ordinary Java compile tasks.
On ANALYZE completion for a compilation unit, scan its attributed tree once
and write a source shard. At final compilation completion, write the ordered
manifest/commit record only if diagnostics and the build universe satisfy the
configured policy.

Integrate through Gradle/Maven without replacing their task graph:

• Gradle: add the plugin/processor path and -Xplugin: option to each actual
  Java source-set compile task; retain daemon, build cache, configuration cache
  and incremental compilation;
• Maven: attach to the existing compiler execution and target directory; do not
  prepend clean; and
• Bazel/other javac hosts: attach at the toolchain/action boundary only when the
  exact target/action inputs are nameable.

If a task is UP-TO-DATE, load the previously committed shards. Deleted source,
classpath, compiler-option, annotation-processor or generated-source changes
must invalidate the affected manifest even when no plugin invocation occurs.

Resident lane: JDT

When an Eclipse/JDT workspace already owns unsaved/resident source, expose a
narrow bulk snapshot from that workspace and its reconciled compilation units.
It must produce the same graph schema and identities as the javac route and
must freeze one workspace generation. It is a fallback/IDE lane, not a second
pass after javac.

Fact extraction

Walk attributed trees and elements:

• declarations, visibility, nesting, packages/modules, imports/exports;
• MethodInvocationTree and member references to resolved executable elements;
• NewClassTree/constructor elements for instantiation;
• identifiers/member selects plus assignment/update context for reads/writes;
• TypeMirror and tree paths for type references;
• direct class/interface supertypes and Elements.overrides for inheritance and
  overrides;
• annotations with resolved annotation type and annotated target;
• diagnostics from the same compilation task; and
• test facts only through a named JUnit/TestNG enricher with framework
  provenance.

Virtual/interface calls identify the statically selected method. Runtime
implementations remain candidate/unresolved unless final/sealed analysis proves
one exact target.

Identity and universe

Use module/artifact coordinate plus binary owner name, item kind and a canonical
structural signature:

• methods/constructors include erased or fully qualified parameter types,
  generic arity and return/type-parameter context as required;
• fields, record components, enum constants and annotation elements remain
  distinct;
• locals include source file, enclosing stable member and lexical structure;
• anonymous/local classes include a structural owner key that does not change
  on unrelated line insertion; and
• source/bridge/generated elements retain origin and generator/processor
  provenance.

Do not trust scip-java's +N overload ordinal as the final ID. Exact fixtures
must insert/reorder overloads and constructors without renaming unaffected
members.

The universe includes module/source set, Java release/preview flags, classpath
and module path order/content, compiler/JDK version, annotation processors and
options, generated sources, Gradle/Maven target coordinates and relevant build
properties. One multi-module build can have several target universes.

Incremental and correctness behavior

• no-op: validate existing manifest; compiler need not run;
• private body edit: ordinary incremental compile writes only affected source
  shards;
• public ABI edit: build tool/compiler invalidates dependents, and the graph
  records the affected target/source closure;
• annotation processor or classpath change: invalidate generated/consumer
  shards according to the build;
• compiler error: publish diagnostics and either a clearly partial generation
  or retain the prior strict generation according to the common policy—never
  silently combine old and new facts;
• delete/rename: explicit shard deletion; and
• cancellation/crash: no commit.

Cold acceptance is relative to the same build without the graph plugin. Target
overhead is at most 25% plus serialization, with no extra compilation.

Implementation map

1. Implement the common shard and coverage schema from [Bulk index] Replace symbol-by-symbol LSP scans with compiler-owned snapshots #63.
2. Create a separately versioned Java exporter artifact and Gradle/Maven fixture
   integration; do not put a JVM inside the TypeScript package.
3. Add a provider beside the existing scip-java entry and make it preferred
   only after a handshake proves target coverage.
4. Normalize javac/JDT identities through one conformance fixture.
5. Retain scip-java as a compatibility/navigation fallback.
6. Add phase-separated real Gson measurement and lifecycle rows.

Acceptance

• One compile traversal emits declarations, calls, construction,
  accesses, types, direct inheritance, overrides, annotations, diagnostics
  and source evidence.
• No clean, no disabled Gradle daemon/configuration cache, and no second
  compiler pass.
• Multi-module Gradle and Maven fixtures cover main/test source sets,
  JPMS, records, sealed types, overloads, constructors, generics, lambdas,
  anonymous/local classes, annotation processing and generated sources.
• Overload insertion/reorder and multiple constructors keep stable IDs.
• All 15 fact families have explicit coverage/unresolved rows.
• No-op, body/API edit, create/delete/rename, classpath/config/processor
  change, error, cancel, crash and retry are atomic.
• JDT and javac lanes agree on shared source facts and report different
  producer/universe provenance.
• Cold overhead is measured against the native compile; warm no-op and edit
  latency are reported separately.
• scip-java and generic JDT LS remain truthful fallbacks.
• Focused tests, Java experiment, pnpm build, pnpm test, and
  pnpm coverage pass.

Primary references

• javac Plugin API
• TaskListener API
• Trees API
• scip-java
• Gradle Java plugin

[samchon]

Provider recon at graph 71e35af. This issue's premise is stale in two places, and one of its coordination notes now breaks a sibling issue.

scip-java v0.13.0 is a breaking release

sourcegraph/scip-java moved to scip-code/scip-java. Release v0.13.0 (2026-07-02), verbatim:

This is the first release of scip-java under the scip-code organization, with Maven artifacts now published under the org.scip-code group and Docker images at ghcr.io/scip-code/scip-java. The project has been substantially slimmed down and modernized: the CLI is rewritten in Kotlin, the compiler plugins emit SCIP directly without the SemanticDB intermediate step, and the build now targets Java 17+ (with Java 25 supported). Support for Java 8/11, Gradle < 8, Scala indexing, and Zinc has been dropped.

Corrections:

1. SemanticDB is gone from the pipeline entirely. This issue's "Java output is not 'Javac SemanticDB'" framing no longer describes anything — the javac plugin emits SCIP directly. The index-semanticdb subcommand is gone; the CLI is now index, aggregate, snapshot.
2. The "share SemanticDB/SCIP plumbing with Kotlin and Scala" coordination note is obsolete. Scala indexing was dropped (PR #883, merged 2026-05-27, deletes SbtBuildTool.scala, MillBuildTool.scala, ScalaVersion.scala). This breaks [Bulk index][Scala] Consume SemanticDB and TASTy snapshots through BSP #77's assumed dependency — see the correction there; Scala should move to BSP + direct SemanticDB ingestion instead. The shared-plumbing note now holds for Java + Kotlin only.
3. v0.13.1 dropped the Windows launcher (PR #970). Java indexing on Windows is Docker (ghcr.io/scip-code/scip-java) or coursier only.

Also: Java 8/11 and Gradle < 8 are no longer supported; JDK 17+ required (17/21/25), with --add-exports jdk.compiler/com.sun.tools.javac.{model,api,tree,util,code}=ALL-UNNAMED.

scip-java index runs a real build, not an analysis pass

Defaults: Gradle clean compileTestJava compileTestKotlin compileTestKotlinJvm; Maven --batch-mode clean verify -DskipTests. It runs the build — network dependency resolution, annotation processors, codegen — with a compiler plugin attached. This issue's "prepare dependencies without modifying tracked files" must contend with it writing to target//build/.

Build tool matrix: Maven ✅ Java, Gradle ✅ Java, Bazel ✅ Java, Ant ❌, Buck ❌. v0.13.1 fixed "duplicate documents in Bazel index aggregation" — a caution for the Bazel path.

The identity finding (feeds #65)

The overload disambiguator is order-of-appearance, not signature-derived. Per the SemanticDB spec whose grammar scip-java still follows:

Empty string for the definition that appears first. +1 for the definition that appears second. +2 for the definition that appears third.

with the Java-specific ordering:

non-static overloads first, following the same order as they appear in the original source, static overloads secondly, following the same order as they appear in the original source

Consequences:

• Adding an overload above an existing one renumbers every sibling → mass phantom rename/delete/add churn.
• Reordering two overloads swaps their identities, silently, with no textual change to either.
• Flipping a method static ↔ non-static renumbers both partitions.
• Multiple constructors (<init>) get ordinal disambiguators too — an explicit acceptance row on [Bulk index] Introduce overload-safe provider-native symbol identities #65.
• A body-only edit does not renumber, so [Bulk index] Introduce overload-safe provider-native symbol identities #65's literal criterion ("a line insertion or body-only edit keeps every provider-stable ID unchanged") passes while the identity stays fragile in ways that criterion never tests. Recommend adding an overload-insertion/reorder fixture to [Bulk index] Introduce overload-safe provider-native symbol identities #65.

Recommendation: derive a signature hash from SymbolInformation.signature rather than trusting +N. Note the campaign-wide asymmetry — scip-clang's disambiguator is a canonical-type hash (order-independent) while scip-java's is an ordinal; #65 cannot assume "provider-native key = stable" uniformly.

Locals: local <id> is "unique within the underlying document, but they don't have to be unique across multiple documents", and the suffix is "implementation-dependent" → must be paired with Document.relative_path and marked generation-scoped.

Multi-module: SCIP <package> = <manager> <package-name> <version>, so modules stay distinct without name merging. This issue's multi-module acceptance row is satisfied by the format.

What the artifact proves

Java is the strongest SCIP story in the campaign, but still bounded by the schema. SymbolRole has no Call role at all (see the #69 comment), so:

• Proven: contains (descriptor chain), references.
• Partial: imports (Import role + occurrences on import statements — the best-supported edge beyond references); accesses (ReadAccess/WriteAccess exist in the schema — verify the plugin sets them); extends/implements/overrides (is_implementation relationships; Java can be disentangled by target kind Interface vs Class and method vs type — strictly better separable than C++); tests (Test role exists and the Gradle default compiles compileTestJava, so test sources are indexed — verify the plugin sets Test per test source root, since this issue's Gson smoke requires non-zero tests).
• Closest to provable of any language: instantiates — new Foo() yields an occurrence on the constructor symbol with Kind=Constructor. Still an inference from target kind rather than a role, but a semantic inference, not punctuation-guessing, so it survives [Bulk index] Add strict SCIP navigation-skeleton ingestion and enrichment gates #69's bar. Verify with a fixture.
• Not provable: calls, type_ref as such, dispatches, decorates (an annotation use is just a reference to the annotation type — needs enrichment to mark it as decorates and attach the target; annotations are an acceptance row here), exports (only JPMS module-info exports anything).

Required sidecar: extend the javac plugin org.scip-code:scip-javac — do not fork JDT — walking MethodInvocationTree/NewClassTree/MemberSelectTree/AnnotationTree, emitting facts keyed by the same SCIP symbol strings. Cheap relative to C++: it rides the compile that is already happening.

Incremental

Cold-only at milestone 1, as this issue already states. Per-source shards exist but shard production is not dependency invalidation; any classpath/compiler-option/AP/module change forces full. Gradle's own incremental compile could in principle be leveraged (the plugin rides javac), but the clean in both default commands explicitly defeats it — worth overriding via scip-java index -- <custom> at milestone 2.

Full recon: .wiki/bulk-index-providers/recon-c-cpp-java.md.