feat(typescript)!: speak graph schema 2.0.0 — TS-prefixed vocabulary, CanNode keys, fail-fast version check (closes #268)

Rewrite the read-only TS Neo4j backend to query the canonical 2.0.0 graph
(CanNode identity, TS-prefixed labels/relationships) and reject any other
schema on connect.

- Every Cypher query maps to the 2.0.0 vocabulary: :Symbol -> :CanNode,
  :Callable/:Class/... -> :TSCallable/:TSClass/..., CALLS/DECLARES/HAS_METHOD/
  RESOLVES_TO/HAS_MODULE -> TS_CALLS/TS_DECLARES/TS_HAS_METHOD/TS_RESOLVES_TO/
  TS_HAS_MODULE. Application matched by `id ENDS WITH "/" + $app` (no `name`);
  modules keyed by `_module` (no `file_key`).
- Call sites are now :TSBodyNode {kind:"call"} reached via TS_HAS_BODY_NODE and
  resolved through TS_RESOLVES_TO (no :CallSite nodes); reconstruct reads the
  target from `callee`.
- Fail-fast: `_check_schema_version` reads (:Application).schema_version once in
  __init__ and raises the new CldkSchemaMismatchException unless it is "2.0.0".
- Accessors whose vocabulary 2.0.0 does not project raise NotImplementedError
  (no JSON fallback exists for a read-only Cypher client): get_decorators,
  get_class_decorators, get_methods_with_decorators, get_classes_with_decorators,
  get_all_fields, get_interface_properties, get_imports, get_all_exports,
  get_all_variables. Whole-object reconstruction degrades those sub-fields to
  empty so graph-supported accessors keep working. Public facade names and
  return types are unchanged.
- Tests: new test_typescript_neo4j_schema.py covers the version gate and the
  fallback raises without a live graph; the stubbed-graph parity tests adopt the
  2.0.0 query strings; the live-graph integration suite is skipped until the
  analyzer pin moves to >=1.0.0 (Task 9).

Author: rahlk

cldk/analysis/typescript/neo4j/neo4j_backend.py

@@ -106,7 +106,8 @@ def callsite(props: Props) -> TSCallsite:
         argument_types=list(props.get("argument_types", []) or []),
         type_arguments=list(props.get("type_arguments", []) or []),
         return_type=props.get("return_type"),
-        callee_signature=props.get("callee_signature"),
+        # schema 2.0.0 call-site body nodes key the resolved target as ``callee``.
+        callee_signature=props.get("callee_signature", props.get("callee")),
         is_constructor_call=props.get("is_constructor_call", False),
         is_optional_chain=props.get("is_optional_chain", False),
         start_line=props.get("start_line", -1),
@@ -370,8 +371,9 @@ def namespace(
 
 def module(props: Props, **children: Any) -> TSModule:
     return TSModule(
-        file_path=props.get("file_key", props.get("file_path", "")),
-        module_name=props.get("module_name", ""),
+        # schema 2.0.0 modules carry the project-relative path as ``_module``.
+        file_path=props.get("_module", props.get("file_path", "")),
+        module_name=props.get("module_name", props.get("name", "")),
         is_tsx=props.get("is_tsx", False),
         is_declaration_file=props.get("is_declaration_file", False),
         content_hash=props.get("content_hash"),

cldk/analysis/typescript/neo4j/reconstruct.py

@@ -87,6 +87,32 @@ def __init__(self, message: str) -> None:
         super().__init__(self.message)
 
 
+class CldkSchemaMismatchException(Exception):
+    """Exception raised when a persisted graph's schema version is not the one this SDK speaks.
+
+    The Neo4j-backed TypeScript backend reads ``(:Application).schema_version`` on first use and
+    raises this if it differs from the graph schema the SDK was written against. Re-analyze the
+    project with a ``codeanalyzer-typescript`` whose Neo4j projection emits the expected schema.
+
+    Attributes:
+        message (str): A descriptive error message naming the found and expected schema versions.
+
+    See Also:
+        :class:`~cldk.analysis.typescript.neo4j.neo4j_backend.TSNeo4jBackend`: raises this on a
+            version mismatch.
+    """
+
+    def __init__(self, message: str) -> None:
+        """Initialize the exception with a descriptive message.
+
+        Args:
+            message: A descriptive error message naming the found vs. expected schema versions
+                and how to resolve the mismatch.
+        """
+        self.message = message
+        super().__init__(self.message)
+
+
 class CodeanalyzerUsageException(Exception):
     """Exception raised for incorrect CodeAnalyzer usage.
 

cldk/utils/exceptions/exceptions.py

@@ -218,15 +218,15 @@ def stub_neo4j_backend():
     baz_props = _callable_props(_baz())
     qux_props = _callable_props(_qux())
 
-    has_method_query = "MATCH (o:Symbol {signature: $sig})-[:HAS_METHOD]->(m:Callable {name: $name}) RETURN properties(m) AS p LIMIT 1"
+    has_method_query = "MATCH (o:CanNode {signature: $sig})-[:TS_HAS_METHOD]->(m:TSCallable {name: $name}) RETURN properties(m) AS p LIMIT 1"
     exact_sig_query = (
-        "MATCH (parent)-[:DECLARES]->(c:Callable {signature: $sig}) "
-        "WHERE (parent:Module OR parent:Namespace) AND c._module IN $mods "
+        "MATCH (parent)-[:TS_DECLARES]->(c:TSCallable {signature: $sig}) "
+        "WHERE (parent:TSModule OR parent:TSNamespace) AND c._module IN $mods "
         "RETURN properties(c) AS p LIMIT 1"
     )
     short_name_query = (
-        "MATCH (parent)-[:DECLARES]->(c:Callable {name: $name}) "
-        "WHERE (parent:Module OR parent:Namespace) AND c._module IN $mods AND c.signature STARTS WITH $prefix "
+        "MATCH (parent)-[:TS_DECLARES]->(c:TSCallable {name: $name}) "
+        "WHERE (parent:TSModule OR parent:TSNamespace) AND c._module IN $mods AND c.signature STARTS WITH $prefix "
         "RETURN properties(c) AS p LIMIT 1"
     )
 

tests/analysis/typescript/test_typescript_get_method_functions.py

@@ -68,10 +68,20 @@ def _neo4j_reachable() -> bool:
         return False
 
 
-pytestmark = pytest.mark.skipif(
-    not _neo4j_reachable(),
-    reason=f"no Neo4j reachable at {NEO4J_URI} (set CLDK_TEST_NEO4J_URI / _USER / _PASSWORD)",
-)
+# The read-only backend now speaks graph schema 2.0.0 (TS-prefixed vocabulary, CanNode keys), but
+# the pinned ``codeanalyzer-typescript`` is still 0.4.3, whose ``--emit neo4j`` projection predates
+# that schema — so this out-of-band-populated integration suite cannot produce a conformant graph
+# yet. It is unconditionally skipped until the analyzer pin moves to >=1.0.0 (release-train Task 9);
+# the ``_neo4j_reachable`` guard is retained for when it is re-enabled.
+pytestmark = [
+    pytest.mark.skipif(
+        not _neo4j_reachable(),
+        reason=f"no Neo4j reachable at {NEO4J_URI} (set CLDK_TEST_NEO4J_URI / _USER / _PASSWORD)",
+    ),
+    pytest.mark.skip(
+        reason="needs a graph schema 2.0.0 database (codeanalyzer-typescript>=1.0.0); the pin is still 0.4.3 until Task 9 moves it",
+    ),
+]
 
 
 def _codeanalyzer_ts_exec() -> list[str]:

tests/analysis/typescript/test_typescript_neo4j_backend.py

@@ -0,0 +1,91 @@
+################################################################################
+# Copyright IBM Corporation 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+################################################################################
+
+"""Unit tests for the TS Neo4j backend's graph-schema contract (no live Neo4j required).
+
+Two things are exercised here without ever opening a Bolt connection:
+
+* the fail-fast ``schema_version`` gate (``_check_schema_version``) the backend runs on first use;
+* the accessors whose vocabulary is *not projected* into graph schema 2.0.0 (decorators,
+  attributes/fields, module imports/exports, variables) — these must raise a clear
+  ``NotImplementedError`` rather than silently returning wrong data.
+
+Both are tested against a bare ``__new__`` instance (no ``__init__``, so no driver), because the
+logic under test never needs a real session.
+"""
+
+import pytest
+
+from cldk.analysis.typescript.neo4j import TSNeo4jBackend
+from cldk.utils.exceptions.exceptions import CldkSchemaMismatchException
+
+
+def _bare_backend() -> TSNeo4jBackend:
+    """A backend instance with no live driver — enough to exercise pure query/guard logic."""
+    return TSNeo4jBackend.__new__(TSNeo4jBackend)
+
+
+# -----[ schema-version gate ]-----
+def test_schema_version_mismatch_fails_fast():
+    backend = _bare_backend()
+    with pytest.raises(CldkSchemaMismatchException):
+        backend._check_schema_version(expected="2.0.0", found="1.0.0")
+
+
+def test_schema_version_match_passes():
+    backend = _bare_backend()
+    # An exact match is a no-op (returns None, raises nothing).
+    assert backend._check_schema_version(expected="2.0.0", found="2.0.0") is None
+
+
+def test_schema_version_queried_from_application_when_not_supplied(monkeypatch):
+    backend = _bare_backend()
+    monkeypatch.setattr(backend, "_run", lambda *a, **k: [{"v": "2.0.0"}])
+    # Reads (:Application).schema_version and finds the supported version ⇒ passes.
+    assert backend._check_schema_version(expected="2.0.0") is None
+
+    monkeypatch.setattr(backend, "_run", lambda *a, **k: [{"v": "1.0.0"}])
+    with pytest.raises(CldkSchemaMismatchException):
+        backend._check_schema_version(expected="2.0.0")
+
+
+def test_schema_version_absent_fails_fast(monkeypatch):
+    backend = _bare_backend()
+    # No Application row at all (empty/foreign DB) ⇒ found is None ⇒ mismatch.
+    monkeypatch.setattr(backend, "_run", lambda *a, **k: [])
+    with pytest.raises(CldkSchemaMismatchException):
+        backend._check_schema_version(expected="2.0.0")
+
+
+# -----[ accessors with no graph support in schema 2.0.0 ]-----
+_FALLBACK_CALLS = [
+    ("get_decorators", ("src/x.f",)),
+    ("get_class_decorators", ("src/x.C",)),
+    ("get_methods_with_decorators", (["Get"],)),
+    ("get_classes_with_decorators", (["Controller"],)),
+    ("get_all_fields", ("src/x.C",)),
+    ("get_interface_properties", ("src/x.I",)),
+    ("get_imports", ()),
+    ("get_all_exports", ()),
+    ("get_all_variables", ()),
+]
+
+
+@pytest.mark.parametrize("method_name,args", _FALLBACK_CALLS)
+def test_unprojected_accessor_raises_not_implemented(method_name, args):
+    backend = _bare_backend()
+    with pytest.raises(NotImplementedError, match="graph schema 2.0.0"):
+        getattr(backend, method_name)(*args)