descry-codegraph 0.3.1__tar.gz → 0.3.2__tar.gz

{descry_codegraph-0.3.1 → descry_codegraph-0.3.2}/CHANGELOG.md

@@ -6,6 +6,99 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.3.2] — 2026-10-23
+
+### Fixed
+
+- A caller that reaches a symbol only as one of an unresolved call's
+  candidates is counted apart from its callers. `in_degree` ("N callers")
+  counts the callers whose calls are resolved to the symbol, and is
+  counted again as a graph loads, so a graph from 0.3.1 needs no reindex.
+  Every other count gives the others as "(+N possible)": brief `context`
+  (callers and callees), `callers`, `callees`, and the web page's headers
+  (`possible` in the web API). Lists mark each one; `changes` does so in
+  text, in its structured form (`candidates`, `callers_possible`) and on
+  the page.
+- A function no longer counts as a certain caller of a symbol it defines
+  when its call to it is unresolved.
+- A node ID names that node alone: `callers`, `callees`, `quick`, `flow`
+  and `path` given one no longer also match other definitions filed under
+  the same owner and name (a Ruby `self.x` beside `x`).
+- `context`'s usage examples are calls of that symbol, those resolved to
+  it first, then those it is one of the candidates of, marked; they were
+  any unresolved call ending in its name.
+- `callers` of a name lists the calls the resolver left unresolved with no
+  candidates apart from its callers, marked "(unresolved; same name)" and
+  counted as "+N unresolved" (`unresolved` in the web API). Some are calls
+  of the project's definition the resolver cannot follow (a Rust re-export,
+  a TypeScript static member), some are calls of something else with that
+  name (`loader.list_templates()` on a library's loader). Neither is
+  counted as a caller. An unresolved call with candidates reaches only
+  those. Callers asked for by node ID are those resolved to it or narrowed
+  to it.
+- A list cut short (`callers`, `callees`, `context`'s callers, `changes`,
+  backward `flow` in text and as a tree) keeps the callers resolved to the
+  symbol first, and says how many it leaves out and how many of those only
+  may be; a `flow` tree node gives them as `more` and `more_possible`, and
+  the web API's `callers` and `callees` as `more`, shown on the page.
+- `flow`, in text and as a tree, places each symbol at the first level
+  that reaches it and marks it "(at level N)" where it is met again
+  (`seen`, that level, in the tree); a direct callee or caller reached
+  first through another one was dropped from its level, with everything
+  below it. `context`, at every depth, lists all of the symbol's own
+  callees and cuts each level below to the per-level limit with a note; it
+  opens a callee (inlines it and lists its own callees) at the first level
+  that reaches it while the token budget covers it, lists every other
+  callee by its signature or "(at level N)", and says when the budget, the
+  node limit or the timeout cut it short. Depth 1 ignored `max_tokens`. A
+  `flow` that stops early says so: "(timeout)" or "(node limit)" in text,
+  `cut` in the tree, a note on the page.
+- A `flow` of `depth` N shows N levels of calls below the start; `depth=1`
+  showed the start alone. `[query] max_depth` is that many levels too, for
+  `flow` and for `context`'s callee expansion. A depth past it is traced to
+  it and says so; the web API returns the depth traced, and `/api/health`
+  gives the ceiling the page's depth field is held to.
+- A callee the resolver left unresolved is no longer shown or counted as
+  certain or as external. `context`, at every depth, names it as one of
+  its candidates, or "(unresolved)" where it found none. `callees` marks
+  it the same way and counts it apart ("+N unresolved"). A callee is what
+  a call is written as: calls written apart (`a.add`, `b.add`) are two
+  callees, and calls written alike may reach any definition one of them
+  is narrowed to. Forward `flow` follows a possible callee to each
+  definition it may reach, marked, and `context` at a depth past 1 says
+  how many callees each level leaves out.
+- `callees` says how many callees its `limit` leaves out, and of a name
+  several definitions share, which one it answers for (`others` in the web
+  API).
+- A `limit`, a `flow` or `context` `depth`, a `context` `max_tokens` or
+  `callee_budget`, or a `path` `max_depth` below 1 is refused by every
+  tool; `limit=0` answered as if there were no
+  callers, matches, changes or history.
+- The web page's changes view no longer throws for a changed symbol with
+  no callers.
+- `context --max-output-tokens` cuts the parts the answer is made of, not
+  its text: expanded callees, then usage examples past 2, related tests
+  and configuration, callers past 5 (still counting possible callers
+  apart), the symbol's callees past 5 (planned again for those five, so
+  the note counts by kind only callees drawn nowhere in the answer and no
+  "(at level N)" mark points at a callee cut away), and the source past 30
+  of the symbol's lines, saying what each step left out; a section dropped
+  whole keeps its heading with "(omitted, max_output_tokens limit)".
+  It read the rendered text back, so code with a heading-like or a fence
+  line in it was cut wrongly or not at all, opened callees kept their
+  headings without their code, and counts were wrong.
+- `flow` text indents the code it inlines as deep as its fence. The code
+  was printed from the first column inside an indented fence, so it broke
+  the tree, and below the first level the fence read as an indented code
+  block.
+- A command that loads no embedding model no longer imports
+  sentence-transformers, and with it torch, as the service starts: where
+  they are installed every CLI command spent seconds on it.
+- `churn` ranks symbols, and co-change pairs of symbols, with the same
+  number of commits by node ID, so the same history gives the same list.
+  Their order among ties changed from run to run, and so, at the limit,
+  did which of them were listed.
+
 ## [0.3.1] — 2026-10-22
 
 ### Fixed

{descry_codegraph-0.3.1 → descry_codegraph-0.3.2}/CLAUDE.md

@@ -23,7 +23,7 @@ just test tests/test_handlers.py::test_index     # one test
 just test -k "cross_lang and not slow"           # by expression
 ```
 
-Python 3.11+ required (enforced by `pyproject.toml`). Pre-commit gate: `just lint && just fmt && just test` all pass (2755 tests currently — a drop is a regression signal).
+Python 3.11+ required (enforced by `pyproject.toml`). Pre-commit gate: `just lint && just fmt && just test` all pass (2810 tests currently — a drop is a regression signal).
 
 Invoke the tool while developing:
 

{descry_codegraph-0.3.1 → descry_codegraph-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: descry-codegraph
-Version: 0.3.1
+Version: 0.3.2
 Summary: Codebase knowledge graph: polyglot indexer, semantic search, call-graph analysis
 Project-URL: Homepage, https://github.com/06chaynes/descry
 Project-URL: Repository, https://github.com/06chaynes/descry

{descry_codegraph-0.3.1 → descry_codegraph-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "descry-codegraph"
-version = "0.3.1"
+version = "0.3.2"
 description = "Codebase knowledge graph: polyglot indexer, semantic search, call-graph analysis"
 requires-python = ">=3.11"
 authors = [{name = "Christian Haynes"}]

{descry_codegraph-0.3.1 → descry_codegraph-0.3.2}/src/descry/__init__.py

@@ -1,4 +1,4 @@
 """Descry — Codebase knowledge graph: polyglot indexer, semantic search, call-graph analysis."""
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"
 __all__ = ["__version__"]

{descry_codegraph-0.3.1 → descry_codegraph-0.3.2}/src/descry/_graph.py

@@ -112,4 +112,18 @@ def load_graph_with_schema(path: Path | str) -> dict:
             f"run 'descry index' to rebuild."
         )
     _check_shape(data)
+    count_callers(data["nodes"], data["edges"])
     return data
+
+
+def count_callers(nodes: list, edges: list) -> None:
+    """Set each node's `in_degree` to the number of its callers: the
+    symbols whose calls are resolved to it, not those an unresolved call
+    only may be. A graph is counted again as it loads, so one written by an
+    older descry counts them the same way."""
+    callers: dict[str, set] = {}
+    for edge in edges:
+        if edge["relation"] in CALL_RELATIONS:
+            callers.setdefault(edge["target"], set()).add(edge["source"])
+    for node in nodes:
+        node["metadata"]["in_degree"] = len(callers.get(node["id"], ()))

{descry_codegraph-0.3.1 → descry_codegraph-0.3.2}/src/descry/cli.py

@@ -302,7 +302,12 @@ def main():
         choices=["forward", "backward"],
         help="Trace direction (default: forward)",
     )
-    sub.add_argument("--depth", type=int, default=3, help="Trace depth (default: 3)")
+    sub.add_argument(
+        "--depth",
+        type=int,
+        default=3,
+        help="Levels of calls below the start (default: 3)",
+    )
     sub.add_argument("--target", default=None, help="Target symbol to reach")
     sub.add_argument(
         "--inline-threshold",

{descry_codegraph-0.3.1 → descry_codegraph-0.3.2}/src/descry/embeddings.py

@@ -12,6 +12,7 @@ Usage:
 
 import contextlib
 import hashlib
+import importlib.util
 import json
 import logging
 import os
@@ -347,13 +348,14 @@ def _resolve_cache_dir(graph_path: Path, cache_dir: str | None = None) -> Path:
 # Try to import embedding dependencies
 try:
     import numpy as np
-    from sentence_transformers import SentenceTransformer
-
-    EMBEDDINGS_AVAILABLE = True
 except ImportError:
-    EMBEDDINGS_AVAILABLE = False
     np = None
-    SentenceTransformer = None
+# Imported by _load_sentence_transformer: it brings in torch, which takes
+# seconds a command that loads no model should not spend.
+SentenceTransformer = None
+EMBEDDINGS_AVAILABLE = (
+    np is not None and importlib.util.find_spec("sentence_transformers") is not None
+)
 
 
 def embeddings_available() -> bool:
@@ -376,6 +378,9 @@ def _load_sentence_transformer(model_name: str, revision: str | None = None):
         model_name: Registry alias, HuggingFace repo id, or local path.
         revision: Overrides the registry's pinned revision.
     """
+    global SentenceTransformer
+    if SentenceTransformer is None:
+        from sentence_transformers import SentenceTransformer
     spec = resolve_model_spec(model_name)
     target = spec.repo_id if spec else model_name
     if revision is None and spec:

{descry_codegraph-0.3.1 → descry_codegraph-0.3.2}/src/descry/generate.py

@@ -25433,19 +25433,10 @@ class CodeGraphBuilder:
             output_path: Path to write the graph JSON
             scip_index: Optional ScipIndex for type-aware resolution
         """
-        from descry._graph import CALL_RELATIONS, CURRENT_SCHEMA
+        from descry._graph import CURRENT_SCHEMA, count_callers
 
         self.resolve_references(scip_index=scip_index)
-        # The number of its callers: those certain and those it is one of
-        # the candidates of
-        callers = {}
-        for edge in self.edges:
-            if edge["relation"] in CALL_RELATIONS:
-                candidates = edge.get("metadata", {}).get("candidates", ())
-                for target in (edge["target"], *candidates):
-                    callers.setdefault(target, set()).add(edge["source"])
-        for node in self.nodes:
-            node["metadata"]["in_degree"] = len(callers.get(node["id"], ()))
+        count_callers(self.nodes, self.edges)
         # Atomic write: stream to a sibling tmp file then os.replace. A
         # concurrent reader (MCP prewarm, web `/api/health`, another CLI
         # invocation) that stats the destination mid-write would otherwise

{descry_codegraph-0.3.1 → descry_codegraph-0.3.2}/src/descry/git_history.py

@@ -758,7 +758,7 @@ class GitHistoryAnalyzer:
 
             # Sort by commit count
             sorted_symbols = sorted(
-                symbol_commits.items(), key=lambda x: len(x[1]), reverse=True
+                symbol_commits.items(), key=lambda x: (-len(x[1]), x[0])
             )[:limit]
 
             lines = []
@@ -923,7 +923,7 @@ class GitHistoryAnalyzer:
 
         # SYMBOLS MODE
         sorted_symbols = sorted(
-            symbol_commits.items(), key=lambda x: len(x[1]), reverse=True
+            symbol_commits.items(), key=lambda x: (-len(x[1]), x[0])
         )[:limit]
 
         symbols = []
@@ -983,7 +983,7 @@ class GitHistoryAnalyzer:
             frequent_pairs = [
                 (pair, count) for pair, count in pair_counts.items() if count >= 2
             ]
-            frequent_pairs.sort(key=lambda x: x[1], reverse=True)
+            frequent_pairs.sort(key=lambda x: (-x[1], x[0]))
 
             for (sym_a, sym_b), count in frequent_pairs[:limit]:
                 _, name_a, loc_a = self._get_node_display(sym_a)
@@ -1081,7 +1081,7 @@ class GitHistoryAnalyzer:
             frequent_pairs = [
                 (pair, count) for pair, count in pair_counts.items() if count >= 2
             ]
-            frequent_pairs.sort(key=lambda x: x[1], reverse=True)
+            frequent_pairs.sort(key=lambda x: (-x[1], x[0]))
             frequent_pairs = frequent_pairs[:limit]
 
         if frequent_pairs:
@@ -1660,26 +1660,43 @@ class GitHistoryAnalyzer:
                 f"(+{stats['added']}/-{stats['removed']})"
             )
 
-            # Show callers if requested
             if show_callers and self.querier:
-                # The callers of this symbol, not of every one of its name
-                callers = self.querier.get_callers(node_id)
+                callers, total, possible = self._symbol_callers(node_id)
                 if callers:
-                    caller_names = []
-                    for caller_id in callers[:5]:
-                        c_node = self.querier.get_node_info(caller_id)
-                        if c_node:
-                            caller_names.append(c_node["metadata"].get("name", "?"))
-                        else:
-                            # Extract name from node ID
-                            parts = caller_id.split("::")
-                            caller_names.append(parts[-1] if parts else "?")
-
-                    more = f", +{len(callers) - 5} more" if len(callers) > 5 else ""
-                    lines.append(f"     Callers: {', '.join(caller_names)}{more}")
+                    names = ", ".join(
+                        c["name"] + self.querier.one_of(c["candidates"])
+                        for c in callers
+                    )
+                    hidden = possible - sum(bool(c["candidates"]) for c in callers)
+                    hidden_certain = total - len(callers) - hidden
+                    more = (
+                        f"; {self.querier.more_callers(hidden_certain, hidden)}"
+                        if total > len(callers)
+                        else ""
+                    )
+                    lines.append(f"     Callers: {names}{more}")
 
         return "\n".join(lines)
 
+    def _symbol_callers(self, node_id):
+        """The first five callers of the symbol ``node_id``, certain ones
+        first, each ``{"id", "name", "candidates"}`` where ``candidates`` is
+        the number an unresolved call reaching it only may be one of; the
+        number of its callers; and how many of those only may be."""
+        caller_ids, ambiguous = self.querier.ordered_callers(node_id)
+        callers = []
+        for caller_id in caller_ids[:5]:
+            c_node = self.querier.get_node_info(caller_id)
+            name = (
+                c_node["metadata"].get("name", "?")
+                if c_node
+                else caller_id.split("::")[-1]
+            )
+            callers.append(
+                {"id": caller_id, "name": name, "candidates": ambiguous.get(caller_id)}
+            )
+        return callers, len(caller_ids), len(ambiguous)
+
     def get_changes_structured(
         self,
         commit_range: str | None = None,
@@ -1742,21 +1759,11 @@ class GitHistoryAnalyzer:
             }
 
             if show_callers and self.querier:
-                caller_ids = self.querier.get_callers(node_id)
-                if caller_ids:
-                    callers = []
-                    for caller_id in caller_ids[:5]:
-                        c_node = self.querier.get_node_info(caller_id)
-                        c_name = (
-                            c_node["metadata"].get("name", "?")
-                            if c_node
-                            else caller_id.split("::")[-1]
-                            if "::" in caller_id
-                            else "?"
-                        )
-                        callers.append({"id": caller_id, "name": c_name})
+                callers, total, possible = self._symbol_callers(node_id)
+                if callers:
                     entry["callers"] = callers
-                    entry["callers_total"] = len(caller_ids)
+                    entry["callers_total"] = total
+                    entry["callers_possible"] = possible
 
             symbols.append(entry)
 

{descry_codegraph-0.3.1 → descry_codegraph-0.3.2}/src/descry/handlers.py

@@ -946,10 +946,12 @@ _GRAPH_NOT_FOUND = "Graph not found. Run descry ensure first."
 _INDEX_BUSY = "An index run is already in progress"
 
 
-def _limit_error(limit: int) -> str | None:
-    """Why `limit` cannot be used, or None. A negative one slices from the end."""
-    if limit < 0:
-        return f"limit must not be negative, got {limit}."
+def limit_error(limit: int, name: str = "limit") -> str | None:
+    """Why the limit or depth ``name`` cannot be ``limit``, or None: a
+    negative one slices from the end, and none at all answers as if there
+    were nothing to show."""
+    if limit < 1:
+        return f"{name} must be at least 1, got {limit}."
     return None
 
 
@@ -1712,7 +1714,7 @@ class DescryService:
 
     async def callers_data(self, name: str, limit: int = 20) -> dict:
         """Callers of a symbol, as data. An exact miss retries with fuzzy=True."""
-        if error := _limit_error(limit):
+        if error := limit_error(limit):
             return {"ok": False, "error": error, "reason": "invalid"}
         q = await self._get_querier()
         if not q:
@@ -1721,15 +1723,11 @@ class DescryService:
 
     @staticmethod
     def _callers_from(q, name: str, limit: int) -> dict:
-        all_callers = q.get_callers(name)
-        ambiguous = q.get_ambiguous_callers(name)
+        all_callers, ambiguous = q.ordered_callers(name)
         fuzzy = False
         if not all_callers:
-            all_callers = q.get_callers(name, fuzzy=True)
-            ambiguous = q.get_ambiguous_callers(name, fuzzy=True)
+            all_callers, ambiguous = q.ordered_callers(name, fuzzy=True)
             fuzzy = bool(all_callers)
-        # Certain callers come before those that are one of several candidates.
-        all_callers = sorted(all_callers, key=ambiguous.__contains__)
 
         return {
             "ok": True,
@@ -1738,12 +1736,13 @@ class DescryService:
             "fuzzy": fuzzy,
             "total": len(all_callers),
             "callers": all_callers[:limit],
-            "ambiguous": {c: ambiguous[c] for c in all_callers if c in ambiguous},
+            "left_out": all_callers[limit:],
+            "ambiguous": ambiguous,
         }
 
     async def callees_data(self, name: str, limit: int = 20) -> dict:
         """Callees of a symbol, as data. Same fuzzy fallback as callers_data."""
-        if error := _limit_error(limit):
+        if error := limit_error(limit):
             return {"ok": False, "error": error, "reason": "invalid"}
         q = await self._get_querier()
         if not q:
@@ -1784,12 +1783,15 @@ class DescryService:
             "node": node,
             "total": len(callees),
             "callees": callees[:limit],
-            "ambiguous": {c: ambiguous[c] for c in callees if c in ambiguous},
+            "left_out": callees[limit:],
+            "ambiguous": ambiguous,
+            # The definitions of the name besides the one answered for
+            "others": len(func_matches) - 1,
         }
 
     async def callers(self, name: str, limit: int = 20) -> str:
         """Find all callers of a symbol."""
-        if error := _limit_error(limit):
+        if error := limit_error(limit):
             return ServiceError(f"ERROR: {error}")
         # One querier for lookup and rendering: a second fetch returns None
         # if the graph file has been removed in between.
@@ -1808,7 +1810,11 @@ class DescryService:
                 f"No callers of '{name}'. Try descry search to verify symbol exists."
             )
         else:
-            lines = [f"{len(callers)} caller(s) of '{name}'{fuzzy_note}:"]
+            certain, possible, unresolved = q.kinds(
+                callers + data["left_out"], ambiguous
+            )
+            extra = q.possible(possible, unresolved)
+            lines = [f"{certain} caller(s) of '{name}'{fuzzy_note}{extra}:"]
             for caller in callers:
                 node_info = q.get_node_info(caller)
                 one_of = q.one_of(ambiguous.get(caller))
@@ -1822,16 +1828,16 @@ class DescryService:
                 else:
                     lines.append(f"  {caller}{one_of}")
             if len(callers) < total_count:
-                lines.append(
-                    f"  ... ({total_count - len(callers)} more, limit {limit})"
-                )
+                certain, possible, unresolved = q.kinds(data["left_out"], ambiguous)
+                more = q.more_callers(certain, possible, unresolved=unresolved)
+                lines.append(f"  ... ({more}, limit {limit})")
             result = "\n".join(lines)
 
         return await self._format_response(result)
 
     async def callees(self, name: str, limit: int = 20) -> str:
         """Find what a symbol calls."""
-        if error := _limit_error(limit):
+        if error := limit_error(limit):
             return ServiceError(f"ERROR: {error}")
         q = await self._get_querier()
         if not q:
@@ -1842,15 +1848,32 @@ class DescryService:
 
         node = data["node"]
         callees = data["callees"]
+        total = data["total"]
         ambiguous = data.get("ambiguous", {})
         fuzzy_note = " (fuzzy match)" if data["fuzzy"] else ""
-        display_name = node.get("metadata", {}).get("name", name)
-        if not callees:
-            result = f"'{display_name}'{fuzzy_note} calls no tracked functions."
+        # A name several definitions have is answered for one, named by ID
+        display_name = (
+            node["id"] if data["others"] else node.get("metadata", {}).get("name", name)
+        )
+        others = (
+            f"\n({data['others']} other "
+            f"{'match(es) for' if data['fuzzy'] else 'definition(s) of'} '{name}'; "
+            "use a node ID to choose)"
+            if data["others"]
+            else ""
+        )
+        if not total:
+            result = f"'{display_name}'{fuzzy_note} calls no tracked functions.{others}"
         else:
-            lines = [f"'{display_name}'{fuzzy_note} calls {len(callees)} function(s):"]
+            certain, possible, unresolved = q.kinds(
+                callees + data["left_out"], ambiguous
+            )
+            possible = q.possible(possible, unresolved)
+            lines = [
+                f"'{display_name}'{fuzzy_note} calls {certain} function(s){possible}:"
+            ]
             for callee in callees:
-                one_of = q.one_of(ambiguous.get(callee))
+                one_of = q.callee_note(ambiguous.get(callee))
                 callee_info = q.get_node_info(callee)
                 if callee_info:
                     lineno = callee_info.get("metadata", {}).get("lineno")
@@ -1861,7 +1884,11 @@ class DescryService:
                         lines.append(f"  {callee}{one_of}")
                 else:
                     lines.append(f"  {callee}{one_of}")
-            result = "\n".join(lines)
+            if len(callees) < total:
+                certain, possible, unresolved = q.kinds(data["left_out"], ambiguous)
+                more = q.more_callers(certain, possible, "callees", unresolved)
+                lines.append(f"  ... ({more}, limit {limit})")
+            result = "\n".join(lines) + others
 
         return await self._format_response(result)
 
@@ -1879,6 +1906,13 @@ class DescryService:
         max_output_tokens: int | None = None,
     ) -> str:
         """Get full context for a symbol."""
+        for value, name in (
+            (depth, "depth"),
+            (max_tokens, "max_tokens"),
+            (callee_budget, "callee_budget"),
+        ):
+            if error := limit_error(value, name):
+                return ServiceError(f"ERROR: {error}")
         q = await self._get_querier()
         if not q:
             return ServiceError(f"ERROR: {self._no_graph_error()}")
@@ -1928,7 +1962,10 @@ class DescryService:
                 result, include_header=False, max_lines=50
             )
 
-        depth_note = f" [depth={depth}]" if depth > 1 else ""
+        traced = q.flow_depth(depth)
+        depth_note = f" [depth={traced}]" if traced > 1 else ""
+        if traced < depth:
+            depth_note += f" [depth {depth} is past [query] max_depth]"
         full_note = " [full=true]" if full else ""
         head_note = f" [head_lines={head_lines}]" if head_lines else ""
         expand_note = " [expand_callees=true]" if expand_callees else ""
@@ -1951,8 +1988,11 @@ class DescryService:
         """Call flow from a starting symbol, as data.
 
         `result` is the markdown trace, or the tree of
-        `GraphQuerier.trace_flow_structured` when `structured`.
+        `GraphQuerier.trace_flow_structured` when `structured`; `depth` is
+        the depth traced, at most the project's ceiling.
         """
+        if error := limit_error(depth, "depth"):
+            return {"ok": False, "error": error, "reason": "invalid"}
         q = await self._get_querier()
         if not q:
             return {"ok": False, "error": self._no_graph_error()}
@@ -1965,7 +2005,12 @@ class DescryService:
             target=target,
             inline_threshold=inline_threshold,
         )
-        return {"ok": True, "error": None, "result": result}
+        return {
+            "ok": True,
+            "error": None,
+            "result": result,
+            "depth": q.flow_depth(depth),
+        }
 
     async def flow(
         self,
@@ -1998,7 +2043,7 @@ class DescryService:
         Returns `{"ok", "error", "results", "method"}`; `method` is "keyword"
         or "hybrid".
         """
-        if error := _limit_error(limit):
+        if error := limit_error(limit):
             return {
                 "ok": False,
                 "error": error,
@@ -2334,8 +2379,8 @@ class DescryService:
         reported as a missing graph; `reason` classifies it as "invalid",
         "unavailable", "no_graph", "loading" or "failed".
         """
-        if limit_error := _limit_error(limit):
-            reason, error = "invalid", limit_error
+        if refused := limit_error(limit):
+            reason, error = "invalid", refused
         elif not self._semantic_available or not self._SemanticSearcher:
             reason, error = "unavailable", "Semantic search not available."
         elif not self.config.graph_path.exists():
@@ -2644,6 +2689,8 @@ class DescryService:
         `status` and `path` are those of `GraphQuerier.find_call_path_result`.
         Unless `status` is "found", `message` says why there is no path.
         """
+        if error := limit_error(max_depth, "max_depth"):
+            return {"ok": False, "error": error, "reason": "invalid"}
         q = await self._get_querier()
         if not q:
             return {"ok": False, "error": self._no_graph_error()}
@@ -2925,10 +2972,10 @@ class DescryService:
         """Run a GitHistoryAnalyzer method off the event loop, as data.
 
         `result` is what the method returned. On failure `reason` is
-        "invalid" for a negative `limit`, "unavailable" when the git history
+        "invalid" for a `limit` below 1, "unavailable" when the git history
         module is missing and "failed" when the analysis raised.
         """
-        if error := _limit_error(kwargs["limit"]):
+        if error := limit_error(kwargs["limit"]):
             return {"ok": False, "error": error, "reason": "invalid"}
         if not self._git_available:
             return {

{descry_codegraph-0.3.1 → descry_codegraph-0.3.2}/src/descry/mcp_server.py

@@ -243,7 +243,7 @@ async def descry_flow(
     target: str | None = None,
     inline_threshold: int = 100,
 ) -> str:
-    """Trace call flow from a starting symbol. Shows call chains with inline code for small functions. Use for 'how does X reach Y' queries, impact analysis, and understanding execution paths. Direction 'forward' traces callees (what this calls), 'backward' traces callers (what calls this)."""
+    """Trace call flow from a starting symbol. Shows call chains with inline code for small functions. Use for 'how does X reach Y' queries, impact analysis, and understanding execution paths. Direction 'forward' traces callees (what this calls), 'backward' traces callers (what calls this). depth is the levels of calls below the start, at most the project's [query] max_depth (default 3)."""
     return _fenced(
         await _svc().flow(start, direction.value, depth, target, inline_threshold)
     )