python-sdk v2.0.0-rc.3

[rahlk]

TypeScript and Java now answer the same query surface Python has: addressing, per-callable control
and data flow, slices, call-graph and value-flow predicates, entrypoints, and the repository-artifact
layer — identically whether you read an analysis.json or an attached Neo4j graph, including on the
paths where a backend has to refuse.

Four legs of work: TypeScript on schema v2 and its query surface, Java on schema v2 (driven by
the analyzer wheel, with degraded runs reported rather than silent) and its query surface. Design
records: docs/design/specs/2026-09-06-leg-2.5-typescript.md and
docs/design/specs/2026-09-06-leg-3-java.md.

Both analyzers moved with it. codeanalyzer-java 3.1.0 connects the level-4 port lattice, so Java's
interprocedural value questions answer for the first time, and adds config-read provenance and the
entrypoint report. codeanalyzer-typescript 1.5.0 corrects source spans to UTF-8 byte offsets and
gives declaration-merged names one id per facet, so a class and an interface of the same name are both
reachable instead of one shadowing the other.

Where a backend cannot answer, it says so and says why. Every such refusal is measured from the data in
front of it, never from an analyzer version string, so a re-emitted graph starts answering on its own.
What remains unanswerable is listed under Known limitations rather than returned as an empty
result.

Breaking

• Java: get_call_graph() nodes are "<type fqn>.<signature>" strings, not (signature, klass) tuples.
  Take the owning class from cg.nodes[key]["method_detail"].klass rather than splitting the key.
• Java: single-file source_code mode is gone. Analyze the project directory instead.
• Java: a local or anonymous class's qualified name carries its declaring callable (p.Outer.m(int).$anon$0).
  Without it, sibling callables collide. Take class keys from get_all_classes() rather than composing them.
• A graph emitted below the analyzer floor is refused at attach with GraphSchemaMismatch instead of
  answering every query with zero rows: codeanalyzer-java 3.0.1 and codeanalyzer-typescript 1.3.0. Re-emit;
  there is no in-place upgrade. TSNeo4jBackend also speaks a graph vocabulary that shares nothing with 0.4.3's.
• Values that changed shape: JGraphEdges and TSCallEdge are now {src, dst, prov, weight}; Java's
  calling_lines is a sorted list of absolute file lines; Java's get_config_keys() is keyed by the
  artifact-relative key; Java's get_test_methods() reads the analyzer's annotations rather than re-parsing
  source; TSCallable lost path/call_sites/accessed_symbols/local_variables/code_start_line and
  TSModule lost file_path/module_name, since v2 keys modules by path and stores source once;
  TSCallableOverview.from_callable takes a required keyword-only path.
• Removed: TypeScriptAnalysis.get_entry_point_methods and get_service_entry_point_methods, which only
  ever raised — the working entrypoint accessors below replace them.
• TypeScript TSSpan.bytes are UTF-8 byte offsets, on every node at every level
  (codeanalyzer-typescript 1.5.0, cants#179). They were UTF-16 code units, which Python sliced as code points
  and the Neo4j projection sliced as bytes — three units that agreed only on ASCII. TSCallable.code and
  every accessor built on it (get_source, get_method_bodies, describe, locate(...).source) now decode
  the module's UTF-8 bytes, the way Java's JCompilationUnit.slice() already did: encoded once per module, a
  plain index when the file is ASCII. On a non-ASCII file, text read through 1.3.0/1.4.0 was wrong and is now
  right — re-emit rather than compare offsets across versions. Note that schema_version stays 2.0.0
  through this break: the contract version is not a signal that a breaking change landed.

Added

• The agent-facing query surface on TypeScriptAnalysis — 29 accessors, each with PythonAnalysis's
  signature and semantics. Addressing (locate, locate_many, resolve_callable, resolve_value,
  get_source, describe, has_resolution_edges); per-callable graphs and dataflow (get_cfg/get_cdg/
  get_ddg, slice_backward/slice_forward/backward_cone, reaches, callers_of/callees_of,
  paths_between/call_paths_between, flows_to_call/flows_to_argument); entrypoints
  (get_entrypoints, get_entrypoint_classes, get_entrypoint_coverage, get_config_readers); and the five
  repository-artifact getters. Both backends answer identically, including on the miss paths.
• The agent-facing query surface on JavaAnalysis — 38 accessors, each with PythonAnalysis's signature and
  semantics. Addressing (locate, locate_many, resolve_callable, resolve_value, get_source,
  describe, has_resolution_edges); per-callable graphs and dataflow (get_cfg/get_cdg/get_ddg,
  slice_backward/slice_forward/backward_cone, reaches, callers_of/callees_of,
  paths_between/call_paths_between, flows_to_call/flows_to_argument); entrypoints and the bulk
  projections (get_entrypoints, get_entrypoint_classes, get_entrypoint_coverage,
  get_callables_overview, get_method_bodies, get_decorated_callables, get_callsites_for,
  get_external_symbols); the six repository-artifact getters; and the type-kind leaf accessors
  get_interfaces/get_enums/get_enum_members/get_records. Both backends answer identically,
  including on the miss paths.
• cldk.models.java.JCallableOverview and JClassOverview, the projections those bulk accessors
  return. They carry the addressable "<type fqn>.<signature>" key, never a can:// id.
• Six Java accessors that only ever raised NotImplementedError now answer (#366), at the
  signature they have always been published with: get_imports() (the project's distinct import
  targets, sorted — the Neo4j projection aggregates a module's imports per target, so file order is
  not recoverable and the set is what both backends can give), get_variables() (each callable's
  local variables, keyed by the "<type fqn>.<signature>" call-graph key and ordered by
  (line, name); fields and parameters keep their own accessors, and an unexpected keyword now
  raises TypeError instead of being ignored), get_class_hierarchy() (a nx.DiGraph, subclass →
  supertype, each edge carrying type="EXTENDS" or "IMPLEMENTS" — read off each declaration's own
  base_types/interfaces, which is why out-of-project supertypes are in it),
  get_methods_with_annotations() (grouped by the spelling the caller passed, matched by the J-5
  marker rule, each entry {class, signature, method_name, body}), get_call_targets() (the
  declared names some call site actually writes — simple-name matching, no overload resolution) and
  get_calling_lines() (sorted, distinct absolute file lines, off the call graph's own
  calling_lines). Both backends answer identically; none of the six issues any new Cypher.
  get_service_entry_point_classes/get_service_entry_point_methods and remove_all_comments
  still raise.
• Java reaches analysis levels 3 and 4 — control flow, control and data dependence, and the interprocedural
  graph. The level now reaches the analyzer, which it never did before.
• A java install extra. pip install "cldk[java]" brings the analyzer and its bundled JVM;
  pip install "cldk[all]" reproduces the previous behaviour. Bare cldk no longer carries either. The Python
  and TypeScript analyzers are still installed unconditionally; #340 moves them into extras of their own.
• JavaScript modules are in scope for TypeScript analysis, under their own id prefix.
• A degraded Java level-3 or level-4 run is reported rather than silent. Those levels need compiled classes;
  without them the analyzer emits a declared-only graph and still reports the level. The SDK now surfaces the
  analyzer's own warnings and records them beside the payload, so a cached run still knows. The graph is
  returned either way.
• cldk.models.typescript.TSClassOverview, the class-level projection get_entrypoint_classes returns.

Changed

• Java's four interprocedural value accessors now answer. slice_forward, paths_between,
  flows_to_call and flows_to_argument refused on Java because codeanalyzer-java emitted the level-4 port
  lattice disconnected from the statement dependence graph — a formal_in had out-degree zero, so every
  forward answer was empty whatever the program did. codeanalyzer-java 3.0.3 joins the two layers
  (codeanalyzer-java#227), and the SDK's guard reads the data rather than a version, so all four answer: a
  value can be followed out of a parameter, across call boundaries and into a callee's parameter, with each
  hop labelled data / argument / return / control. Measured on the whole of daytrader8: 5,083 ddg
  edges cross between the port lattice and the statement graph in all four directions, where there were none.
  To get this, re-analyse (or re-emit your Neo4j graph) with the pinned analyzer; an older graph stays
  attachable and keeps refusing, as does any analysis run under --l3-engine wala. The same release drops
  ddg edges whose endpoint was never emitted as a body node (codeanalyzer-java#228), so get_ddg() over
  analysis.json and over Neo4j now report the same edges — 10,430 on daytrader8, set for set, against a
  5,434/5,347 split before.
• Java's code-to-config layer and entrypoint report now answer. codeanalyzer-java 3.1.0 adds both, so
  get_config_uses(), get_config_readers(key) and get_unresolved_config_reads() return real edges instead
  of [], and get_entrypoint_coverage() returns the pass's own record instead of
  entrypoint_report_unavailable. The two config tiers are surfaced, not flattened: prov == ["literal"]
  is a string literal at the call site (codeanalyzer-java#233), "dataflow" is a key reached over the L3 DDG
  or the L4 call graph (#237) — a derived answer, weaker evidence, and it widens with the analysis level. On a
  PyConfigRead the list is every tier attempted, so ["literal", "dataflow"] means the dataflow tier ran
  and still could not name the key. Measured on daytrader8: 13 resolved uses (all ["literal"]) and 16
  unresolved reads — ["literal"] at level 1, ["literal", "dataflow"] at level 4; the graph collapses those
  16 into 8 edges, since J_READS_CONFIG_UNRESOLVED is discriminated by (key, reason) and carries no site.
  To get this, re-analyse (or re-emit your Neo4j graph) with the pinned analyzer; an older analysis
  keeps refusing, and the probe is measured from the data rather than from a version string — see the known
  limitation below for what it measures and why it cannot be the config layer's own absence.
• Pins: codeanalyzer-java 2.4.1 → 3.1.0, codeanalyzer-typescript 0.4.3 → 1.5.0.
• The Java analyzer ships as a wheel, not a jar in this repo. The 35 MB checked-in jar, the Temurin download
  in _jdk.py, and the release workflow's jar injection are gone; no JAVA_HOME is read or set, and no JDK is
  downloaded. The published wheel drops from about 35 MB to 320 KB.
• Both languages' backends inherit the generic AnalysisBackend, so each answers the shared artifact,
  dependency and configuration accessors.
• Where a backend cannot answer, it says so instead of returning an empty value. On Neo4j: Java's file-keyed
  comment accessors, and TypeScript's get_extended_classes/get_implemented_interfaces when the relationship
  type is absent — and its get_imports, get_exports, get_method_parameters and
  get_unresolved_config_reads on a graph emitted before codeanalyzer-typescript 1.4.0, which carries none
  of the data they read (below). The remaining documented gaps, and where the two backends legitimately differ,
  are listed in docs/agent-api-reference.md.
• TypeScript's get_imports, get_exports, get_method_parameters and get_unresolved_config_reads answer
  over Neo4j, on a graph emitted by codeanalyzer-typescript 1.4.0 or newer: the projection gained
  TS_IMPORTS / TS_RE_EXPORTS edges, :TSModule.exports_json, :TSCallable.parameters_json and
  TS_READS_CONFIG_UNRESOLVED (codeanalyzer-typescript#182). Parameters also reach TSCallable.parameters and
  exports reach TSModule.exports on a rebuilt node. A 1.3.0 graph is still attachable and those four
  still refuse there rather than answer an empty that would read as a fact; the decision is measured from the
  application's own data — is any carrier present — never from the analyzer's version string, so a re-emitted
  graph starts answering with no SDK change. TSImport/TSExport gained the analyzer's new
  resolved_module. Migration: re-emit with codeanalyzer-typescript>=1.5.0 --emit neo4j.
• Three more codeanalyzer-typescript ceilings are gone in 1.5.0, verified against the re-emitted reference
  graph rather than taken from the release notes. :TSCallable.code is no longer one line short over Neo4j
  (cants#179) — the four xfail(strict=True) marks that pinned it now XPASS and are removed. Declaration
  merging mints one id per facet (cants#177), so a class X + interface X pair is two nodes and both
  are served, where before one facet was lost to whichever declaration the emitter saw last; on
  superset-frontend that is 7 signatures, and no node carries two declaration labels any more. The analyzer
  also refuses a missing or non-directory input instead of exiting 0 (cants#181) and no longer clones the whole
  envelope per module (cants#180); neither had an SDK workaround to remove.
• Every Cypher statement is scoped per bound variable, not per statement — both endpoints of a call edge, a
  quantified path's far end, a slice's reached body nodes, and every interior node of a variable-length or
  shortest-path walk (all(n IN nodes(p) …) on the slice, path and reachability queries). A statement that
  matched one endpoint by a signature two applications both declare, or that walked through an intermediate it
  never predicated, could previously return the other application's node.
• LocateResult.body is a language-neutral BodyRef, so cldk/analysis/commons/ no longer imports a
  language package for it.
• An AmbiguousName now names only the ways out that are actually open — on all three languages. The
  Narrow it with … sentence offers in_class= / in_module= only when the caller has not already passed
  that keyword and the listed matches disagree on it, so two overloads of one class, or two __init__s of
  one class, are no longer told to narrow by a keyword that provably cannot split them. The last clause is
  always offered and is language-specific: more of the dotted path on Python and TypeScript, and on Java
  the full signature, exactly as one of the listed matches spells it (more of the dotted path cannot
  separate two overloads). AmbiguousName.candidates is unchanged. Python's resolve_callable,
  callers_of, callees_of and resolve_within therefore produce a different message for the same input
  than in rc.2; assert on .candidates, not on the sentence.
• Internal: the language-neutral query helpers moved from cldk/analysis/python/ to cldk/analysis/commons/;
  Python re-imports every name unchanged.

Fixed

• get_cfg/get_cdg/get_ddg on the Python Neo4j backend no longer drop self-loop edges. The
  per-callable query bound the containment relationship twice, so Cypher's relationship-uniqueness rule
  silently discarded every edge whose endpoints are the same body node — a statement that reads a
  variable it also redefines. 64,702 such edges exist on the odoo reference graph; one callable returned
  28,146 of its 28,394. total was counted from the same match, so the short page reported itself
  complete. (#349)

• JavaAnalysis.get_method_parameters() is annotated List[JCallableParameter], which is what it has always
  returned.

• get_call_graph() on Java no longer re-parses each method body once per edge — 145.7s to 41.0s on a
  4,100-file project.

• Two documentation errors: EntrypointCoverage.unresolved is a dict[str, int], not a list[str]; and the
  get_config_keys() example used a key form that never worked.

• get_source() on the in-process TypeScript backend named the application by its can:// id where the Neo4j
  backend named it plainly; both now name the application. get_external_symbols() and get_source() over
  Neo4j scoped externals by the can://typescript/ prefix alone, dropping any external a JavaScript module
  owns; both now carry the two-prefix scope.

Known limitations

• Java CRUD accessors raise: schema v2 does not carry CRUD yet (codeanalyzer-java#187).
• The Java graph's JCallable.code is the declaration slice where the JSON's is the body block, and the graph
  cannot recover the body block (codeanalyzer-java#176).
• Import bindings read over the TypeScript Neo4j backend are narrower than in process. TS_IMPORTS folds
  every binding between a module pair into one edge of sorted sets, so an entry's alias, import_kind and span
  are not recoverable, and the emitter drops a relative specifier that resolved to no emitted module. Exports,
  parameters and unresolved config reads are lossless, except that the config-read edge carries no site and
  collapses sites sharing a (callee, key, reason) triple.
• TypeScript's DDG has one provenance tier; Java's has two; Python's has three.
• get_config_keys() is still keyed by a can:// id on Python and TypeScript, where Java now uses the
  artifact-relative key (#346).
• Java's slice_forward, paths_between, flows_to_call and flows_to_argument still raise on an
  analysis emitted before codeanalyzer-java 3.0.3, or by any version under --l3-engine wala: no dependence
  edge leaves a formal_in there, so every forward answer would be empty whatever the program does. A Neo4j
  graph emitted by 3.0.1 or 3.0.2 is still attachable (the floor is 3.0.1) and still refuses — re-emit it.
• Java's flows_to_argument is not per-argument precise. codeanalyzer-java feeds every actual of a call
  site from the one statement containing it, not from the reaching definition of that argument, so on a
  reached call site every argument answers True together. Paths are complete; per-argument precision is not
  what the analyzer promises.
• Java's entrypoint report and code-to-config layer need codeanalyzer-java 3.1.0. On an older analysis —
  a cached analysis.json is reused whatever wrote it, and a 3.0.x Neo4j graph is still attachable, the floor
  being 3.0.1 — get_entrypoint_coverage() returns entrypoint_report_unavailable rather than fabricated
  coverage, and get_config_uses() / get_config_readers() / get_unresolved_config_reads() raise rather
  than answer []. The probe is one fact measured from the data: 3.1.0 writes an entrypoint report on every
  run and 3.0.x writes none of the three overlays. It deliberately is not the config layer's own absence,
  which is ambiguous — the analyzer writes config_uses / config_reads_unresolved only when non-empty, and
  the graph declares J_USES_CONFIG / J_READS_CONFIG_UNRESOLVED only once an edge exists, so a clean 3.1.0
  analysis of a project that reads no configuration carries neither and must still answer. get_entrypoints()
  and get_entrypoint_classes() carry the real marks at every generation, as does get_config_keys().
• Java's get_external_symbols() answers over Neo4j and raises locally: the analyzer homes out-of-project
  call targets only under --external-calls, which --emit neo4j forces and a local run does not.
• The Java graph carries a switch body-node kind, which is outside SliceNode.KINDS (that vocabulary is
  codeanalyzer-python's, and Python has no switch statement). It is reported as the analyzer spells it.
• Java's get_ddg() over Neo4j carries 276 points-to edges (on daytrader8) that the same
  analyzer's analysis.json does not, and that is a difference of what each source was asked.
  codeanalyzer-java 3.1.0 makes the level-4 points-to layer depend on --external-calls, which
  --emit neo4j forces on and which the SDK's local run does not pass; 3.0.3 produced the same
  10,430 edges either way. Measured on daytrader8, same tree, four runs: 3.0.3 -a 4 → 10,430
  (1,134 points-to); 3.1.0 -a 4 → 10,154 (858); 3.1.0 -a 4 --external-calls → 10,430, set for
  set identical to the graph; 3.1.0 --emit neo4j → 10,430. The graph is a strict superset and the
  payload has nothing the graph lacks, so slice_forward and the other forward walks can reach
  further over Neo4j. Reported upstream: the flag is documented as controlling only whether
  out-of-project call targets are homed as external_symbols.
• The Java Neo4j projection still carries no comment nodes. codeanalyzer-java 3.1.0 closes
  codeanalyzer-java#231's config-read and entrypoint-report halves and not its comment half: :JComment is a
  declared label with zero nodes on a graph emitted by it, and only a declaration's docstring reaches
  the graph. So remove_all_comments keeps raising, and the file-keyed comment accessors keep refusing over
  Neo4j while the javadoc-only ones narrow, exactly as before.