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

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

@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.3.4] — 2026-10-23
+
+### Fixed
+
+- `search` answers what semantic search finds when the keywords find
+  nothing: the semantic pass ran because they found little, and its
+  results were then dropped ("No matches"). It now searches under
+  `lang`, `crate`, `type` and `exclude_tests` as the keyword side does; its
+  results were merged unfiltered.
+- `search --type` with a type the graph has none of, or one descry does
+  not know, matches nothing, as an unknown `lang` does; it was ignored and
+  every type answered. The CLI lists the types it takes.
+- `flow --target` takes a node ID as well as a name; a node ID was never
+  found, and the trace said nothing of it.
+
 ## [0.3.3] — 2026-10-23
 
 ### Fixed

{descry_codegraph-0.3.3 → descry_codegraph-0.3.4}/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 (2812 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 (2822 tests currently — a drop is a regression signal).
 
 Invoke the tool while developing:
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: descry-codegraph
-Version: 0.3.3
+Version: 0.3.4
 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.3 → descry_codegraph-0.3.4}/claude-skill/descry/references/cli-reference.md

@@ -24,7 +24,7 @@ descry search <terms...>
     [--limit N]                  # default 10
     [--lang rust|ts|py|...]
     [--crate NAME]
-    [--type Function|Class|Method|...]
+    [--type function|class|method|constant|file|all]
     [--exclude-tests]
 
 descry semantic <query>
@@ -49,7 +49,7 @@ descry callees <name> [--limit N]           # default 20
 descry flow <start>
     [--direction forward|backward]   # default forward
     [--depth N]                       # default 3, capped by [query] max_depth
-    [--target NAME]                   # stop early if reached
+    [--target SYMBOL]                 # stop early if reached (name or node ID)
     [--inline-threshold N]            # inline callee source below N tokens
 
 descry path <start> <end>

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

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

{descry_codegraph-0.3.3 → descry_codegraph-0.3.4}/src/descry/__init__.py

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

{descry_codegraph-0.3.3 → descry_codegraph-0.3.4}/src/descry/cli.py

@@ -308,7 +308,9 @@ def main():
         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(
+        "--target", default=None, help="Symbol to reach, by name or node ID"
+    )
     sub.add_argument(
         "--inline-threshold",
         type=int,
@@ -329,7 +331,13 @@ def main():
     sub.add_argument("--limit", type=int, default=10, help="Max results (default: 10)")
     sub.add_argument("--lang", default=None, help="Filter by language")
     sub.add_argument("--crate", default=None, help="Filter by crate")
-    sub.add_argument("--type", default=None, help="Filter by symbol type")
+    sub.add_argument(
+        "--type",
+        default=None,
+        type=str.lower,
+        choices=["function", "class", "method", "constant", "file", "all"],
+        help="Filter by symbol type",
+    )
     sub.add_argument(
         "--exclude-tests", action="store_true", help="Exclude test symbols"
     )

{descry_codegraph-0.3.3 → descry_codegraph-0.3.4}/src/descry/embeddings.py

@@ -774,7 +774,9 @@ class SemanticSearcher:
         self.embeddings = embeddings / np.where(norms == 0, 1, norms)
         logger.info("Embeddings generated successfully")
 
-    def search(self, query: str, limit: int = 10, min_score: float = 0.3) -> list:
+    def search(
+        self, query: str, limit: int = 10, min_score: float = 0.3, keep=None
+    ) -> list:
         """Search for nodes semantically similar to the query.
 
         Args:
@@ -782,6 +784,7 @@ class SemanticSearcher:
             limit: Maximum number of results
             min_score: Minimum final score, i.e. cosine similarity after
                 the in-degree and type boosts are added (may exceed 1).
+            keep: The node IDs results may have, None for any.
 
         Returns:
             List of (node, score) tuples sorted by relevance
@@ -826,10 +829,19 @@ class SemanticSearcher:
             np.linalg.norm(self.embeddings, axis=1) * np.linalg.norm(query_embedding)
         )
 
+        if keep is not None:
+            # Nodes outside `keep` never enter the pool
+            kept = np.fromiter(
+                (n["id"] in keep for n in self.nodes), bool, len(self.nodes)
+            )
+            similarities = np.where(kept, similarities, -np.inf)
+            if not kept.any():
+                return []
+
         # Take a candidate pool by base score, then apply min_score to the
         # final score, so a node whose boosts (worth up to +0.17) lift it over
         # the threshold is kept.
-        pool = min(len(similarities), limit * 3)
+        pool = min(len(similarities) if keep is None else int(kept.sum()), limit * 3)
         top_indices = np.argpartition(-similarities, pool - 1)[:pool]
         top_indices = top_indices[np.argsort(-similarities[top_indices])]
 

{descry_codegraph-0.3.3 → descry_codegraph-0.3.4}/src/descry/handlers.py

@@ -2086,23 +2086,23 @@ class DescryService:
                 # and respects the cache lock).
                 searcher = await self._get_semantic_searcher()
                 if searcher is not None:
+                    # Under the filters the keyword side has
                     semantic_results = await asyncio.to_thread(
                         searcher.search,
                         " ".join(terms),
                         limit=limit * 2,
                         min_score=0.25,
+                        keep=q.filtered_ids(lang, crate, symbol_type, exclude_tests),
                     )
             except Exception as e:  # noqa: BLE001 — boundary over the embedding backend; search degrades to keyword-only
                 logger.warning(f"Semantic search failed, using keyword only: {e}")
 
-        if semantic_results and tfidf_results:
+        if semantic_results:
             combined = reciprocal_rank_fusion(tfidf_results, semantic_results)
             results = [node for node, _ in combined[:limit]]
             method = "hybrid"
-        elif tfidf_results:
-            results = tfidf_results[:limit]
         else:
-            results = []
+            results = tfidf_results[:limit]
 
         return {"ok": True, "error": None, "results": results, "method": method}
 

{descry_codegraph-0.3.3 → descry_codegraph-0.3.4}/src/descry/query.py

@@ -1318,7 +1318,8 @@ class GraphQuerier:
         once, at the first level that reaches it, and met again as `seen`,
         the level of that entry (the start is level 0).
         Returns ``(root, path, cut)``: the tree, the node IDs from the start
-        to the first node named ``target``, and why it stopped early
+        to the first node ``target`` names, by name or node ID, and why it
+        stopped early
         ("timeout", "node limit") or None."""
         start_time = time.time()
 
@@ -1353,7 +1354,7 @@ class GraphQuerier:
 
         root = tree_node(start_id, None)
         paths = {start_id: [start_id]}
-        if target and root["name"] == target:
+        if target in (root["name"], root["id"]):
             return root, paths[start_id], None
         level = [root]
         for _ in range(depth):
@@ -1378,7 +1379,7 @@ class GraphQuerier:
                     child = tree_node(child_id, marks.get(child_id))
                     paths[child_id] = [*paths[parent["id"]], child_id]
                     parent["children"].append(child)
-                    if target and child["name"] == target:
+                    if target in (child["name"], child["id"]):
                         return root, paths[child_id], None
                     next_level.append(child)
             level = next_level
@@ -1500,7 +1501,7 @@ class GraphQuerier:
         cut (why the trace stopped early, when it did). Each tree node has: id,
         name, type, tokens, file, line, code, lang, candidates, children,
         more, more_possible, and `seen`, the level its entry is at, where it
-        is placed there already. The trace stops at the first node named `target`.
+        is placed there already. The trace stops at the first node `target` names, by name or node ID.
         """
         if timeout_ms is None:
             timeout_ms = self._timeout_ms
@@ -1666,6 +1667,33 @@ class GraphQuerier:
             idf[term] = math.log((total_docs + 1) / (df + 1)) + 1
         return idf
 
+    def filtered_ids(
+        self, lang=None, crate=None, symbol_type=None, exclude_tests=False
+    ):
+        """The IDs of the nodes `search_docs`'s filters keep, None when none
+        is given: the language, the crate or module, the type, and no tests."""
+        if not (lang or crate or symbol_type or exclude_tests):
+            return None
+        self._ensure_filter_indices()
+        kept = set(self.nodes.keys())
+        if exclude_tests and self._index_is_test:
+            kept -= self._index_is_test
+        if crate:
+            kept &= self._index_by_crate.get(crate, set())
+        if lang and lang != "all":
+            lang = _LANG_ALIASES.get(lang.lower(), lang.lower())
+            kept &= self._index_by_lang.get(lang, set())
+        if symbol_type and symbol_type != "all":
+            type_map = {
+                "function": "Function",
+                "class": "Class",
+                "method": "Method",
+                "constant": "Constant",
+                "file": "File",
+            }
+            kept &= self._index_by_type.get(type_map.get(symbol_type.lower()), set())
+        return kept
+
     def search_docs(
         self, query_terms, lang=None, crate=None, symbol_type=None, exclude_tests=False
     ):
@@ -1695,38 +1723,10 @@ class GraphQuerier:
         if num_terms == 0:
             return []
 
-        # Apply filters if any specified
-        if lang or crate or symbol_type or exclude_tests:
-            self._ensure_filter_indices()
-            candidate_ids = set(self.nodes.keys())
-
-            # Filter out test files and functions if requested
-            if exclude_tests and self._index_is_test:
-                candidate_ids -= self._index_is_test
-
-            if crate:
-                # If crate filter specified but doesn't exist, return empty results
-                if crate not in self._index_by_crate:
-                    return []
-                candidate_ids &= self._index_by_crate[crate]
-            if lang and lang != "all":
-                lang = _LANG_ALIASES.get(lang.lower(), lang.lower())
-                candidate_ids &= self._index_by_lang.get(lang, set())
-            if symbol_type and symbol_type != "all":
-                type_map = {
-                    "function": "Function",
-                    "class": "Class",
-                    "method": "Method",
-                    "constant": "Constant",
-                    "file": "File",
-                }
-                type_key = type_map.get(symbol_type.lower())
-                if type_key and type_key in self._index_by_type:
-                    candidate_ids &= self._index_by_type[type_key]
-
-            candidates = [self.nodes[nid] for nid in candidate_ids]
-        else:
-            candidates = self.data["nodes"]
+        kept = self.filtered_ids(lang, crate, symbol_type, exclude_tests)
+        candidates = (
+            self.data["nodes"] if kept is None else [self.nodes[nid] for nid in kept]
+        )
 
         for node in candidates:
             score = 0.0

{descry_codegraph-0.3.3 → descry_codegraph-0.3.4}/tests/test_cli.py

@@ -225,3 +225,29 @@ class TestCliStopped:
         index.send_signal(signal.SIGHUP)
         assert not indexer_tree.grandchild_exited(timeout=1)
         assert index.poll() is None
+
+
+class TestSearchType:
+    """`--type` takes the types descry has, in any case, and refuses others."""
+
+    def test_a_type_is_passed_lowercased(self, monkeypatch):
+        seen = {}
+
+        class Service:
+            async def search(self, **kwargs):
+                seen.update(kwargs)
+                return "ok"
+
+        monkeypatch.setattr(cli, "_make_service", Service)
+        monkeypatch.setattr(
+            sys, "argv", ["descry", "search", "x", "--type", "Function"]
+        )
+        cli.main()
+        assert seen["symbol_type"] == "function"
+
+    def test_an_unknown_type_is_refused(self, monkeypatch, capsys):
+        monkeypatch.setattr(sys, "argv", ["descry", "search", "x", "--type", "struct"])
+        with pytest.raises(SystemExit) as exit_:
+            cli.main()
+        assert exit_.value.code == 2
+        assert "invalid choice: 'struct'" in capsys.readouterr().err

{descry_codegraph-0.3.3 → descry_codegraph-0.3.4}/tests/test_embeddings.py

@@ -434,6 +434,26 @@ class TestSearchScoring:
         with pytest.raises(EmbeddingCacheMismatch):
             s.search("anything", limit=3)
 
+    def test_kept_nodes_are_the_pool_others_never_enter(self, fake_model, graph_writer):
+        """A filter applies before the pool is cut, so a kept node far down
+        the ranking is still found."""
+        s = SemanticSearcher(str(graph_writer()))
+        dim = s.embeddings.shape[1]
+        s.embeddings = np.zeros((len(s.nodes), dim), dtype="float32")
+        s.embeddings[:, 0] = 1.0
+        last = len(s.nodes) - 1
+        s.embeddings[last] = 0.0
+        s.embeddings[last, 1] = 1.0
+        q = np.zeros(dim, dtype="float32")
+        q[0], q[1] = 1.0, 0.1
+        s.model = FakeSentenceTransformer(dim=dim, prompts={})
+        s.model.encode = lambda texts, **kw: q.reshape(1, -1)
+        wanted = s.nodes[last]["id"]
+
+        hits = s.search("q", limit=1, min_score=-1.0, keep={wanted})
+        assert [n["id"] for n, _ in hits] == [wanted]
+        assert s.search("q", limit=1, min_score=-1.0, keep=set()) == []
+
     def test_results_are_sorted_and_limited(self, fake_model, graph_writer):
         s = SemanticSearcher(str(graph_writer()))
         hits = s.search("alpha", limit=2, min_score=-1.0)

{descry_codegraph-0.3.3 → descry_codegraph-0.3.4}/tests/test_handlers.py

@@ -1709,3 +1709,41 @@ async def test_a_context_budget_below_one_is_refused(tmp_path, bound):
     result = await DescryService(config).context("FILE:x.py::f", depth=2, **{bound: 0})
     assert isinstance(result, ServiceError)
     assert f"{bound} must be at least 1, got 0." in result
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("terms", "lang", "found"),
+    [
+        (["who", "talks", "to", "nothing"], None, ["FILE:x.py::f", "FILE:y.rs::g"]),
+        (["who", "talks", "to", "nothing"], "python", ["FILE:x.py::f"]),
+        # The keywords find `f` too; the semantic side is still filtered
+        (["f"], "python", ["FILE:x.py::f"]),
+    ],
+)
+async def test_search_keeps_semantic_matches_no_keyword_finds(
+    tmp_path, terms, lang, found
+):
+    """The semantic side runs because the keywords found little; what it
+    finds is answered, under the same filters as the keywords."""
+    config = _plain_config(tmp_path)
+    py = {"id": "FILE:x.py::f", "type": "Function", "metadata": {"name": "f"}}
+    rs = {"id": "FILE:y.rs::g", "type": "Function", "metadata": {"name": "g"}}
+    _write_graph(config, nodes=[py, rs])
+    svc = DescryService(config)
+
+    class Searcher:
+        def __init__(self, graph_path, **kwargs):
+            pass
+
+        def ensure_model(self):
+            pass
+
+        def search(self, query, limit=10, min_score=0.0, keep=None):
+            return [
+                r for r in [(py, 0.9), (rs, 0.8)] if keep is None or r[0]["id"] in keep
+            ]
+
+    svc._semantic_available, svc._SemanticSearcher = True, Searcher
+    data = await svc.search_data(terms, lang=lang)
+    assert ([n["id"] for n in data["results"]], data["method"]) == (found, "hybrid")

{descry_codegraph-0.3.3 → descry_codegraph-0.3.4}/tests/test_query.py

@@ -301,12 +301,16 @@ class TestFindCallPath:
 
         os.unlink(f.name)
 
+    @pytest.mark.parametrize(
+        "target", ["validate_token", "FILE:auth.rs::validate_token"]
+    )
     def test_structured_flow_stops_at_the_target_and_reports_the_path(
-        self, call_path_graph
+        self, call_path_graph, target
     ):
+        """The target is named by name or by node ID."""
         q = GraphQuerier(call_path_graph)
 
-        tree = q.trace_flow_structured("handle_request", target="validate_token")
+        tree = q.trace_flow_structured("handle_request", target=target)
 
         assert tree["path_to_target"] == [
             "handle_request",
@@ -1073,6 +1077,14 @@ class TestLanguageFilter:
     def test_all_and_none_do_not_filter(self, querier, lang):
         assert len(querier.search_docs(["handler"], lang=lang)) == len(self.FILES)
 
+    @pytest.mark.parametrize(
+        ("kind", "found"), [("function", len(FILES)), ("class", 0), ("struct", 0)]
+    )
+    def test_type_keeps_only_that_type(self, querier, kind, found):
+        """A type the graph has none of, or no type descry has, matches
+        nothing, as an unknown language does."""
+        assert len(querier.search_docs(["handler"], symbol_type=kind)) == found
+
 
 class TestCallPathDepthAndOutcome:
     def _chain(self, tmp_path, length, **config):