Repository navigation
Description
Is your feature request related to a problem? Please describe.
Every pip install cldk installs every analyzer, so a consumer who only reads a Neo4j graph, or only analyzes Python, still pays for the others. With #339 that becomes concrete: the Java analyzer carries a 35 MB bundled JVM (jdk4py), and jdk4py's PyPI metadata declares bare GPLv2 with no license file, so enterprise policy gates flag it for consumers who never analyze Java. (The runtime itself is ordinary OpenJDK, GPLv2 with the Classpath Exception; the friction is metadata, not licensing.)
[project.optional-dependencies] neo4j already declares only the driver, so pip install "cldk[neo4j]" looks like it should be analyzer-free. It is not, because the analyzers are hard dependencies.
Measured on release/2.0:
| dependency | loaded by import cldk? |
|---|---|
codeanalyzer-java |
no (works uninstalled) |
codeanalyzer-typescript |
declared, not imported at import time |
codeanalyzer-python |
yes, eagerly, 14 modules |
Describe the solution you'd like
-
pip install "cldk[neo4j]"installs no analyzer and no JVM;CLDK.python(...)/typescript/javawith a Neo4j config still work -
pip install "cldk[java]"is the only way to get the JVM (delivered by Java backend: depend on the codeanalyzer-java wheel (bundled JVM) instead of a bundled jar plus _jdk.py #339) -
import cldkworks with any subset of the analyzers absent; calling a facade whose analyzer is missing raises naming the distribution andpip install "cldk[<extra>]" - The shared artifact/config/span/body models no longer live under
cldk/models/python/, andcldk/analysis/commons/imports nothing from a language package - The release workflow and the test groups install the extras the suites need
Describe alternatives you've considered
Not stated in the original issue.
Additional context
The blocker for cldk[python]
The core sources its cross-language vocabulary from the Python analyzer's schema:
cldk/models/python/__init__.py:24re-exportscodeanalyzer.schema.py_schema.cldk/analysis/commons/backend.py:60importsPyArtifact,PyConfigKey,PyConfigRead,PyConfigUseEdge,PyDependencyfrom it — the return types the genericAnalysisBackendpromises for every language.cldk/analysis/commons/results.py:55importsSpanandBodyNodefrom it.
So codeanalyzer-python is a dependency of the core, not of the Python backend. The artifact/config/span/body types are shared by design (leg 1 D2 chose per-language models but a shared artifact layer); they are simply living in the wrong package, and their Py prefix now misnames them.
Scope boundary
In scope: java and typescript extras with lazy imports and an error that names the missing distribution and its install extra; relocating the shared artifact/span/body models out of cldk/models/python/ into a language-neutral home so codeanalyzer-python can become the python extra; keeping cldk[neo4j] analyzer-free; an all extra.
Out of scope: renaming the shared types on the public surface (PyArtifact and friends are returned by existing accessors, so a rename is a separate, sanctioned break). Whether the bare cldk install keeps any analyzer at all is the decision this issue exists to make.
Caveats and known risks
- Breaking for anyone relying on
pip install cldkthenCLDK.python(...). 2.0 is the release that can carry it; it needs a CHANGELOG entry with the one-line migration per language. - Relocating the shared models moves types that appear in public return values. Keep the class identities and re-export from the old paths, or it stops being a packaging change and becomes an API break.
codeanalyzer-pythonis also the source ofAnalysisLevel-adjacent schema helpers used by the Python Neo4j backend; check every import before declaring the core clean.
Definition of done
- A fresh venv per extra combination (
cldk,cldk[neo4j],cldk[java],cldk[python],cldk[all]) imports cleanly, andpip listshows no analyzer the combination did not ask for -
grep -rn "codeanalyzer" cldk/analysis/commons cldk/models/commonsis empty - Each facade's missing-analyzer error is asserted by a test, with the extra named in the message
- Full suite green with the extras installed; the release workflow installs them
Activity
python-sdk2.0 — a static-analysis front end for humans and agents .github#55rahlk commentedon Sep 6, 2026
Decision, 2026-09-06: thin base plus additive extras, with
cldk[all]as the everything install.This settles the open question in the scope boundary above. The reasoning is that extras are purely additive under PEP 508, so
pip install "cldk[neo4j]"can never subtract what the base requires. A fat base and a JVM-free Neo4j install are mutually exclusive; only a thin base delivers the second.Target contract:
pip install cldkpip install "cldk[neo4j]"pip install "cldk[python]"codeanalyzer-pythonpip install "cldk[typescript]"codeanalyzer-typescriptpip install "cldk[java]"codeanalyzer-java, which carries the jar andjdk4pypip install "cldk[all]"Landing in two steps. #339 adds the
javaandallextras now (all = ["cldk[java]", "cldk[neo4j]"], a self-referential spelling so this issue only has to append to it), with a lazy import and an error that names the distribution and the install extra. This issue then movescodeanalyzer-typescriptandcodeanalyzer-pythoninto extras, which for Python requires relocating the shared artifact, config, span and body-node models out ofcldk/models/python/first, as described above.Breaking for anyone who does
pip install cldkand then calls a facade. The migration is one line per language, andcldk[all]reproduces today's behaviour exactly, so the CHANGELOG should lead with that.feat(java): drive the analyzer through the codeanalyzer-java wheel an…
feat(java): drive the analyzer through the codeanalyzer-java wheel an…
feat(java): drive the analyzer through the codeanalyzer-java wheel an…