Skip to content

Epic: namespace the TS Neo4j graph with TS/TS_ prefixes via dual-label staging (analyzer + SDK + docs) #64

Description

@rahlk

SUMMARY

The TypeScript analyzer is the only CLDK backend whose Neo4j projection uses bare node labels and relationship types (:Callable, CALLS) — Java uses J/J_, Python uses Py/PY_ — so a shared multi-language database cannot attribute TS nodes, and generic labels collide with other data. This epic namespaces the TS graph in two stages: an additive dual-label release (graph schema 1.1.0) that adds TS-prefixed twin labels alongside the existing ones without breaking any consumer, then a breaking completion folded into the in-flight v2/CanNode contract (graph schema 2.0.0) that drops the bare labels and renames relationship types to TS_*. analysis.json is untouched; only the Neo4j projection of the contract moves.

AFFECTED REPOS (from Contract-Impact Triage)

  • codellm-devkit/codeanalyzer-typescript — emitter (schema.ts, project/cypher/bolt, conformance test, schema.neo4j.json) — codeanalyzer-backend rung (stages 1 and 2) + finishing
  • codellm-devkit/python-sdk — cldk/analysis/typescript/neo4j/neo4j_backend.py queries the bare labels/rels and pins codeanalyzer-typescript==0.4.3 — cldk-sdk-frontend rung
  • codellm-devkit/cldk-devtools (formerly cldk-forge) — skills/codeanalyzer-backend/references/neo4j-projection.md (all copies) currently blesses TS as unprefixed — docs
  • codellm-devkit/docs — TS backend page label audit — docs

DESIGN DECISIONS (locked before build starts)

  • Stage 1 is additive, honestly MINOR (1.1.0): every specific node label gains a TS-prefixed twin on the same node ((:Callable:TSCallable)); marker Entrypoint gains TSEntrypoint; relationship types, merge labels, uniqueness constraints, and keys are unchanged. Existing queries keep working. A wholesale rename cannot ship as MINOR under the schema's own MAJOR-on-rename rule (src/build/neo4j/schema.ts).
  • Stage 2 is the breaking completion, shipped inside the v2/CanNode contract (2.0.0): bare specific labels dropped, every relationship type renamed to TS_*. CanNode deliberately stays unprefixed as the shared cross-language canonical merge layer — it merges on can:// ids, which embed the language, so no cross-language collision is possible there; per-language attribution comes from the specific labels.
  • Convention change: neo4j-projection.md is rewritten to mandate language prefixes for all analyzers (CamelCase tag on node labels, UPPER_SNAKE tag on relationship types), removing the bare-namespaced option, with the shared-merge-label carve-out and dual-label staging documented as the sanctioned migration path.
  • Existing issues: Namespace Neo4j node labels with a TS prefix #8 is delivered (additively) by stage 1 with the merge label kept shared; Namespace Neo4j relationship types with a TS_ prefix #9 and Bump graph schema contract to 2.0.0 and regenerate published artifacts #10 are absorbed by stage 2. The stale branch patch/ts-prefix-neo4j-schema predates the refactor(neo4j): consolidate the graph schema into one source of truth (closes #15) #16 schema consolidation (it rewrote the deleted catalog.ts) and serves only as a reference diff.
  • Scope guard: no analysis.json change; no SDK public-API change (the Neo4j query layer is internal); Java/Python analyzers unchanged; no in-place data migration for existing databases (re-analyze to upgrade).

CHILDREN (one per rung/PR-unit; checklist updated as they land)

DEFINITION OF DONE (epic-level)

  • Every child PR merged and its gate green (Neo4j conformance test enforces the declared schema at each stage).
  • Stage 1: a loaded graph returns identical node counts for each bare label and its TS twin; edge counts unchanged; SCHEMA_VERSION = 1.1.0 stamped on :Application.
  • Stage 2: no bare specific labels remain; all rels TS_*; CanNode merge intact; SCHEMA_VERSION = 2.0.0.
  • python-sdk pin bumped only once both sides of each stage are released; its TS Neo4j tests green against the new labels.
  • Convention doc updated in all three copies; docs page audited; CHANGELOGs note the schema versions.

Metadata

Metadata

Assignees

No one assigned

    Labels

    epicCross-repo coordination epic

    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