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

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

@@ -6,6 +6,112 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.3.3] — 2026-10-23
+
+### Fixed
+
+- A `bin` directory is indexed: Dart keeps its entry points there and Rust
+  its extra binaries (`src/bin/`). Only the `bin` of a .NET project or of
+  an Eclipse project, beside its project file or `.classpath`, is left out
+  as build output; every `bin` was.
+- A Dart call of a standard type's name without `new`, `StringBuffer()`,
+  makes an instance of that type, as `new StringBuffer()` does. Calls on it
+  were taken as calls on an unknown receiver and listed as possible calls
+  of every project method of their name (`toString`, `write`, `close`).
+
+## [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.3}/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 (2812 tests currently — a drop is a regression signal).
 
 Invoke the tool while developing:
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: descry-codegraph
-Version: 0.3.1
+Version: 0.3.3
 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
@@ -267,7 +267,7 @@ For customization, add a `.descry.toml` to your project root.
 
 ```toml
 [project]
-# OPTIONAL — REPLACES the 25-element default. Leave unset to keep defaults
+# OPTIONAL — REPLACES the 24-element default. Leave unset to keep defaults
 # (.git, .gradle, .next, .svelte-kit, .venv, node_modules, target, build, …).
 # excluded_dirs = ["target", "node_modules", "dist", "build", "vendor"]
 # OPTIONAL — in a git repository, files git ignores are not indexed.
@@ -393,7 +393,7 @@ Share of project calls resolved without SCIP, measured on public repositories at
 | C# | serilog `bebc771`, Newtonsoft.Json `52fa3ae` (`Src/Newtonsoft.Json`) | 94%, 91% |
 | C | jq `a19efdd`, libuv `954c1d1` | 99%, 79% |
 | C++ | leveldb `7ee830d`, fmt `c4927e6` | 97%, 86% |
-| Dart | shelf `b2cb503`, riverpod `1efba1c` (`packages/riverpod`) | 93%, 91% |
+| Dart | shelf `b2cb503`, riverpod `1efba1c` (`packages/riverpod`) | 95%, 91% |
 | Ruby | rack `a9833c8`, sinatra `cb22afd` | 70%, 39% |
 
 The remainder is unresolved, not wrong: of 450 resolved edges drawn at random from these repositories and read against the source, every one reaches the definition the call reaches. Ruby is low because the language declares no types and calls inside DSL blocks run with another `self`; libuv because most of its functions exist once for Unix and once for Windows, and the build files, not the source, choose between them.

{descry_codegraph-0.3.1 → descry_codegraph-0.3.3}/README.md

@@ -202,7 +202,7 @@ For customization, add a `.descry.toml` to your project root.
 
 ```toml
 [project]
-# OPTIONAL — REPLACES the 25-element default. Leave unset to keep defaults
+# OPTIONAL — REPLACES the 24-element default. Leave unset to keep defaults
 # (.git, .gradle, .next, .svelte-kit, .venv, node_modules, target, build, …).
 # excluded_dirs = ["target", "node_modules", "dist", "build", "vendor"]
 # OPTIONAL — in a git repository, files git ignores are not indexed.
@@ -328,7 +328,7 @@ Share of project calls resolved without SCIP, measured on public repositories at
 | C# | serilog `bebc771`, Newtonsoft.Json `52fa3ae` (`Src/Newtonsoft.Json`) | 94%, 91% |
 | C | jq `a19efdd`, libuv `954c1d1` | 99%, 79% |
 | C++ | leveldb `7ee830d`, fmt `c4927e6` | 97%, 86% |
-| Dart | shelf `b2cb503`, riverpod `1efba1c` (`packages/riverpod`) | 93%, 91% |
+| Dart | shelf `b2cb503`, riverpod `1efba1c` (`packages/riverpod`) | 95%, 91% |
 | Ruby | rack `a9833c8`, sinatra `cb22afd` | 70%, 39% |
 
 The remainder is unresolved, not wrong: of 450 resolved edges drawn at random from these repositories and read against the source, every one reaches the definition the call reaches. Ruby is low because the language declares no types and calls inside DSL blocks run with another `self`; libuv because most of its functions exist once for Unix and once for Windows, and the build files, not the source, choose between them.

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

@@ -1,6 +1,6 @@
 [project]
 name = "descry-codegraph"
-version = "0.3.1"
+version = "0.3.3"
 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.3}/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.3"
 __all__ = ["__version__"]

{descry_codegraph-0.3.1 → descry_codegraph-0.3.3}/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.3}/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.3}/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.3}/src/descry/generate.py

@@ -18650,6 +18650,15 @@ class CallResolver:
             if self.standard[lang].key(callee, source_id) == callee:
                 held = self._returned_type(constructed, source_id)
                 self._result = held or self._result
+        elif verdict[1] == _EXTERNAL and not origin and lang == "dart":
+            # Dart constructs without `new`: a call of a standard type's
+            # name gives an instance of it.
+            library = self.standard[lang]
+            if (
+                callee in library.data["types"]
+                and library.key(callee, source_id) == callee
+            ):
+                self._result = self._returned_type(callee, source_id) or self._result
         elif verdict[1] == _EXTERNAL and not origin and lang == "typescript":
             known, value = self._js_global(callee, source_id)
             if known:
@@ -24878,12 +24887,19 @@ class CodeGraphBuilder:
         for root, dirs, files in os.walk(self.root_dir, followlinks=False):
             dirs.sort()
             files.sort()
-            # Filter by name first (excluded dirs, dotfiles), and by what git
-            # ignores.
+            # Filter by name first (excluded dirs, dotfiles, the build output
+            # of a .NET or an Eclipse project), and by what git ignores.
+            # `bin` holds sources in Dart and Rust.
+            built = any(
+                f.endswith((".csproj", ".vbproj", ".fsproj")) or f == ".classpath"
+                for f in files
+            )
             dirs[:] = [
                 d
                 for d in kept(root, dirs)
-                if not d.startswith(".") and d not in self.excluded_dirs
+                if not d.startswith(".")
+                and d not in self.excluded_dirs
+                and not (built and d == "bin")
             ]
             # Then filter by realpath containment — drop directories that are
             # symlinks pointing outside the project root.
@@ -25433,19 +25449,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.3}/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)