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

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

@@ -6,6 +6,132 @@ 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
+
+- The callers a change lists (`changes`), and those `context` lists and
+  counts and an upstream `flow` follows, are the callers of that symbol,
+  not of every symbol of its name. `context` marks a caller that reaches
+  the symbol only as one of an unresolved call's candidates, as `callers`
+  does.
+- A symbol's caller count (`in_degree`, shown as "N callers") counts the
+  symbols that call or construct it, not every edge into it: the file
+  defining it was counted as a caller.
+- A Python signature is written as the source writes it, with defaults,
+  `*`, `**`, keyword-only parameters and `async`, and with no `-> None`
+  where no return type is annotated. An unannotated function was recorded
+  as returning `None`.
+- The web UI's Language filter lists the graph's languages, which the
+  graph status now gives (`/api/status`, `/api/health`), instead of four
+  fixed ones.
+- A search during the startup pre-warm, or during the embeddings load
+  after an index, waits for that load (up to `embedding_timeout`) instead
+  of reporting that embeddings are loading. A streamed index reports the
+  embeddings line however long the load takes.
+- scip-python runs without `pip` on PATH and outside a git repository: it
+  is given an empty environment and a project version.
+- A SCIP indexer's failure is reported by its error, without the stack
+  frames that pushed it out of the message.
+- `flatten` takes a class name as `context` does, not only a node ID.
+- `impls` says trait implementations are recorded for Rust only, instead
+  of advising a reindex.
+- An unresolved call with one candidate reads "unresolved; the only
+  candidate", not "one of 1 candidates".
+
 ## [0.3.0] — 2026-10-22
 
 Call resolution is rebuilt for every supported language: a call is

{descry_codegraph-0.3.0 → 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 (2722 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.0 → descry_codegraph-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: descry-codegraph
-Version: 0.3.0
+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
@@ -251,7 +251,7 @@ Descry provides 19 tools, available through all interfaces:
 | `path` | Find shortest call path between two symbols |
 | `structure` | Show file structure — imports, classes, functions |
 | `flatten` | Show effective API of a class including inherited methods |
-| `impls` | Find all implementations of a trait/interface method |
+| `impls` | Find all implementations of a Rust trait method |
 | `cross-lang` | Trace frontend API calls to backend handlers via OpenAPI |
 | `churn` | Find code churn hotspots (symbols, files, or co-change pairs) |
 | `evolution` | Track how a symbol has changed over time |

{descry_codegraph-0.3.0 → descry_codegraph-0.3.2}/README.md

@@ -186,7 +186,7 @@ Descry provides 19 tools, available through all interfaces:
 | `path` | Find shortest call path between two symbols |
 | `structure` | Show file structure — imports, classes, functions |
 | `flatten` | Show effective API of a class including inherited methods |
-| `impls` | Find all implementations of a trait/interface method |
+| `impls` | Find all implementations of a Rust trait method |
 | `cross-lang` | Trace frontend API calls to backend handlers via OpenAPI |
 | `churn` | Find code churn hotspots (symbols, files, or co-change pairs) |
 | `evolution` | Track how a symbol has changed over time |

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

@@ -1,6 +1,6 @@
 [project]
 name = "descry-codegraph"
-version = "0.3.0"
+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.0 → 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.0"
+__version__ = "0.3.2"
 __all__ = ["__version__"]

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

@@ -11,6 +11,11 @@ from pathlib import Path
 
 CURRENT_SCHEMA = 2
 
+# The edges by which one symbol calls or constructs another: its callers
+CALL_RELATIONS = frozenset(
+    {"CALLS", "CALLS_RESOLVED", "INSTANTIATES", "INSTANTIATES_RESOLVED"}
+)
+
 
 class GraphSchemaError(Exception):
     """Raised when a graph file is not a graph this version can read.
@@ -107,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.0 → 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",
@@ -368,7 +373,7 @@ def main():
 
     # impls
     sub = subparsers.add_parser(
-        "impls", help="Find all implementations of a trait method"
+        "impls", help="Find all implementations of a Rust trait method"
     )
     sub.add_argument("method", help="Method name")
     sub.add_argument("--trait-name", default=None, help="Filter by trait name")

{descry_codegraph-0.3.0 → 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.0 → descry_codegraph-0.3.2}/src/descry/generate.py

@@ -8388,15 +8388,6 @@ class PythonParser(BaseParser):
             return f"[{elts}]"
         return "Complex"
 
-    def _get_args_info(self, args_node):
-        args_list = []
-        for arg in args_node.args:
-            arg_str = arg.arg
-            if arg.annotation:
-                arg_str += f": {self._get_type_annotation(arg.annotation)}"
-            args_list.append(arg_str)
-        return args_list
-
     def _get_param_types(self, args_node):
         """Extract parameter types as a list for metadata storage."""
         param_types = []
@@ -8492,12 +8483,14 @@ class PythonParser(BaseParser):
             is_method = parent_id in self.class_ids
             node_type = "Method" if is_method else "Function"
 
-            args = self._get_args_info(node.args)
             param_types = self._get_param_types(node.args)
             return_type = (
-                self._get_type_annotation(node.returns) if node.returns else "None"
+                self._get_type_annotation(node.returns) if node.returns else ""
             )
-            signature = f"def {node.name}({', '.join(args)}) -> {return_type}"
+            keyword = "async def" if isinstance(node, ast.AsyncFunctionDef) else "def"
+            signature = f"{keyword} {node.name}({ast.unparse(node.args)})"
+            if node.returns:
+                signature += f" -> {ast.unparse(node.returns)}"
 
             self.builder.add_node(
                 func_id,
@@ -25440,16 +25433,10 @@ class CodeGraphBuilder:
             output_path: Path to write the graph JSON
             scip_index: Optional ScipIndex for type-aware resolution
         """
-        from descry._graph import CURRENT_SCHEMA
+        from descry._graph import CURRENT_SCHEMA, count_callers
 
         self.resolve_references(scip_index=scip_index)
-        in_degree = {}
-        for edge in self.edges:
-            t = edge["target"]
-            if t:
-                in_degree[t] = in_degree.get(t, 0) + 1
-        for node in self.nodes:
-            node["metadata"]["in_degree"] = in_degree.get(node["id"], 0)
+        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.0 → 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:
-                sym_name = name.split(".")[-1]  # Get base name
-                callers = self.querier.get_callers(sym_name)
+                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,22 +1759,11 @@ class GitHistoryAnalyzer:
             }
 
             if show_callers and self.querier:
-                sym_name = name.split(".")[-1]
-                caller_ids = self.querier.get_callers(sym_name)
-                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)