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

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions