Skip to content

Commit 5ebafaf

Browse files
rahlkrahlk
committed
refactor(core): reshape facade into per-language factories + typed backend configs
Fixes #164. Replace the stringly-typed `CLDK(language).analysis(...)` front end with per-language factory methods (`CLDK.java/.python/.typescript/.c`) that each expose only the options that apply, and select the backend by the *type* of a `backend=` configuration object instead of `neo4j_config` truthiness. - Add `cldk/analysis/commons/backend_config.py`: `CodeAnalyzerConfig` (cache_dir only), `PyCodeAnalyzerConfig` (use_codeql/use_ray), hoisted `Neo4jConnectionConfig`, the per-language `*Backend` unions, and a `cache_subdir()` helper. The two old `Neo4jConnectionConfig` modules re-export from here for backward compatibility. - Facades dispatch on the config type (CodeAnalyzerConfig vs Neo4jConnectionConfig). - Unify on-disk persistence into a single language-keyed `cache_dir` (`<cache_dir>/<language>/analysis.json`, default `<project>/.codeanalyzer`); caching is on by default for Java/TypeScript. - Remove `analysis_json_path` (folded into cache_dir) and `analysis_backend_path` (binary ships with the packaged dependency; `$CODEANALYZER_TS_BIN` kept for TS) from the public interface. - Deprecate Java `source_code` input and the `CLDK(language).analysis(...)` entry point; the latter is retained as a forwarding shim that emits a DeprecationWarning. - Update tests for the new API and cache-on-by-default disk semantics; document the change (Added/Changed/Deprecated/Removed/Migration) in the changelog.
1 parent e22538b commit 5ebafaf

33 files changed

Lines changed: 1794 additions & 836 deletions

‎CHANGELOG.md‎

Lines changed: 50 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88
## [Unreleased]
99

1010
### Added
11-
- Neo4j-backed TypeScript analysis backend (`cldk.analysis.typescript.neo4j.TSNeo4jBackend`). It
12-
is a drop-in alternative to the in-memory `TSCodeanalyzer`: it answers the **same** `get_*`
11+
- **Per-language factory methods on `CLDK`** — `CLDK.java()`, `CLDK.python()`, `CLDK.typescript()`,
12+
and `CLDK.c()` — each with an honest signature exposing only the options that apply to that
13+
language. These are the preferred entry points, replacing the stringly-typed
14+
`CLDK(language).analysis(...)`.
15+
- **Typed backend-configuration objects** in `cldk.analysis.commons.backend_config`. The backend is
16+
now selected by the *type* of the `backend=` config passed to a factory: `CodeAnalyzerConfig`
17+
(default; in-process analyzer) / `PyCodeAnalyzerConfig` (adds `use_codeql`, `use_ray`), or
18+
`Neo4jConnectionConfig` (read-only Neo4j). `Neo4jConnectionConfig` is hoisted here and re-exported
19+
from `cldk.analysis.{python,typescript}.neo4j` for backward compatibility.
20+
- **Unified, language-keyed cache directory.** All backends now share a single `cache_dir`
21+
(default `<project>/.codeanalyzer`) and write their artifacts under a per-language subdirectory
22+
(`<cache_dir>/java`, `<cache_dir>/python`, `<cache_dir>/typescript`), so a polyglot project
23+
analyzed under more than one language no longer overwrites a shared `analysis.json`.
24+
25+
### Changed
26+
- **Caching is on by default for Java/TypeScript.** The in-process backend now caches `analysis.json`
27+
to disk (under the language-keyed `cache_dir`) instead of streaming over a stdout pipe.
28+
- `CLDK(language).analysis(...)` is **deprecated** and retained as a thin compatibility shim that
29+
forwards to the new factory methods (emits a `DeprecationWarning`).
30+
31+
### Deprecated
32+
- Java `source_code` (single-file) input — pass `project_path` instead.
33+
34+
### Removed
35+
- `analysis_backend_path` from the public interface. The backend binary ships with the packaged
36+
`codeanalyzer-*` dependency; for TypeScript, `$CODEANALYZER_TS_BIN` remains as the only
37+
out-of-band override.
38+
- `analysis_json_path` from the public interface — folded into the unified `cache_dir`.
39+
40+
### Migration
41+
- The language-keyed cache relocates `analysis.json` from `<cache_dir>/analysis.json` to
42+
`<cache_dir>/<language>/analysis.json`; existing caches are not found at the new path, so the
43+
first run after upgrading recomputes the analysis.
44+
45+
### Added (Neo4j)
46+
- Read-only Neo4j-backed TypeScript analysis backend (`cldk.analysis.typescript.neo4j.TSNeo4jBackend`).
47+
It is a drop-in alternative to the in-memory `TSCodeanalyzer`: it answers the **same** `get_*`
1348
query surface (call graph, callers/callees, class hierarchy, call sites, decorators, symbol
1449
lookups, ...) by running **Cypher over a live Neo4j graph** instead of walking the pydantic /
1550
NetworkX structures. The graph is the one `codeanalyzer-typescript` emits with `--emit neo4j`
16-
(schema `schema.neo4j.json`); the backend can populate the database for you over Bolt, or query
17-
one that is already loaded.
51+
(schema `schema.neo4j.json`); it is always populated out of band, and the SDK only polls it
52+
(read-only — never writes, needs no binary or project sources).
1853
- `TypeScriptAnalysis` / `CLDK.analysis(language="typescript")` now accept an optional
1954
`neo4j_config` (`Neo4jConnectionConfig`) to select the Neo4j backend; without it the in-memory
2055
backend is used, unchanged.
56+
- Read-only Neo4j-backed **Python** analysis backend (`cldk.analysis.python.neo4j.PyNeo4jBackend`),
57+
the analog of the TypeScript one. It answers all 21 `PythonAnalysisBackend` queries via Cypher
58+
over the graph `codeanalyzer-python` (>= 0.2.0) emits with `--emit neo4j`. Verified against a real
59+
57-module project: every node/edge **present in the graph** reconstructs identically to the
60+
in-memory `PyCodeanalyzer` (3169/3200 checks; zero weight/provenance mismatches on shared call
61+
edges). Known gaps are not in the query layer: projection-lossy fields (comments → docstring,
62+
`PyVariableDeclaration.value`/columns, per-binding import detail), and an **upstream emitter bug**
63+
where calls to a bare module name that is also imported (e.g. `os`/`re`/`json`) are dropped from
64+
the emitted call graph. `PythonAnalysis` / `CLDK.analysis(language="python")` accept the same
65+
optional `neo4j_config`.
66+
- Bumped `codeanalyzer-python` to `0.2.0` (adds the Neo4j graph emitter).
2167
- Optional `neo4j` extra (`pip install cldk[neo4j]`) for the Neo4j Python driver.
2268

2369
## [v1.0.7] - 2026-02-14

‎cldk/analysis/commons/backend_config.py‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
################################################################################
2+
# Copyright IBM Corporation 2026
3+
#
4+
# Licensed under the Apache License, Version 2.0 (the "License");
5+
# you may not use this file except in compliance with the License.
6+
# You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
################################################################################
16+
17+
"""Backend configuration objects for the CLDK analysis facades.
18+
19+
The CLDK front end selects analysis behavior along two orthogonal axes: the *language* (chosen by
20+
which :class:`~cldk.core.CLDK` factory method is called) and the *backend* (chosen by the **type**
21+
of the configuration object passed as ``backend=``). The dataclasses here are those configuration
22+
objects -- Parameter Objects that the facades ingest and dispatch on.
23+
24+
Two backend families exist:
25+
26+
* :class:`CodeAnalyzerConfig` (and its language-specific subclasses) selects the in-process
27+
codeanalyzer backend, which runs the packaged ``codeanalyzer-*`` binary and caches its
28+
``analysis.json`` under a language-keyed cache directory.
29+
* :class:`Neo4jConnectionConfig` selects the read-only Neo4j/Cypher backend, which answers the
30+
same queries over a graph populated out of band.
31+
32+
The per-language ``*Backend`` unions below are the discriminated unions the facades match on.
33+
"""
34+
35+
from __future__ import annotations
36+
37+
from dataclasses import dataclass
38+
from pathlib import Path
39+
from typing import Union
40+
41+
# The canonical sub-directory name each language's artifacts live under inside the shared cache
42+
# root. Keyed so that a polyglot repository analyzed under more than one language does not have its
43+
# backends overwrite a single shared ``analysis.json``.
44+
_CACHE_KEYS = {"java": "java", "python": "python", "typescript": "typescript", "c": "c"}
45+
46+
47+
@dataclass
48+
class CodeAnalyzerConfig:
49+
"""Select the in-process codeanalyzer backend.
50+
51+
The backend binary is sourced from the packaged ``codeanalyzer-*`` dependency, so the only
52+
knob is where analysis artifacts are cached.
53+
54+
Attributes:
55+
cache_dir: Root directory for analysis artifacts. When ``None`` the facade defaults it to
56+
``<project>/.codeanalyzer``. Each backend writes under a language-keyed subdirectory of
57+
this root (see :func:`cache_subdir`), so the same root can be shared across languages.
58+
"""
59+
60+
cache_dir: Union[str, Path, None] = None
61+
62+
63+
@dataclass
64+
class PyCodeAnalyzerConfig(CodeAnalyzerConfig):
65+
"""Select the in-process codeanalyzer backend for Python.
66+
67+
Adds the Python-only call-graph knobs on top of :class:`CodeAnalyzerConfig`.
68+
69+
Attributes:
70+
use_codeql: If ``True`` (default), augment Jedi-based call-graph resolution with CodeQL.
71+
use_ray: If ``True``, enable Ray-based parallel processing for large projects.
72+
"""
73+
74+
use_codeql: bool = True
75+
use_ray: bool = False
76+
77+
78+
@dataclass
79+
class Neo4jConnectionConfig:
80+
"""Select the read-only Neo4j-backed analysis backend.
81+
82+
The graph is always populated out of band (e.g. a job that runs ``codeanalyzer-* --emit
83+
neo4j``); the SDK only polls it. This config carries the connection details and which
84+
application to scope queries to.
85+
86+
Attributes:
87+
uri: Bolt URI of the Neo4j server (e.g. ``bolt://localhost:7687``).
88+
username: Neo4j username (read-only credentials are sufficient).
89+
password: Neo4j password.
90+
database: Database name (``None`` => server default).
91+
application_name: The application anchor name to scope queries to. Matches the
92+
``--app-name`` the graph was loaded with (defaults to the project directory name).
93+
"""
94+
95+
uri: str
96+
username: str = "neo4j"
97+
password: str = "neo4j"
98+
database: str | None = None
99+
application_name: str | None = None
100+
101+
102+
# Per-language discriminated unions the facades match on. Java has no Neo4j backend yet, so its
103+
# only admissible config is the codeanalyzer one.
104+
JavaBackend = CodeAnalyzerConfig
105+
PyBackend = Union[PyCodeAnalyzerConfig, Neo4jConnectionConfig]
106+
TSBackend = Union[CodeAnalyzerConfig, Neo4jConnectionConfig]
107+
108+
109+
def cache_subdir(cache_dir: Union[str, Path, None], project_dir: Union[str, Path, None], language: str) -> Path | None:
110+
"""Resolve the language-keyed cache directory for a backend.
111+
112+
Args:
113+
cache_dir: The cache root from the backend config. When ``None``, defaults to
114+
``<project_dir>/.codeanalyzer``.
115+
project_dir: The project directory, used to derive the default root.
116+
language: The canonical language key (``"java"``, ``"python"``, ``"typescript"``, ``"c"``).
117+
118+
Returns:
119+
``<root>/<language>`` as an absolute path, or ``None`` if no root can be determined
120+
(no ``cache_dir`` and no ``project_dir``).
121+
"""
122+
key = _CACHE_KEYS.get(language, language)
123+
if cache_dir is not None:
124+
root = Path(cache_dir).expanduser().resolve()
125+
elif project_dir is not None:
126+
root = Path(project_dir).expanduser().resolve() / ".codeanalyzer"
127+
else:
128+
return None
129+
return root / key

‎cldk/analysis/java/codeanalyzer/codeanalyzer.py‎

Lines changed: 5 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
import re
1919
import shlex
2020
import subprocess
21-
from importlib import resources
21+
import sys
2222
from itertools import chain, groupby
2323
from pathlib import Path
2424
from subprocess import CompletedProcess
@@ -44,7 +44,6 @@ class JCodeanalyzer(JavaAnalysisBackend):
4444
Args:
4545
project_dir (str or Path): The path to the root of the Java project.
4646
source_code (str, optional): The source code of a single Java file to analyze. Defaults to None.
47-
analysis_backend_path (str or Path, optional): The path to the analysis backend. Defaults to None.
4847
analysis_json_path (str or Path, optional): The path to save the intermediate code analysis outputs.
4948
If None, the analysis will be read from the pipe.
5049
analysis_level (str): The level of analysis ('symbol_table' or 'call_graph').
@@ -55,15 +54,13 @@ def __init__(
5554
self,
5655
project_dir: Union[str, Path],
5756
source_code: str | None,
58-
analysis_backend_path: Union[str, Path, None],
5957
analysis_json_path: Union[str, Path, None],
6058
analysis_level: str,
6159
eager_analysis: bool,
6260
target_files: List[str] | None,
6361
) -> None:
6462
self.project_dir = project_dir
6563
self.source_code = source_code
66-
self.analysis_backend_path = analysis_backend_path
6764
self.analysis_json_path = analysis_json_path
6865
self.eager_analysis = eager_analysis
6966
self.analysis_level = analysis_level
@@ -89,29 +86,16 @@ def _get_application(self) -> JApplication:
8986
return self.application
9087

9188
def _get_codeanalyzer_exec(self) -> List[str]:
92-
"""Should return the executable command for codeanalyzer.
89+
"""Return the executable command for codeanalyzer-java.
9390
9491
Returns:
9592
List[str]: The executable command for codeanalyzer.
9693
9794
Notes:
98-
- If the analysis_backend_path is provided, the codeanalyzer jar from that path will be used.
99-
- If not provided, the latest codeanalyzer jar from GitHub will be downloaded.
95+
- The JVM-free native binary shipped in the ``codeanalyzer-java`` PyPI package is used,
96+
invoked as ``python -m codeanalyzer_java``.
10097
"""
101-
102-
if self.analysis_backend_path:
103-
analysis_backend_path = Path(self.analysis_backend_path)
104-
logger.info(f"Using codeanalyzer jar from {analysis_backend_path}")
105-
codeanalyzer_jar_file = next(analysis_backend_path.rglob("codeanalyzer-*.jar"), None)
106-
if codeanalyzer_jar_file is None:
107-
raise CodeanalyzerExecutionException("Codeanalyzer jar not found in the provided path.")
108-
codeanalyzer_exec = shlex.split(f"java -jar {codeanalyzer_jar_file}")
109-
else:
110-
# Since the path to codeanalyzer.jar we will use the default jar from the cldk/analysis/java/codeanalyzer/jar folder
111-
with resources.as_file(resources.files("cldk.analysis.java.codeanalyzer.jar")) as codeanalyzer_jar_path:
112-
codeanalyzer_jar_file = next(codeanalyzer_jar_path.rglob("codeanalyzer-*.jar"), None)
113-
codeanalyzer_exec = shlex.split(f"java -jar {codeanalyzer_jar_file}")
114-
return codeanalyzer_exec
98+
return [sys.executable, "-m", "codeanalyzer_java"]
11599

116100
@staticmethod
117101
def _init_japplication(data: str) -> JApplication:

‎cldk/analysis/java/codeanalyzer/jar/.gitignore‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎cldk/analysis/java/codeanalyzer/jar/codeanalyzer-2.3.8.jar‎

-28.7 MB
Binary file not shown.

‎cldk/analysis/java/java_analysis.py‎

Lines changed: 19 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@
5252

5353
from tree_sitter import Tree
5454

55+
from cldk.analysis.commons.backend_config import CodeAnalyzerConfig, JavaBackend, cache_subdir
5556
from cldk.analysis.commons.treesitter import TreesitterJava
5657
from cldk.models.java import JCallable
5758
from cldk.models.java import JApplication
@@ -85,12 +86,11 @@ class JavaAnalysis:
8586
8687
Attributes:
8788
project_dir (str | Path | None): Path to the Java project directory.
88-
source_code (str | None): Java source code string for single-file mode.
89+
source_code (str | None): Java source code string for single-file mode (deprecated).
8990
analysis_level (str): The depth of analysis performed.
90-
analysis_json_path (str | Path | None): Path for persisting analysis results.
91-
analysis_backend_path (str | None): Path to the CodeAnalyzer JAR.
9291
eager_analysis (bool): Whether to force regeneration of analysis.
9392
target_files (List[str] | None): Specific files to analyze.
93+
backend_config (JavaBackend): The backend configuration object.
9494
treesitter_java (TreesitterJava): Tree-sitter parser for Java.
9595
backend (JCodeanalyzer): The underlying analysis backend.
9696
@@ -103,11 +103,10 @@ def __init__(
103103
self,
104104
project_dir: str | Path | None,
105105
source_code: str | None,
106-
analysis_backend_path: str | None,
107-
analysis_json_path: str | Path | None,
108106
analysis_level: str,
109107
target_files: List[str] | None,
110108
eager_analysis: bool,
109+
backend: JavaBackend | None = None,
111110
) -> None:
112111
"""Initialize the Java analysis facade.
113112
@@ -121,14 +120,8 @@ def __init__(
121120
Mutually exclusive with ``source_code``.
122121
source_code: Java source code string for single-file analysis.
123122
Useful for quick syntactic analysis without a project structure.
124-
Mutually exclusive with ``project_dir``.
125-
analysis_backend_path: Path to the directory containing the
126-
``codeanalyzer-*.jar`` backend. If not provided, the JAR is
127-
automatically downloaded from the latest release. Only used
128-
in project mode.
129-
analysis_json_path: Path where the analysis database
130-
(``analysis.json``) should be persisted. If ``None``, analysis
131-
results are computed on-demand and not cached to disk.
123+
Mutually exclusive with ``project_dir``. Deprecated; will be
124+
removed in a future release.
132125
analysis_level: The depth of analysis to perform. Common values:
133126
- ``"symbol_table"``: Extract symbols only (faster)
134127
- ``"call_graph"``: Full call graph analysis (comprehensive)
@@ -140,6 +133,10 @@ def __init__(
140133
eager_analysis: If ``True``, forces regeneration of the analysis
141134
database on each run, ignoring any existing cached results.
142135
If ``False``, cached results are reused when available.
136+
backend: The backend configuration object. Defaults to
137+
:class:`~cldk.analysis.commons.backend_config.CodeAnalyzerConfig`,
138+
which runs the packaged codeanalyzer-java binary and caches
139+
``analysis.json`` under a language-keyed cache directory.
143140
144141
Raises:
145142
NotImplementedError: If the requested analysis configuration is
@@ -149,19 +146,23 @@ def __init__(
149146
self.project_dir = project_dir
150147
self.source_code = source_code
151148
self.analysis_level = analysis_level
152-
self.analysis_json_path = analysis_json_path
153-
self.analysis_backend_path = analysis_backend_path
154149
self.eager_analysis = eager_analysis
155150
self.target_files = target_files
151+
self.backend_config: JavaBackend = backend if backend is not None else CodeAnalyzerConfig()
152+
# Java has a single backend family; the config only carries the cache root. analysis.json
153+
# is cached under <cache_dir>/java (None in source_code mode, where the analyzer streams
154+
# results over a pipe).
155+
cache_path = cache_subdir(self.backend_config.cache_dir, project_dir, "java")
156+
if cache_path is not None:
157+
cache_path.mkdir(parents=True, exist_ok=True)
156158
self.treesitter_java: TreesitterJava = TreesitterJava()
157-
# Initialize the analysis analysis_backend
159+
# Initialize the analysis backend
158160
self.backend: JavaAnalysisBackend = JCodeanalyzer(
159161
project_dir=self.project_dir,
160162
source_code=self.source_code,
161163
eager_analysis=self.eager_analysis,
162164
analysis_level=self.analysis_level,
163-
analysis_json_path=self.analysis_json_path,
164-
analysis_backend_path=self.analysis_backend_path,
165+
analysis_json_path=cache_path,
165166
target_files=self.target_files,
166167
)
167168

cldk/analysis/java/codeanalyzer/jar/__init__.py renamed to cldk/analysis/python/neo4j/__init__.py

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
################################################################################
2-
# Copyright IBM Corporation 2024
2+
# Copyright IBM Corporation 2026
33
#
44
# Licensed under the Apache License, Version 2.0 (the "License");
55
# you may not use this file except in compliance with the License.
@@ -14,6 +14,9 @@
1414
# limitations under the License.
1515
################################################################################
1616

17-
"""
18-
Jar package
19-
"""
17+
"""Read-only Neo4j-backed Python analysis backend (Cypher queries over the codeanalyzer-python graph)."""
18+
19+
from cldk.analysis.python.neo4j.config import Neo4jConnectionConfig
20+
from cldk.analysis.python.neo4j.neo4j_backend import PyNeo4jBackend
21+
22+
__all__ = ["PyNeo4jBackend", "Neo4jConnectionConfig"]

0 commit comments

Comments
 (0)