Skip to content

Migrate emission to canonical schema v2 (L1 → L2 → Neo4j → L3 remap; gates python-sdk 2.0.0) #175

Description

@rahlk

PROBLEM

codeanalyzer-java emits the old schema (Neo4j contract 1.1.0), and its in-flight L3/SDG work (#171/#173) is old-shape (program_graphs/sdg_edges). It is the last L2+ language off canonical schema v2, and the SDK's 2.0.0 GATES on this migration (decision in codellm-devkit/python-sdk#238).

SCOPE BOUNDARY

Pure graph provider — this analyzer emits schema v2 and stops. No SDK work here (that is python-sdk#228); slicing/taint remain SDK-side queries. Golden rule: keep everything that COMPUTES facts (WALA, the resolver, the call-graph builder); replace only what SERIALIZES them.

GOALS (staged lowest-first per the migration playbook; each stage independently validatable)

  1. L1 emission: the containment tree with can:// ids, span with byte offsets, whole-file source on the module node (per-callable code retires), structured decorators[] (was flat annotations[]), error_channel[] (was thrown_exceptions[]), single kind per type node (the is_* booleans retire).
  2. L2 emission: identity-only call_graph {src,dst,prov,weight} at application scope (rich JGraphEdges retire); callee null->id backfill on call body nodes.
  3. Neo4j v2 projection: relabel to the v2 node/edge families; schema.neo4j.json bumps to 2.0.0.
  4. L3 remap: move program_graphs.functions[sig].cfg.nodes into body{}; split sdg_edges into cfg/cdg/ddg/summary (intra) + param_in/param_out (application); data_dependence: no-heap|full becomes the ddg prov: ["ssa"] vs ["points-to"] split.

CAVEATS AND KNOWN RISKS

  • The WALA L3 remap is the long pole; stages 1-3 land first so the SDK's rc train can validate against Java L1/L2 early.
  • Keep the old emitter behind a flag during transition (the compat shim), with a superset check: v2 output contains every old-output fact modulo the sanctioned drops.
  • Parity clause: never rename or repurpose shared vocabulary; Java-specific additions are recorded in .claude/SCHEMA_DECISIONS.md.

DEFINITION OF DONE

  • v2 output validates against the SDK cpg models at each emitted max_level; L1 ⊆ L2 ⊆ L3 superset gate holds.
  • Neo4j load clean — no dangling edges; conformance test against the bumped schema.neo4j.json green.
  • Major version release cut with the breaking output change in the changelog; python-sdk#228 unblocked.

Part of codellm-devkit/python-sdk#238

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions