feat(python): leg 1.5 — bounded queries, addressing, and dataflow (#323)

feat(python): leg 1.5 — bounded queries, addressing, and dataflow

Author: rahlk

CHANGELOG.md

@@ -288,6 +288,10 @@ def overview(row: Props) -> PyCallableOverview:
     ``row`` is a flat ``RETURN`` projection (not a node's ``properties()``): ``signature``, ``name``,
     ``decorators``, ``path``, ``start_line``, ``end_line``, and ``class_signature`` (the owning
     class via ``PY_HAS_METHOD``, or ``None`` for a module-level / nested function).
+
+    ``path`` is projected from ``:PyCallable._module`` — the repo-relative module key, the same
+    vocabulary :func:`class_overview` and ``locate`` speak — *not* ``:PyCallable.path``, which is
+    the absolute path on the machine that ran the analysis.
     """
     class_sig = row.get("class_signature")
     return PyCallableOverview(

cldk/analysis/commons/resolve.py

@@ -19,13 +19,19 @@
 """
 
 from .exceptions import (
+    AmbiguousName,
     CldkInitializationException,
     CodeanalyzerExecutionException,
+    CodeanalyzerUsageException,
     GraphSchemaMismatch,
+    SelectorNotInGraph,
 )
 
 __all__ = [
+    "AmbiguousName",
     "CodeanalyzerExecutionException",
+    "CodeanalyzerUsageException",
     "CldkInitializationException",
     "GraphSchemaMismatch",
+    "SelectorNotInGraph",
 ]

cldk/analysis/commons/results.py

@@ -138,6 +138,106 @@ def _describe(expected: set[str], found: set[str], missing: set[str]) -> str:
         return f"Graph schema mismatch: expected relationship types {sorted(expected)}, missing {sorted(missing)}. Found on the graph: {sorted(found)}. {generation}"
 
 
+class SelectorNotInGraph(ValueError):
+    """Raised when a scoping keyword names something the analysed application does not hold.
+
+    ``get_symbol_table(paths=...)``, ``get_classes(module=...)`` and ``get_call_graph(roots=...)``
+    all narrow a whole-application enumeration to a caller-supplied selection. A value in that
+    selection which matches nothing used to contribute nothing, so a typo'd path and a module that
+    genuinely declares no classes were the *same* empty dict — the ambiguous-empty defect the
+    query facade exists to remove (D7). Raising makes them different answers.
+
+    The message names the values that matched nothing and stops there. It deliberately offers no
+    near-miss candidates: leg 1.5's E8 puts typo-tolerant matching out of scope "not in the
+    resolver, not in the error path", because a suggestion is a guess, and a guess presented as a
+    correction is the confident-wrong-answer failure this design exists to prevent.
+
+    Subclasses :class:`ValueError` because that is what these accessors already document raising
+    for a malformed scoping keyword (an empty selection, a ``depth`` below 1) — an unmatched value
+    is the same class of caller error, not a new one, and a caller catching ``ValueError`` around a
+    scoped call keeps working.
+
+    Attributes:
+        kind (str): Which keyword named them — ``"paths"``, ``"module"`` or ``"roots"``.
+        missing (list[str]): The values, as the caller wrote them, that matched nothing.
+        requested (int): How many values the keyword carried in total, so a partial miss is
+            visible as a partial miss.
+    """
+
+    def __init__(self, kind: str, missing: list[str], requested: int, *, detail: str | None = None) -> None:
+        """Initialize with the keyword, the values that missed, and how many were asked for.
+
+        Args:
+            kind: The scoping keyword's name (``"paths"`` / ``"module"`` / ``"roots"``), or the
+                thing a name-taking accessor failed to resolve (``"callable"`` / ``"value"`` /
+                ``"in_class"`` / ``"in_module"``).
+            missing: The unmatched values, in the caller's own spelling.
+            requested: The total number of values the keyword carried.
+            detail: An optional sentence appended in parentheses: what the caller can do instead,
+                or which *other* argument the miss is relative to. Never a near-miss suggestion.
+        """
+        self.kind = kind
+        self.missing = list(missing)
+        self.requested = requested
+        self.detail = detail
+        self.message = f"{len(self.missing)} of {requested} {kind} not in graph: " + ", ".join(repr(m) for m in self.missing)
+        if detail:
+            self.message += f" ({detail})"
+        super().__init__(self.message)
+
+
+class AmbiguousName(ValueError):
+    """Raised when a name the caller wrote matches more than one thing, listing every match.
+
+    The addressing layer (leg 1.5, E6-E8) lets a caller name a callable or a value the way it
+    already thinks of it rather than assembling the analyzer's ``can://`` id. Names are a viable
+    address -- 86% of this application's leaf callable names are unique -- but the remainder are
+    framework methods (``__init__`` 238, ``write`` 220, ``create`` 214), and there picking one is a
+    confident wrong answer with no signal to the caller. So the resolver never picks: it raises,
+    and hands back the matches as data.
+
+    Like :class:`SelectorNotInGraph`, it offers no near-miss suggestions -- every string in
+    ``candidates`` genuinely matched the name as written. E8 puts typo-tolerant matching out of
+    scope "not in the resolver, not in the error path", so there is no scoring, no edit distance,
+    and nothing here that was not a real match.
+
+    ``candidates`` carries **all** of them, because that is the data a caller may want to filter
+    programmatically; ``message`` shows only the first few plus a total, because two hundred
+    strings in a traceback is not an error message a person can act on. The message also names the
+    keyword that narrows it -- an error that says what to do next costs nothing extra to write.
+
+    Subclasses :class:`ValueError` for the same reason :class:`SelectorNotInGraph` does: an
+    unusable name is a caller error, and a caller already catching ``ValueError`` around a
+    resolution keeps working.
+
+    Attributes:
+        name (str): The name as the caller wrote it.
+        candidates (list[str]): Every match, in a deterministic (sorted) order.
+        kind (str): What was being resolved -- ``"callable"`` or ``"value"``.
+    """
+
+    #: How many candidates the message shows before falling back to a count.
+    SHOWN = 5
+
+    def __init__(self, name: str, candidates: list[str], *, kind: str = "callable", narrow_with: str = "in_class= or in_module=") -> None:
+        """Initialize with the name, every match, and how a caller narrows it.
+
+        Args:
+            name: The name as the caller wrote it.
+            candidates: Every candidate that matched it.
+            kind: What was being resolved (``"callable"`` / ``"value"``), for the message.
+            narrow_with: The keyword(s) that would disambiguate, named in the message.
+        """
+        self.name = name
+        self.candidates = sorted(candidates)
+        self.kind = kind
+        shown = self.candidates[: self.SHOWN]
+        more = len(self.candidates) - len(shown)
+        listed = "; ".join(repr(c) for c in shown) + (f"; ... and {more} more" if more else "")
+        self.message = f"{name!r} is ambiguous: {len(self.candidates)} {kind}s match. Narrow it with {narrow_with}. Matches: {listed}"
+        super().__init__(self.message)
+
+
 class CodeanalyzerUsageException(Exception):
     """Exception raised for incorrect CodeAnalyzer usage.