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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    EpicCross-repo coordination epic

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions