feat(java): add a read-only Neo4j analysis backend (parity with Python/TypeScript)

Adds cldk.analysis.java.neo4j.JNeo4jBackend, a read-only Cypher client that
reconstructs the canonical JApplication from the graph codeanalyzer-java (>=2.4.0)
emits with --emit neo4j, then answers all 36 JavaAnalysisBackend queries with the
in-memory backend's logic. Selected by passing a Neo4jConnectionConfig as the
backend= config to CLDK.java()/JavaAnalysis (JavaBackend union extended).

Verified 1-to-1 against JCodeanalyzer on the daytrader8 sample: everything the
graph contains reconstructs identically. Three producer-side gaps in the 2.4.0
emitter are tracked upstream (codeanalyzer-java#156/#157/#158), not query bugs.

- backend_config: JavaBackend = Union[CodeAnalyzerConfig, Neo4jConnectionConfig]
- java_analysis/core: select JNeo4jBackend by config type; allow project_path=None
- bump codeanalyzer-java pin to 2.4.0 (adds the Neo4j emitter)
- tests: selection + ABC contract (run anywhere) + skip-by-default daytrader parity
- README: mermaid + backends table show Java's read-only Neo4j backend

Closes #167

Author: rahlk

CHANGELOG.md

@@ -63,7 +63,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   where calls to a bare module name that is also imported (e.g. `os`/`re`/`json`) are dropped from
   the emitted call graph. `PythonAnalysis` / `CLDK.analysis(language="python")` accept the same
   optional `neo4j_config`.
-- Bumped `codeanalyzer-python` to `0.2.0` (adds the Neo4j graph emitter).
+- Read-only Neo4j-backed **Java** analysis backend (`cldk.analysis.java.neo4j.JNeo4jBackend`),
+  completing Neo4j parity across all three languages. It reconstructs the canonical `JApplication`
+  from the graph `codeanalyzer-java` (>= 2.4.0) emits with `--emit neo4j` and answers all 36
+  `JavaAnalysisBackend` queries with the in-memory backend's logic. Verified against the daytrader8
+  sample (145 classes): everything the graph actually contains reconstructs identically to
+  `JCodeanalyzer`. Three producer-side gaps in the 2.4.0 emitter make the graph an incomplete
+  projection (tracked upstream, not query-layer bugs): all fields of a class collapse to one node
+  (codeanalyzer-java#156), imports lose the type name (codeanalyzer-java#157), and `J_CALLS`
+  materializes only a fraction of the call graph (codeanalyzer-java#158). `JavaAnalysis` /
+  `CLDK.java(...)` accept a `Neo4jConnectionConfig` as the `backend=` config to select it.
+- Bumped `codeanalyzer-python` to `0.2.0` (adds the Neo4j graph emitter); bumped `codeanalyzer-java`
+  to `2.4.0` (adds the Neo4j graph emitter).
 - Optional `neo4j` extra (`pip install cldk[neo4j]`) for the Neo4j Python driver.
 
 ## [v1.0.7] - 2026-02-14

README.md

@@ -99,9 +99,8 @@ class Neo4jConnectionConfig:
     application_name: str | None = None
 
 
-# Per-language discriminated unions the facades match on. Java has no Neo4j backend yet, so its
-# only admissible config is the codeanalyzer one.
-JavaBackend = CodeAnalyzerConfig
+# Per-language discriminated unions the facades match on.
+JavaBackend = Union[CodeAnalyzerConfig, Neo4jConnectionConfig]
 PyBackend = Union[PyCodeAnalyzerConfig, Neo4jConnectionConfig]
 TSBackend = Union[CodeAnalyzerConfig, Neo4jConnectionConfig]
 

cldk/analysis/commons/backend_config.py

@@ -52,12 +52,13 @@
 
 from tree_sitter import Tree
 
-from cldk.analysis.commons.backend_config import CodeAnalyzerConfig, JavaBackend, cache_subdir
+from cldk.analysis.commons.backend_config import CodeAnalyzerConfig, JavaBackend, Neo4jConnectionConfig, cache_subdir
 from cldk.analysis.commons.treesitter import TreesitterJava
 from cldk.models.java import JCallable
 from cldk.models.java import JApplication
 from cldk.models.java.models import JCRUDOperation, JComment, JCompilationUnit, JMethodDetail, JType, JField
 from cldk.analysis.java.codeanalyzer import JCodeanalyzer
+from cldk.analysis.java.neo4j import JNeo4jBackend
 from cldk.analysis.java.backend import JavaAnalysisBackend
 
 
@@ -149,22 +150,33 @@ def __init__(
         self.eager_analysis = eager_analysis
         self.target_files = target_files
         self.backend_config: JavaBackend = backend if backend is not None else CodeAnalyzerConfig()
-        # Java has a single backend family; the config only carries the cache root. analysis.json
-        # is cached under <cache_dir>/java (None in source_code mode, where the analyzer streams
-        # results over a pipe).
-        cache_path = cache_subdir(self.backend_config.cache_dir, project_dir, "java")
-        if cache_path is not None:
-            cache_path.mkdir(parents=True, exist_ok=True)
         self.treesitter_java: TreesitterJava = TreesitterJava()
-        # Initialize the analysis backend
-        self.backend: JavaAnalysisBackend = JCodeanalyzer(
-            project_dir=self.project_dir,
-            source_code=self.source_code,
-            eager_analysis=self.eager_analysis,
-            analysis_level=self.analysis_level,
-            analysis_json_path=cache_path,
-            target_files=self.target_files,
-        )
+        self.backend: JavaAnalysisBackend
+        if isinstance(self.backend_config, Neo4jConnectionConfig):
+            # Read-only: the graph is populated out of band; the SDK only polls it.
+            cfg = self.backend_config
+            application_name = cfg.application_name or (Path(project_dir).name if project_dir else None)
+            self.backend = JNeo4jBackend(
+                neo4j_uri=cfg.uri,
+                neo4j_username=cfg.username,
+                neo4j_password=cfg.password,
+                neo4j_database=cfg.database,
+                application_name=application_name,
+            )
+        else:
+            # The config only carries the cache root. analysis.json is cached under <cache_dir>/java
+            # (None in source_code mode, where the analyzer streams results over a pipe).
+            cache_path = cache_subdir(self.backend_config.cache_dir, project_dir, "java")
+            if cache_path is not None:
+                cache_path.mkdir(parents=True, exist_ok=True)
+            self.backend = JCodeanalyzer(
+                project_dir=self.project_dir,
+                source_code=self.source_code,
+                eager_analysis=self.eager_analysis,
+                analysis_level=self.analysis_level,
+                analysis_json_path=cache_path,
+                target_files=self.target_files,
+            )
 
     def get_imports(self) -> List[str]:
         """Return all import statements in the source code.

cldk/analysis/java/java_analysis.py

@@ -0,0 +1,22 @@
+################################################################################
+# Copyright IBM Corporation 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+################################################################################
+
+"""Read-only Neo4j-backed Java analysis backend (Cypher queries over the codeanalyzer-java graph)."""
+
+from cldk.analysis.java.neo4j.config import Neo4jConnectionConfig
+from cldk.analysis.java.neo4j.neo4j_backend import JNeo4jBackend
+
+__all__ = ["JNeo4jBackend", "Neo4jConnectionConfig"]

cldk/analysis/java/neo4j/__init__.py

@@ -0,0 +1,27 @@
+################################################################################
+# Copyright IBM Corporation 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+################################################################################
+
+"""Connection settings for the read-only Neo4j-backed Java analysis backend.
+
+The definition has been hoisted to :mod:`cldk.analysis.commons.backend_config`; it is re-exported
+here for symmetry with the Python and TypeScript backends.
+"""
+
+from __future__ import annotations
+
+from cldk.analysis.commons.backend_config import Neo4jConnectionConfig
+
+__all__ = ["Neo4jConnectionConfig"]