fix(typescript): guard ambiguous application match; mark 2.0.0 e2e-verify assumptions (#268)

Review fixes on the graph-schema-2.0.0 rewrite:

- `_resolve_application_id` resolves `application_name` to exactly one
  :Application `can://` id on connect; 0 or >1 suffix matches raise
  CodeanalyzerUsageException naming the candidate ids, so a shared database
  with two apps ending in the same path segment can no longer silently merge
  module scopes. `_load_module_keys` anchors on the resolved id. The schema
  check still runs first (DB-level) so pre-2.0.0 graphs keep the actionable
  mismatch error; rationale commented in __init__.
- Every unverified 2.0.0 assumption now carries a VERIFY(2.0.0-e2e) marker at
  its query site (`_module` scoping, array-prop class hierarchy, method_name
  fallback, reconstruct's module_name->name fallback); the module docstring
  states the `_module` claim as to-verify, and the two leftover v1
  "Symbol-keyed" prose comments are reworded.
- Query-construction unit tests capture the built Cypher through the `_run`
  seam for the two riskiest rewrites: the TS_HAS_BODY_NODE / TSBodyNode
  {kind:"call"} / TS_RESOLVES_TO call-site path (reading `callee`) and
  TSModule `_module` scoping, plus the app-id guard (0-match and 2-match).
- CldkSchemaMismatchException exported from cldk.utils.exceptions __all__.

Author: rahlk

cldk/analysis/typescript/neo4j/neo4j_backend.py

@@ -45,10 +45,12 @@
 * call *sites* are body nodes — ``(:TSBodyNode {kind: "call"})`` reached via
   ``TS_HAS_BODY_NODE`` and resolved through ``TS_RESOLVES_TO`` — not standalone
   call-site nodes;
-* every project-owned node carries a ``_module`` provenance property (the
-  project-relative path), so a single database may hold several applications —
-  all queries here are scoped to this backend's application by the set of its
-  module ``_module`` keys.
+* module nodes carry a ``_module`` property (the project-relative path); this
+  backend further *assumes* — to-verify against a live 1.0.0 graph, see the
+  ``VERIFY(2.0.0-e2e)`` markers — that every project-owned node carries the same
+  ``_module`` provenance property, so a single database may hold several
+  applications and all queries here can be scoped to this backend's application
+  by the set of its module ``_module`` keys.
 
 Parity caveats (inherent to what schema 2.0.0 projects, not bugs):
 
@@ -91,7 +93,7 @@
     TSTypeAlias,
     TSVariableDeclaration,
 )
-from cldk.utils.exceptions.exceptions import CldkSchemaMismatchException, CodeanalyzerExecutionException
+from cldk.utils.exceptions.exceptions import CldkSchemaMismatchException, CodeanalyzerExecutionException, CodeanalyzerUsageException
 
 logger = logging.getLogger(__name__)
 
@@ -139,9 +141,16 @@ def __init__(
         self._database = neo4j_database
         self._driver = GraphDatabase.driver(neo4j_uri, auth=(neo4j_username, neo4j_password))
 
-        # Fail fast if the persisted graph isn't the schema this SDK speaks.
+        # Fail fast if the persisted graph isn't the schema this SDK speaks. This runs *before*
+        # the application-id resolution on purpose: a pre-2.0.0 graph has no `can://` ids, so
+        # resolving first would report "no application found" instead of the (more actionable)
+        # schema mismatch.
         self._check_schema_version()
 
+        # Resolve `application_name` to exactly one Application `id` (guards against a shared
+        # database where several apps' ids share the same trailing path segment).
+        self._app_id: str = self._resolve_application_id()
+
         # The application's module `_module` keys, used to scope every query to this app.
         self._modules: List[str] = self._load_module_keys()
 
@@ -177,12 +186,39 @@ def _check_schema_version(self, expected: str | None = None, found: str | None =
                 f"graph schema {found!r} in database, this SDK speaks {expected!r} — re-analyze with codeanalyzer-typescript>=1.0.0"
             )
 
-    def _load_module_keys(self) -> List[str]:
+    def _resolve_application_id(self) -> str:
+        """Resolve ``application_name`` to exactly one ``:Application`` node's ``can://`` id.
+
+        The suffix match (``a.id ENDS WITH "/" + $app``) can bind multiple applications in a
+        shared database — e.g. two repos whose ids both end in ``/frontend`` — which would
+        silently merge their module scopes. Raise :class:`CodeanalyzerUsageException` unless the
+        match is unique; the caller disambiguates by passing a longer trailing path (any suffix
+        of the ``can://`` id starting at a ``/`` boundary works as ``application_name``).
+        """
         rows = self._run(
-            'MATCH (a:Application) WHERE a.id ENDS WITH "/" + $app '
-            "MATCH (a)-[:TS_HAS_MODULE]->(m:TSModule) RETURN m._module AS k",
+            'MATCH (a:Application) WHERE a.id ENDS WITH "/" + $app RETURN a.id AS id ORDER BY id',
             app=self.application_name,
         )
+        if not rows:
+            raise CodeanalyzerUsageException(
+                f"no :Application found whose id ends with '/{self.application_name}' — check application_name (the --app-name the graph was loaded with)."
+            )
+        if len(rows) > 1:
+            candidates = ", ".join(r["id"] for r in rows)
+            raise CodeanalyzerUsageException(
+                f"application_name '{self.application_name}' is ambiguous: it matches {len(rows)} applications in this database ({candidates}). "
+                "Pass a longer trailing path of the intended application's id to disambiguate."
+            )
+        return rows[0]["id"]
+
+    def _load_module_keys(self) -> List[str]:
+        # VERIFY(2.0.0-e2e): every project-owned node is assumed to carry a `_module` provenance
+        # property (as in the pre-2.0.0 projection); all the `x._module IN $mods` scoping below
+        # depends on it — validate against a live 1.0.0 graph (Task 9).
+        rows = self._run(
+            "MATCH (a:Application {id: $app_id})-[:TS_HAS_MODULE]->(m:TSModule) RETURN m._module AS k",
+            app_id=self._app_id,
+        )
         return [r["k"] for r in rows]
 
     # -----[ child-fetch helpers (reconstruction) ]-----
@@ -195,7 +231,7 @@ def _callsites_of(self, signature: str) -> List[TSCallsite]:
 
     def _callable_full(self, props: Dict[str, Any]) -> TSCallable:
         sig = props["signature"]
-        # Symbol-keyed containers are keyed by signature (matching the analyzer's dict keys).
+        # Nested-declaration containers are keyed by signature (matching the analyzer's dict keys).
         inner_callables = {p["signature"]: self._callable_full(p) for p in self._children(sig, "TS_DECLARES", "TSCallable")}
         inner_classes = {p["signature"]: self._class_full(p) for p in self._children(sig, "TS_DECLARES", "TSClass")}
         return R.callable_(
@@ -309,7 +345,7 @@ def get_typescript_module(self, file_path: str) -> TSModule | None:
         if not rows:
             return None
         props = rows[0]["p"]
-        # All symbol containers are keyed by signature (matching the analyzer's dict keys).
+        # All declaration containers are keyed by signature (matching the analyzer's dict keys).
         classes = {p["signature"]: self._class_full(p) for p in self._module_decls(file_path, "TSClass")}
         interfaces = {p["signature"]: self._interface_full(p) for p in self._module_decls(file_path, "TSInterface")}
         enums = {p["signature"]: R.enum(p) for p in self._module_decls(file_path, "TSEnum")}
@@ -488,6 +524,10 @@ def get_class_call_graph(self, qualified_class_name: str, method_signature: str
 
     def get_class_hierarchy(self) -> nx.DiGraph:
         """Inheritance/implementation graph: an edge child → base for every base_class."""
+        # VERIFY(2.0.0-e2e): hierarchy is read from the `base_classes` / `implements_types` array
+        # properties (as pre-2.0.0), not the TS_EXTENDS / TS_IMPLEMENTS edges — validate against a
+        # live 1.0.0 graph (Task 9); this also covers get_extended_classes,
+        # get_implemented_interfaces and get_all_sub_classes.
         graph = nx.DiGraph()
         rows = self._run(
             "MATCH (n:CanNode) WHERE (n:TSClass OR n:TSInterface) AND n._module IN $mods " "RETURN n.signature AS sig, n.base_classes AS bases",
@@ -513,6 +553,9 @@ def get_calling_lines(self, target_signature: str) -> List[int]:
         return [r["line"] for r in rows]
 
     def get_call_targets(self, source_signature: str) -> Set[str]:
+        # VERIFY(2.0.0-e2e): falls back to `cs.method_name` when a call body node has no resolved
+        # `callee`; whether TSBodyNode carries `method_name` is unconfirmed — validate against a
+        # live 1.0.0 graph (Task 9).
         rows = self._run(
             "MATCH (c:TSCallable {signature: $sig})-[:TS_HAS_BODY_NODE]->(cs:TSBodyNode {kind: 'call'}) " "RETURN cs.callee AS cosig, cs.method_name AS mn",
             sig=source_signature,

cldk/analysis/typescript/neo4j/reconstruct.py

@@ -373,6 +373,8 @@ def module(props: Props, **children: Any) -> TSModule:
     return TSModule(
         # schema 2.0.0 modules carry the project-relative path as ``_module``.
         file_path=props.get("_module", props.get("file_path", "")),
+        # VERIFY(2.0.0-e2e): assumes the 2.0.0 module node names the module via `name` (falling
+        # back from the pre-2.0.0 `module_name`) — validate against a live 1.0.0 graph (Task 9).
         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),

cldk/utils/exceptions/__init__.py

@@ -20,10 +20,12 @@
 
 from .exceptions import (
     CldkInitializationException,
+    CldkSchemaMismatchException,
     CodeanalyzerExecutionException,
 )
 
 __all__ = [
     "CodeanalyzerExecutionException",
     "CldkInitializationException",
+    "CldkSchemaMismatchException",
 ]

tests/analysis/typescript/test_typescript_neo4j_schema.py

@@ -16,21 +16,25 @@
 
 """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:
+Four 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 application-id resolution guard (``_resolve_application_id``) — the suffix match must bind
+  exactly one ``:Application`` or raise, never silently merge two apps' module scopes;
 * 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.
+  ``NotImplementedError`` rather than silently returning wrong data;
+* the constructed Cypher for the two riskiest 2.0.0 rewrites (the call-site body-node path and
+  module `_module` scoping) — behavioral verification against a live graph is Task 9's e2e run.
 
-Both are tested against a bare ``__new__`` instance (no ``__init__``, so no driver), because the
+All 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
+from cldk.utils.exceptions.exceptions import CldkSchemaMismatchException, CodeanalyzerUsageException
 
 
 def _bare_backend() -> TSNeo4jBackend:
@@ -70,6 +74,104 @@ def test_schema_version_absent_fails_fast(monkeypatch):
         backend._check_schema_version(expected="2.0.0")
 
 
+# -----[ application-id resolution guard ]-----
+def test_resolve_application_id_unique_match(monkeypatch):
+    backend = _bare_backend()
+    backend.application_name = "frontend"
+    monkeypatch.setattr(backend, "_run", lambda *a, **k: [{"id": "can://repo-a/frontend"}])
+    assert backend._resolve_application_id() == "can://repo-a/frontend"
+
+
+def test_resolve_application_id_no_match_raises(monkeypatch):
+    backend = _bare_backend()
+    backend.application_name = "frontend"
+    monkeypatch.setattr(backend, "_run", lambda *a, **k: [])
+    with pytest.raises(CodeanalyzerUsageException, match="no :Application found"):
+        backend._resolve_application_id()
+
+
+def test_resolve_application_id_ambiguous_raises_naming_candidates(monkeypatch):
+    backend = _bare_backend()
+    backend.application_name = "frontend"
+    monkeypatch.setattr(
+        backend,
+        "_run",
+        lambda *a, **k: [{"id": "can://repo-a/frontend"}, {"id": "can://repo-b/frontend"}],
+    )
+    with pytest.raises(CodeanalyzerUsageException) as exc_info:
+        backend._resolve_application_id()
+    message = str(exc_info.value)
+    assert "ambiguous" in message
+    assert "can://repo-a/frontend" in message
+    assert "can://repo-b/frontend" in message
+
+
+# -----[ constructed-Cypher shape for the riskiest 2.0.0 rewrites ]-----
+def _recording_backend(monkeypatch):
+    """A bare backend whose ``_run`` records every (query, params) call and returns no rows."""
+    backend = _bare_backend()
+    backend._modules = ["src/mod.ts"]
+    calls = []
+
+    def _run(query, **params):
+        calls.append((query, params))
+        return []
+
+    monkeypatch.setattr(backend, "_run", _run)
+    return backend, calls
+
+
+def test_call_site_query_uses_body_node_path(monkeypatch):
+    backend, calls = _recording_backend(monkeypatch)
+    backend.get_call_sites("src/mod.Foo.bar")
+    (query, params), = calls
+    assert "-[:TS_HAS_BODY_NODE]->" in query
+    assert "TSBodyNode {kind: 'call'}" in query
+    assert params == {"sig": "src/mod.Foo.bar"}
+
+
+def test_calling_lines_query_reads_callee_property(monkeypatch):
+    backend, calls = _recording_backend(monkeypatch)
+    backend.get_calling_lines("src/mod.Foo.bar")
+    (query, _), = calls
+    assert "TSBodyNode {kind: 'call'}" in query
+    assert "cs.callee = $sig" in query
+
+
+def test_call_targets_query_reads_callee_property(monkeypatch):
+    backend, calls = _recording_backend(monkeypatch)
+    backend.get_call_targets("src/mod.Foo.bar")
+    (query, _), = calls
+    assert "-[:TS_HAS_BODY_NODE]->" in query
+    assert "cs.callee AS" in query
+
+
+def test_external_symbols_query_resolves_via_body_nodes(monkeypatch):
+    backend, calls = _recording_backend(monkeypatch)
+    backend.get_external_symbols()
+    (query, _), = calls
+    assert "-[:TS_CALLS]->(e:TSExternal)" in query
+    assert "(cs:TSBodyNode {kind: 'call'})-[:TS_RESOLVES_TO]->(e:TSExternal)" in query
+
+
+def test_module_lookup_query_keys_on_module_property(monkeypatch):
+    backend, calls = _recording_backend(monkeypatch)
+    assert backend.get_typescript_module("src/mod.ts") is None  # no rows stubbed
+    (query, params), = calls
+    assert "TSModule {_module: $key}" in query
+    assert params == {"key": "src/mod.ts"}
+
+
+def test_module_keys_query_scoped_to_resolved_application_id(monkeypatch):
+    backend, calls = _recording_backend(monkeypatch)
+    backend._app_id = "can://repo-a/frontend"
+    backend._load_module_keys()
+    (query, params), = calls
+    assert "Application {id: $app_id}" in query
+    assert "-[:TS_HAS_MODULE]->" in query
+    assert params == {"app_id": "can://repo-a/frontend"}
+
+
 # -----[ accessors with no graph support in schema 2.0.0 ]-----
 _FALLBACK_CALLS = [
     ("get_decorators", ("src/x.f",)),