feat(typescript): four bulk/projected accessors on the TS surface (#298) (#302)

* feat(typescript): TSCallableOverview projection model (#298)

* fix(typescript): close owner_kind to class|interface; require facet fields (#298)

* feat(typescript): bulk accessors on the ABC, in-memory backend, and facade (#298)

* feat(typescript): bulk accessors on the Neo4j backend (#298)

* fix(typescript): get_method_bodies omits code-less callables (#298)

* test(typescript): pin overview Cypher shape in Neo4j bulk stub tests (#298)

* test(typescript): dual-backend parity for the bulk accessors (#298)

* test(typescript): track the blessed slim analysis fixture (#298)

tests/resources/typescript/analysis_json/slim/analysis.json was caught by the
blanket *.json gitignore rule and never committed, even though the TS bulk
accessor tests assert exact-set constants against it and it was hand-built
from a src/external.ts that was itself never committed -- so a fresh clone
could neither run the suite nor regenerate the fixture. Add a narrow
.gitignore exception and track the file.

* docs(typescript): note accessor-pair limitation; file parity issue (#298)

get x()/set x() pairs share one TSCallable.signature, so the in-memory
backend's last-writer-wins _callables map collapses the pair to a single
row while the Neo4j backend (one node per accessor) surfaces two -- and
duplicate decorator names diverge the same way via collect(DISTINCT ...).
Invisible on the current sample-app fixture (unpaired getter only), but the
live parity suite would catch it on any app with a real paired accessor.
Filed as #300; note it on the ABC and facade
get_callables_overview docstrings, and record that decorator order isn't
part of the cross-backend contract.

* chore(typescript): exact ownerless set, direct lookups, delegation test, decorator-order note (#298)

- test_overview_owner_pair_is_none_for_ownerless_callables: fix the
  "owned_less" typo and assert the ownerless signature set exactly, not
  just membership.
- get_method_bodies / get_callsites_for: replace the O(all callables) walk
  via _iter_callables() with direct _callables.get(sig) lookups keyed on
  the requested signatures; omission/empty-entry semantics unchanged
  (covering tests stay green).
- test_facade_delegates_to_backend: replace the same-fixture double-call
  (which only proved the fixture is deterministic) with a MagicMock-backed
  facade asserting each bulk accessor calls the identical backend method
  with the identical arguments and returns its exact object.

Author: rahlk

.gitignore

@@ -53,6 +53,12 @@ scratch*
 *.json
 !devcontainer.json
 
+# Blessed TS unit-test fixture: hand-built from a sample app whose source (incl. src/external.ts)
+# was never committed, so it cannot be regenerated by running codeanalyzer-typescript again. The
+# bulk-accessor tests assert exact-set constants (signature counts, ownerless sets) against this
+# exact file -- losing it breaks the suite for every fresh clone (#298).
+!tests/resources/typescript/analysis_json/slim/analysis.json
+
 
 # Python compiled files and env
 __pycache__/

cldk/analysis/typescript/backend.py

@@ -44,6 +44,7 @@
 from cldk.models.typescript import (
     TSApplication,
     TSCallable,
+    TSCallableOverview,
     TSCallsite,
     TSClass,
     TSClassAttribute,
@@ -244,3 +245,35 @@ def get_methods_with_decorators(self, decorators: List[str]) -> Dict[str, List[s
     @abstractmethod
     def get_classes_with_decorators(self, decorators: List[str]) -> Dict[str, List[str]]:
         """Map each requested decorator name to the signatures of classes carrying it."""
+
+    # -----[ bulk / projected accessors ]-----
+    # Set-at-a-time, field-projected reads — one round-trip on the Neo4j backend, one symbol-table
+    # walk in-process — for callers that enumerate the whole application and would otherwise pay the
+    # per-entity reconstruction of get_all_methods_in_application.
+    @abstractmethod
+    def get_callables_overview(self) -> List[TSCallableOverview]:
+        """A lightweight projection of every callable in the application (methods, module-level,
+        namespace-level, and nested/inner functions), without the full :class:`TSCallable`
+        reconstruction.
+
+        Known limitation: a ``get x()``/``set x()`` accessor pair shares one ``signature``, so
+        this (and the other bulk accessors) can diverge between backends on a paired accessor —
+        see `#300 <https://github.com/codellm-devkit/python-sdk/issues/300>`_."""
+
+    @abstractmethod
+    def get_method_bodies(self, signatures: List[str]) -> Dict[str, str]:
+        """Source bodies for the given callable signatures, keyed by signature. Signatures with no
+        matching callable are omitted, as are callables whose ``code`` is ``None`` (e.g. implicit
+        constructors the analyzer synthesizes with no source text) — every returned value is a
+        real ``str``."""
+
+    @abstractmethod
+    def get_decorated_callables(self, markers: List[str]) -> List[TSCallableOverview]:
+        """Overviews of callables decorated with any of ``markers`` (matched against the decorator
+        names)."""
+
+    @abstractmethod
+    def get_callsites_for(self, signatures: List[str]) -> Dict[str, List[TSCallsite]]:
+        """Call sites of the given callable signatures, keyed by owning signature. Each existing
+        signature gets an entry (an empty list if it has no call sites); signatures with no matching
+        callable are omitted."""

cldk/analysis/typescript/codeanalyzer/codeanalyzer.py

@@ -33,7 +33,7 @@
 from collections import deque
 from pathlib import Path
 from subprocess import CompletedProcess
-from typing import Dict, List, Set, Tuple, Union
+from typing import Dict, Iterator, List, Set, Tuple, Union
 
 import networkx as nx
 
@@ -42,6 +42,7 @@
 from cldk.models.typescript import (
     TSApplication,
     TSCallable,
+    TSCallableOverview,
     TSCallsite,
     TSClass,
     TSClassAttribute,
@@ -554,3 +555,57 @@ def get_classes_with_decorators(self, decorators: List[str]) -> Dict[str, List[s
                 if dec.name in wanted:
                     result[dec.name].append(sig)
         return result
+
+    # -----[ bulk / projected accessors ]-----
+    def _iter_callables(self) -> Iterator[Tuple[TSCallable, str | None, str | None]]:
+        """Yield ``(callable, owner_signature, owner_kind)`` for every callable in the
+        application, including inner/nested callables. The owner map is built only from
+        ``_methods_by_class`` keyed against ``_classes``/``_interfaces``: namespace-owned
+        functions and module-level/nested callables are never in that map, so they correctly come
+        out owner-less (None, None), per the closed "class"|"interface" owner_kind set."""
+        owner_of: Dict[str, Tuple[str, str]] = {}
+        for owner_sig, methods in self._methods_by_class.items():
+            if owner_sig in self._classes:
+                owner_kind = "class"
+            elif owner_sig in self._interfaces:
+                owner_kind = "interface"
+            else:
+                continue
+            for m in methods.values():
+                owner_of[m.signature] = (owner_sig, owner_kind)
+        for sig, c in self._callables.items():
+            owner_sig, owner_kind = owner_of.get(sig, (None, None))
+            yield c, owner_sig, owner_kind
+
+    def get_callables_overview(self) -> List[TSCallableOverview]:
+        """Return a lightweight overview of every callable in the application (see
+        :meth:`TSAnalysisBackend.get_callables_overview`)."""
+        return [TSCallableOverview.from_callable(c, owner_sig, owner_kind) for c, owner_sig, owner_kind in self._iter_callables()]
+
+    def get_method_bodies(self, signatures: List[str]) -> Dict[str, str]:
+        """Return ``{signature: code}`` for the requested signatures that exist and have a body
+        (omits callables whose ``code`` is ``None``, e.g. implicit constructors)."""
+        result: Dict[str, str] = {}
+        for sig in signatures:
+            c = self._callables.get(sig)
+            if c is not None and c.code is not None:
+                result[sig] = c.code
+        return result
+
+    def get_decorated_callables(self, markers: List[str]) -> List[TSCallableOverview]:
+        """Return overviews of callables decorated with any of ``markers``."""
+        marker_set = set(markers)
+        return [
+            TSCallableOverview.from_callable(c, owner_sig, owner_kind)
+            for c, owner_sig, owner_kind in self._iter_callables()
+            if marker_set.intersection(d.name for d in c.decorators)
+        ]
+
+    def get_callsites_for(self, signatures: List[str]) -> Dict[str, List[TSCallsite]]:
+        """Return ``{signature: call_sites}`` for the requested signatures that exist."""
+        result: Dict[str, List[TSCallsite]] = {}
+        for sig in signatures:
+            c = self._callables.get(sig)
+            if c is not None:
+                result[sig] = list(c.call_sites)
+        return result

cldk/analysis/typescript/neo4j/neo4j_backend.py

@@ -63,6 +63,7 @@
 from cldk.models.typescript import (
     TSApplication,
     TSCallable,
+    TSCallableOverview,
     TSCallEdge,
     TSCallsite,
     TSClass,
@@ -710,3 +711,66 @@ def get_classes_with_decorators(self, decorators: List[str]) -> Dict[str, List[s
         for r in rows:
             result[r["dn"]].append(r["sig"])
         return result
+
+    # -----[ bulk / projected accessors ]-----
+    # Field-projected RETURNs that sidestep the per-entity reconstruction fan-out: each is a single
+    # Cypher statement (one round trip), not the child-fetch walk _callable_full pays.
+    #
+    # Owner leg: (o:Symbol)-[:HAS_METHOD]->(c) only ever connects a Class/Interface owner to one of
+    # its methods, so it naturally has no match for module-level, namespace-owned, or nested
+    # callables -- they fall out owner-less (None/None) with no separate namespace leg needed.
+    _OVERVIEW_RETURN = (
+        "OPTIONAL MATCH (o:Symbol)-[:HAS_METHOD]->(c) "
+        "OPTIONAL MATCH (c)-[:DECORATED_BY]->(d:Decorator) "
+        "RETURN c.signature AS signature, c.name AS name, c.kind AS kind, c.path AS path, "
+        "c.start_line AS start_line, c.end_line AS end_line, "
+        "c.is_exported AS is_exported, c.is_async AS is_async, c.is_static AS is_static, "
+        "c.accessibility AS accessibility, "
+        "o.signature AS owner_signature, labels(o) AS owner_labels, "
+        "collect(DISTINCT d.name) AS decorators"
+    )
+
+    def get_callables_overview(self) -> List[TSCallableOverview]:
+        rows = self._run(
+            "MATCH (c:Callable) WHERE c._module IN $mods " + self._OVERVIEW_RETURN,
+            mods=self._modules,
+        )
+        return [R.overview(r) for r in rows]
+
+    def get_method_bodies(self, signatures: List[str]) -> Dict[str, str]:
+        rows = self._run(
+            "MATCH (c:Callable) WHERE c._module IN $mods AND c.signature IN $sigs AND c.code IS NOT NULL "
+            "RETURN c.signature AS signature, c.code AS code",
+            mods=self._modules,
+            sigs=list(signatures),
+        )
+        return {r["signature"]: r["code"] for r in rows}
+
+    def get_decorated_callables(self, markers: List[str]) -> List[TSCallableOverview]:
+        rows = self._run(
+            "MATCH (c:Callable)-[:DECORATED_BY]->(marker:Decorator) "
+            "WHERE c._module IN $mods AND marker.name IN $markers "
+            "WITH DISTINCT c " + self._OVERVIEW_RETURN,
+            mods=self._modules,
+            markers=list(markers),
+        )
+        return [R.overview(r) for r in rows]
+
+    def get_callsites_for(self, signatures: List[str]) -> Dict[str, List[TSCallsite]]:
+        # OPTIONAL MATCH so a requested callable with no call sites still yields a row (p is null),
+        # giving it an empty-list entry -- parity with the in-process backend, which keys every
+        # existing signature. ORDER mirrors _callsites_of's call-site ordering.
+        rows = self._run(
+            "MATCH (c:Callable) WHERE c._module IN $mods AND c.signature IN $sigs "
+            "OPTIONAL MATCH (c)-[:HAS_CALLSITE]->(cs:CallSite) "
+            "RETURN c.signature AS owner, properties(cs) AS p "
+            "ORDER BY cs.start_line, cs.start_column",
+            mods=self._modules,
+            sigs=list(signatures),
+        )
+        out: Dict[str, List[TSCallsite]] = {}
+        for r in rows:
+            sites = out.setdefault(r["owner"], [])
+            if r["p"] is not None:
+                sites.append(R.callsite(r["p"]))
+        return out

cldk/analysis/typescript/neo4j/reconstruct.py

@@ -40,6 +40,7 @@
 
 from cldk.models.typescript import (
     TSCallable,
+    TSCallableOverview,
     TSCallableParameter,
     TSCallsite,
     TSClass,
@@ -191,6 +192,45 @@ def synthesized(props: Props) -> TSSynthesizedCallable:
     )
 
 
+def overview(row: Props) -> TSCallableOverview:
+    """Build a :class:`TSCallableOverview` from a projected callable row (a flat ``RETURN``
+    projection, not a node's ``properties()``): ``signature``/``name``/``kind``/``path``/
+    ``start_line``/``end_line``/``is_exported``/``is_async``/``is_static``/``accessibility`` plus
+    ``owner_signature``/``owner_labels`` (the ``HAS_METHOD`` owner leg — absent, i.e. both null,
+    for module-level/namespace-owned/nested callables) and ``decorators`` (collected decorator
+    names).
+
+    ``owner_kind`` is derived from ``owner_labels`` rather than stored directly: ``"class"`` if the
+    owner node carries the ``Class`` label, ``"interface"`` if it carries ``Interface``, else
+    ``None`` — matching the closed two-value ``owner_kind`` set the in-memory backend produces.
+    """
+    owner_signature = row.get("owner_signature")
+    owner_labels = row.get("owner_labels") or []
+    if owner_signature is None:
+        owner_kind = None
+    elif "Class" in owner_labels:
+        owner_kind = "class"
+    elif "Interface" in owner_labels:
+        owner_kind = "interface"
+    else:
+        owner_kind = None
+    return TSCallableOverview(
+        signature=row.get("signature", ""),
+        name=row.get("name", ""),
+        owner_signature=owner_signature,
+        owner_kind=owner_kind,
+        kind=row.get("kind", "function"),
+        path=row.get("path", ""),
+        start_line=row.get("start_line", -1),
+        end_line=row.get("end_line", -1),
+        decorators=[d for d in (row.get("decorators") or []) if d is not None],
+        is_exported=bool(row.get("is_exported", False)),
+        is_async=bool(row.get("is_async", False)),
+        is_static=bool(row.get("is_static", False)),
+        accessibility=row.get("accessibility"),
+    )
+
+
 # ----------------------------------------------------------------------------------------------
 # declaration nodes (children supplied by the backend)
 # ----------------------------------------------------------------------------------------------

cldk/analysis/typescript/typescript_analysis.py

@@ -36,6 +36,7 @@
 from cldk.models.typescript import (
     TSApplication,
     TSCallable,
+    TSCallableOverview,
     TSCallsite,
     TSClass,
     TSClassAttribute,
@@ -297,3 +298,75 @@ def get_methods_with_decorators(self, decorators: List[str]) -> Dict[str, List[s
     def get_classes_with_decorators(self, decorators: List[str]) -> Dict[str, List[str]]:
         """Map each requested decorator name to the signatures of classes carrying it."""
         return self.backend.get_classes_with_decorators(decorators)
+
+    # -----[ bulk / projected accessors ]-----
+    def get_callables_overview(self) -> List[TSCallableOverview]:
+        """Return a lightweight overview of every callable in the project, in one bulk read.
+
+        A field-projected alternative to :meth:`get_methods` for enumeration: each
+        :class:`~cldk.models.typescript.TSCallableOverview` carries the callable's signature,
+        owning class/interface (if any), native kind, location, and decorators — but not the full
+        reconstruction (call sites, inner callables, locals). On the Neo4j backend this is a single
+        Cypher query instead of the per-entity fan-out :meth:`get_methods` pays. Body-inspect the
+        few you need afterwards via :meth:`get_method` or :meth:`get_method_bodies`.
+
+        Returns:
+            A flat list of :class:`~cldk.models.typescript.TSCallableOverview`, one per callable
+            (class/interface methods, module- and namespace-level functions, and nested/inner
+            callables).
+
+        See Also:
+            :meth:`get_decorated_callables`: The same projection filtered by decorator.
+            :meth:`get_method_bodies`: Bulk source-body fetch for chosen signatures.
+
+        Note:
+            A ``get x()``/``set x()`` accessor pair shares one ``signature``, so this projection
+            (and the other bulk accessors) can diverge between the local and Neo4j backends on a
+            paired accessor — see `#300 <https://github.com/codellm-devkit/python-sdk/issues/300>`_.
+        """
+        return self.backend.get_callables_overview()
+
+    def get_method_bodies(self, signatures: List[str]) -> Dict[str, str]:
+        """Return source bodies for the given callable signatures, in one bulk read.
+
+        Args:
+            signatures: Callable signatures to fetch bodies for (e.g. from
+                :meth:`get_callables_overview`).
+
+        Returns:
+            A dict mapping each signature to its source body. Signatures with no matching callable
+            are omitted, as are callables whose ``code`` is ``None`` (e.g. implicit constructors
+            the analyzer synthesizes with no source text) — every returned value is a real ``str``.
+        """
+        return self.backend.get_method_bodies(signatures)
+
+    def get_decorated_callables(self, markers: List[str]) -> List[TSCallableOverview]:
+        """Return overviews of callables decorated with any of the given markers, in one bulk read.
+
+        Args:
+            markers: Decorator names to match (e.g. ``["Get", "Controller"]``).
+
+        Returns:
+            A list of :class:`~cldk.models.typescript.TSCallableOverview` for every callable
+            carrying at least one of ``markers`` as a decorator.
+
+        See Also:
+            :meth:`get_callables_overview`: The unfiltered projection.
+        """
+        return self.backend.get_decorated_callables(markers)
+
+    def get_callsites_for(self, signatures: List[str]) -> Dict[str, List[TSCallsite]]:
+        """Return the call sites of the given callables, keyed by signature, in one bulk read.
+
+        Avoids the per-callable reconstruction fan-out when you need call sites for a specific
+        frontier (e.g. dispatch-edge synthesis or external-reader detection).
+
+        Args:
+            signatures: Callable signatures to fetch call sites for.
+
+        Returns:
+            A dict mapping each existing signature to its list of
+            :class:`~cldk.models.typescript.TSCallsite` (empty if the callable has no call sites).
+            Signatures with no matching callable are omitted.
+        """
+        return self.backend.get_callsites_for(signatures)

cldk/models/typescript/__init__.py

@@ -42,11 +42,13 @@
     TSTypeParameter,
     TSVariableDeclaration,
 )
+from .projections import TSCallableOverview
 
 __all__ = [
     "TSApplication",
     "TSCallEdge",
     "TSCallable",
+    "TSCallableOverview",
     "TSCallableParameter",
     "TSCallsite",
     "TSClass",