codegraph-brain 0.19.0__tar.gz → 0.20.0__tar.gz

codegraph_brain-0.20.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.20.0"
+}

{codegraph_brain-0.19.0 → codegraph_brain-0.20.0}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.20.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.19.0...codegraph-brain-v0.20.0) (2026-09-11)
+
+
+### Features
+
+* **query:** a traversal says how much of its neighbourhood resolved ([#201](https://github.com/zaebee/codegraph-brain/issues/201)) ([#448](https://github.com/zaebee/codegraph-brain/issues/448)) ([0c63469](https://github.com/zaebee/codegraph-brain/commit/0c634697789f5264316c8a218e993f13a9a0f73f))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#449](https://github.com/zaebee/codegraph-brain/issues/449)) ([e9eccae](https://github.com/zaebee/codegraph-brain/commit/e9eccae8d43e8dc264ca87f8ea0a45752471f079))
+
 ## [0.19.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.18.0...codegraph-brain-v0.19.0) (2026-09-09)
 
 

{codegraph_brain-0.19.0 → codegraph_brain-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.19.0
+Version: 0.20.0
 Summary: Semantic code graph for AI agents — deterministic FQN resolution, impact analysis and architectural drift gates, exposed over MCP.
 Project-URL: Homepage, https://github.com/zaebee/codegraph-brain
 Project-URL: Repository, https://github.com/zaebee/codegraph-brain

{codegraph_brain-0.19.0 → codegraph_brain-0.20.0}/docs/how-to/MCP_REFERENCE.md

@@ -10,9 +10,13 @@
 Analyse transitive upstream callers of a specific FQN.
 
     Answers "what breaks if I change X?". ``output_format="mermaid"`` (default)
-    returns a diagram; ``"json"`` returns a joinable ``{root, nodes, edges}``
-    payload with real FQNs — letting an agent compute set differences (e.g.
-    "which route handlers never reach ``verify_ownership``?") directly.
+    returns a diagram; ``"json"`` returns a joinable ``{root, nodes, edges,
+    coverage}`` payload with real FQNs — letting an agent compute set
+    differences (e.g. "which route handlers never reach ``verify_ownership``?")
+    directly. ``coverage`` counts unresolved calls whose name matches a
+    traversed function, method or class: callers that may be missing, named in
+    ``top_unresolved``. It is an upper bound — a common name matches calls on
+    unrelated objects, which the names make visible.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
@@ -325,8 +329,12 @@ Suggest sub-package boundaries for a package from its dependency communities.
 Trace the execution call-graph starting from a specific FQN downwards.
 
     ``output_format="mermaid"`` (default) returns a human-readable diagram;
-    ``"json"`` returns a joinable ``{root, nodes, edges}`` payload with real
-    FQNs (not display hashes) for agent/CI use. Use ``cgis_ingest`` first if
+    ``"json"`` returns a joinable ``{root, nodes, edges, coverage}`` payload
+    with real FQNs (not display hashes) for agent/CI use. ``coverage`` counts
+    the calls the traversed functions make that resolved to nothing, and
+    ``top_unresolved`` names the most frequent. Read the names, not only the
+    ratio: in Python most are methods on untyped locals (``logger.info``,
+    ``items.append``), which cut nothing short. Use ``cgis_ingest`` first if
     the database does not exist yet.
 
 | Argument | Type | Required | Description |

{codegraph_brain-0.19.0 → codegraph_brain-0.20.0}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.19.0"
+version = "0.20.0"
 description = "Semantic code graph for AI agents — deterministic FQN resolution, impact analysis and architectural drift gates, exposed over MCP."
 readme = "README.md"
 requires-python = ">=3.12"

{codegraph_brain-0.19.0 → codegraph_brain-0.20.0}/src/cgis/api/mcp_server.py

@@ -13,6 +13,7 @@ from typing import Any
 import structlog
 from mcp.server.mcpserver import MCPServer
 
+from cgis.core.coverage import TraversalCoverage
 from cgis.core.freshness import Freshness, FreshnessState
 from cgis.core.models import Edge, Node, NodeType
 from cgis.extractors.python_extractor import PythonExtractor
@@ -64,6 +65,11 @@ def _blank_fqn_error(fqn: str) -> str | None:
     return None
 
 
+def _wants_json(output_format: str) -> bool:
+    """True when a traversal will be rendered as JSON — the only shape that carries coverage."""
+    return output_format.strip().lower() == "json"
+
+
 def _render_subgraph_with_freshness(
     db_path: str,
     output_format: str,
@@ -72,10 +78,11 @@ def _render_subgraph_with_freshness(
     title: str,
     nodes: list[Node],
     edges: list[Edge],
+    coverage: TraversalCoverage | None = None,
 ) -> str:
     """`_render_subgraph`, with this database's freshness measured for it (#175)."""
     return _render_subgraph(
-        output_format, root, note, title, nodes, edges, _graph_freshness(db_path)
+        output_format, root, note, title, nodes, edges, _graph_freshness(db_path), coverage
     )
 
 
@@ -87,6 +94,7 @@ def _render_subgraph(
     nodes: list[Node],
     edges: list[Edge],
     freshness: "Freshness | None" = None,
+    coverage: TraversalCoverage | None = None,
 ) -> str:
     """Render a traversal result as a Mermaid diagram or joinable JSON (#171).
 
@@ -98,11 +106,12 @@ def _render_subgraph(
     ``freshness`` is placed differently in each: a key inside the JSON object,
     a prose note above the diagram. Prefixing the JSON would make it unparseable
     exactly when the graph goes stale, and this renderer is the only place that
-    knows which shape it is about to produce (#175).
+    knows which shape it is about to produce (#175). ``coverage`` (#201) rides
+    in the JSON only.
     """
     fmt = output_format.strip().lower()
     if fmt == "json":
-        payload = graph_to_json(root, nodes, edges)
+        payload = graph_to_json(root, nodes, edges, coverage)
         if freshness is not None and freshness.state is not FreshnessState.FRESH:
             payload = {**payload, "freshness": freshness.model_dump()}
         return json.dumps(payload, indent=2)
@@ -300,8 +309,12 @@ def cgis_trace_flow(
     """Trace the execution call-graph starting from a specific FQN downwards.
 
     ``output_format="mermaid"`` (default) returns a human-readable diagram;
-    ``"json"`` returns a joinable ``{root, nodes, edges}`` payload with real
-    FQNs (not display hashes) for agent/CI use. Use ``cgis_ingest`` first if
+    ``"json"`` returns a joinable ``{root, nodes, edges, coverage}`` payload
+    with real FQNs (not display hashes) for agent/CI use. ``coverage`` counts
+    the calls the traversed functions make that resolved to nothing, and
+    ``top_unresolved`` names the most frequent. Read the names, not only the
+    ratio: in Python most are methods on untyped locals (``logger.info``,
+    ``items.append``), which cut nothing short. Use ``cgis_ingest`` first if
     the database does not exist yet.
     """
     if blank := _blank_fqn_error(fqn):
@@ -313,13 +326,22 @@ def cgis_trace_flow(
             res = resolve_fqn(store, fqn)
             if res.resolved is None:
                 return _resolution_error(fqn, res.candidates, res.truncated)
-            nodes, edges = QueryEngine(store).get_flow_graph(res.resolved, max_depth=depth)
+            result = QueryEngine(store).get_flow_result(
+                res.resolved, max_depth=depth, with_coverage=_wants_json(output_format)
+            )
     except Exception as exc:
         return f"❌ {exc}"
 
     note = f"> Resolved '{fqn}' → '{res.resolved}'\n\n" if res.via_suffix else ""
     return _render_subgraph_with_freshness(
-        db_path, output_format, res.resolved, note, "Execution flow for", nodes, edges
+        db_path,
+        output_format,
+        res.resolved,
+        note,
+        "Execution flow for",
+        result.nodes,
+        result.edges,
+        result.coverage,
     )
 
 
@@ -330,9 +352,13 @@ def cgis_analyze_impact(
     """Analyse transitive upstream callers of a specific FQN.
 
     Answers "what breaks if I change X?". ``output_format="mermaid"`` (default)
-    returns a diagram; ``"json"`` returns a joinable ``{root, nodes, edges}``
-    payload with real FQNs — letting an agent compute set differences (e.g.
-    "which route handlers never reach ``verify_ownership``?") directly.
+    returns a diagram; ``"json"`` returns a joinable ``{root, nodes, edges,
+    coverage}`` payload with real FQNs — letting an agent compute set
+    differences (e.g. "which route handlers never reach ``verify_ownership``?")
+    directly. ``coverage`` counts unresolved calls whose name matches a
+    traversed function, method or class: callers that may be missing, named in
+    ``top_unresolved``. It is an upper bound — a common name matches calls on
+    unrelated objects, which the names make visible.
     """
     if blank := _blank_fqn_error(fqn):
         return blank
@@ -343,13 +369,22 @@ def cgis_analyze_impact(
             res = resolve_fqn(store, fqn)
             if res.resolved is None:
                 return _resolution_error(fqn, res.candidates, res.truncated)
-            nodes, edges = QueryEngine(store).get_impact_graph(res.resolved, max_depth=depth)
+            result = QueryEngine(store).get_impact_result(
+                res.resolved, max_depth=depth, with_coverage=_wants_json(output_format)
+            )
     except Exception as exc:
         return f"❌ {exc}"
 
     note = f"> Resolved '{fqn}' → '{res.resolved}'\n\n" if res.via_suffix else ""
     return _render_subgraph_with_freshness(
-        db_path, output_format, res.resolved, note, "Impact analysis for", nodes, edges
+        db_path,
+        output_format,
+        res.resolved,
+        note,
+        "Impact analysis for",
+        result.nodes,
+        result.edges,
+        result.coverage,
     )
 
 

{codegraph_brain-0.19.0 → codegraph_brain-0.20.0}/src/cgis/cli.py

@@ -31,6 +31,7 @@ from rich.table import Table
 from rich.tree import Tree
 
 from cgis import __app_name__, __version__
+from cgis.core.coverage import TraversalCoverage
 from cgis.core.freshness import FreshnessState
 from cgis.core.models import VIRTUAL_FILE_PATH, Edge, EdgeType, Node, NodeNamespace, NodeType
 from cgis.extractors.python_extractor import file_path_to_module_fqn
@@ -287,12 +288,17 @@ def _render_graph(
     nodes: list[Node],
     edges: list[Edge],
     internal_only: bool = False,
+    coverage: TraversalCoverage | None = None,
 ) -> str:
-    """Render a subgraph for a non-text format (Mermaid for eyes, JSON for agents)."""
+    """Render a subgraph for a non-text format (Mermaid for eyes, JSON for agents).
+
+    ``coverage`` was measured by the engine before ``internal_only`` filters
+    anything, so the filter cannot hide the unresolved calls it removes (#201).
+    """
     if internal_only:
         nodes, edges = _filter_internal(nodes, edges)
     if output_format == OutputFormat.JSON:
-        return _json.dumps(graph_to_json(root, nodes, edges), indent=2)
+        return _json.dumps(graph_to_json(root, nodes, edges, coverage), indent=2)
     return MermaidCompiler().compile(nodes, edges)
 
 
@@ -412,14 +418,19 @@ def trace(
             raise typer.Exit(code=1)
 
         if output_format != OutputFormat.TEXT:
-            nodes, edges = QueryEngine(store).get_flow_graph(
+            flow = QueryEngine(store).get_flow_result(
                 start,
+                with_coverage=output_format == OutputFormat.JSON,
                 max_depth=depth,
                 allowed_edge_types=allowed,
                 show_external=show_external,
                 min_confidence=min_confidence,
             )
-            typer.echo(_render_graph(output_format, start, nodes, edges, internal_only))
+            typer.echo(
+                _render_graph(
+                    output_format, start, flow.nodes, flow.edges, internal_only, flow.coverage
+                )
+            )
         else:
             if internal_only:
                 raise typer.BadParameter(_INTERNAL_ONLY_TEXT_ERR)
@@ -544,14 +555,24 @@ def impact(
             raise typer.Exit(code=1)
 
         if output_format != OutputFormat.TEXT:
-            nodes, edges = QueryEngine(store).get_impact_graph(
+            impact_result = QueryEngine(store).get_impact_result(
                 target,
+                with_coverage=output_format == OutputFormat.JSON,
                 max_depth=depth,
                 allowed_edge_types=allowed,
                 show_external=show_external,
                 min_confidence=min_confidence,
             )
-            typer.echo(_render_graph(output_format, target, nodes, edges, internal_only))
+            typer.echo(
+                _render_graph(
+                    output_format,
+                    target,
+                    impact_result.nodes,
+                    impact_result.edges,
+                    internal_only,
+                    impact_result.coverage,
+                )
+            )
         else:
             if internal_only:
                 raise typer.BadParameter(_INTERNAL_ONLY_TEXT_ERR)

codegraph_brain-0.20.0/src/cgis/core/coverage.py

@@ -0,0 +1,57 @@
+"""How much of a traversal's neighbourhood the graph could actually place (#201).
+
+`cgis validate` reports resolution health for the whole graph. An agent holding
+one `trace_flow` or `analyze_impact` answer needs the local version: were the
+calls around *this* result resolved, or is the answer short because they were not?
+"""
+
+from collections.abc import Mapping
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, computed_field
+
+#: How many unresolved targets a coverage report names. The counts cover all of them.
+TOP_UNRESOLVED_LIMIT = 10
+
+#: What `calls_unresolved` counts, which differs by traversal direction.
+#:
+#: ``unresolved_calls_made`` — calls the expanded nodes make that resolved to
+#: nothing: dead ends downstream. Exact.
+#:
+#: ``unresolved_calls_by_name`` — unresolved calls anywhere in the graph whose
+#: called name matches an expanded node: callers that may be missing upstream.
+#: An upper bound — a name is not an identity, and a common one (``items``)
+#: matches calls on unrelated objects.
+CoverageBasis = Literal["unresolved_calls_made", "unresolved_calls_by_name"]
+
+
+def rank_unresolved(counts: Mapping[str, int]) -> list[tuple[str, int]]:
+    """The most frequent unresolved targets first, ties by name, at most `TOP_UNRESOLVED_LIMIT`."""
+    return sorted(counts.items(), key=lambda item: (-item[1], item[0]))[:TOP_UNRESOLVED_LIMIT]
+
+
+class TraversalCoverage(BaseModel):
+    """Resolution coverage of the CALLS edges around one traversal result.
+
+    ``top_unresolved`` names what the counts are made of, because a ratio alone
+    cannot tell ``logger.info`` from ``billing.charge``. On cgis's own
+    ``IngestionPipeline.run`` (``cgis trace --depth 3`` at 7eb324b) 92 of 235
+    calls are unresolved, and the most frequent are ``logger.info``,
+    ``edge.model_copy`` and ``resolved_edges.append`` — methods on untyped
+    locals, none of them a first-party call the flow is missing.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    basis: CoverageBasis
+    calls_examined: int
+    calls_unresolved: int
+    top_unresolved: list[tuple[str, int]] = Field(default_factory=list)
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def unresolved_ratio(self) -> float:
+        """Share of the examined calls that are unresolved; 0.0 when none were examined."""
+        if not self.calls_examined:
+            return 0.0
+        return self.calls_unresolved / self.calls_examined