codegraph-brain 0.23.0__tar.gz → 0.23.1__tar.gz

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

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

{codegraph_brain-0.23.0 → codegraph_brain-0.23.1}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.23.1](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.23.0...codegraph-brain-v0.23.1) (2026-09-17)
+
+
+### Bug Fixes
+
+* **audit:** an audit that selects no sources is an error, not an empty pass ([#472](https://github.com/zaebee/codegraph-brain/issues/472)) ([9f93010](https://github.com/zaebee/codegraph-brain/commit/9f93010c286d0b189f3c3350833a5cf557316d8f))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#468](https://github.com/zaebee/codegraph-brain/issues/468)) ([4c02171](https://github.com/zaebee/codegraph-brain/commit/4c021719776d00ae2f3539409ba847995f79c48e))
+* auto-sync architecture graph and MCP reference ([#473](https://github.com/zaebee/codegraph-brain/issues/473)) ([567b091](https://github.com/zaebee/codegraph-brain/commit/567b09190c61ab5fc2b5b26c0b445bff2cbe5a12))
+
 ## [0.23.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.22.0...codegraph-brain-v0.23.0) (2026-09-17)
 
 

{codegraph_brain-0.23.0 → codegraph_brain-0.23.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.23.0
+Version: 0.23.1
 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.23.0 → codegraph_brain-0.23.1}/docs/how-to/MCP_REFERENCE.md

@@ -20,10 +20,10 @@ Analyse transitive upstream callers of a specific FQN.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `fqn` | `string` | ✓ |  |
-| `db_path` | `string` |  |  |
-| `depth` | `integer` |  |  |
-| `output_format` | `string` |  |  |
+| `fqn` | `string` | ✓ | Fully qualified name, e.g. pkg.module.Class.method. A unique dot-boundary suffix also resolves; an ambiguous one returns candidates. Use cgis_find_symbol to look a name up. |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `depth` | `integer` |  | Maximum edge hops upstream. Every edge type counts as a hop — CALLS, but also IMPORTS, CONTAINS and REFERENCES — so modules importing the target and the file containing it appear alongside its callers. |
+| `output_format` | `string` |  | "mermaid" for a diagram, or "json" for a payload with real FQNs (case-insensitive). Any other value returns an error. |
 
 ---
 
@@ -41,13 +41,16 @@ Reachability/authorization audit — which sources never reach a checkpoint (#17
     ``fqn``/``file``/``line``. Generalizes to validators, event tracking, or
     service-layer-boundary rules by pointing ``target`` at the required node.
 
+    A selection that matches no source returns a ❌ message, not an empty
+    ``{covered: [], gaps: []}`` that would read as a passing audit (#467).
+
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `target` | `string` | ✓ |  |
-| `db_path` | `string` |  |  |
-| `from_type` | `any` |  |  |
-| `from_prefix` | `any` |  |  |
-| `depth` | `integer` |  |  |
+| `target` | `string` | ✓ | FQN of the checkpoint every source must reach, e.g. an ownership check. A unique dot-boundary suffix also resolves. |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `from_type` | `any` |  | NodeType of the sources to audit, e.g. ROUTE_HANDLER, API_ENDPOINT or FUNCTION (any case). Give this, from_prefix, or both. |
+| `from_prefix` | `any` |  | Only audit sources at or under this FQN prefix, matched on whole dot-segments. A selection matching no source is an error naming the whole-segment prefixes it may have meant. Combined with from_type when both are given. |
+| `depth` | `integer` |  | Maximum reachability depth; a longer path is reported as a gap. |
 
 ---
 
@@ -70,10 +73,10 @@ Compile an agent-facing GraphRAG context package for a focal FQN (#19).
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `fqn` | `string` | ✓ |  |
-| `db_path` | `string` |  |  |
-| `depth` | `integer` |  |  |
-| `source_root` | `string` |  |  |
+| `fqn` | `string` | ✓ | Fully qualified name, e.g. pkg.module.Class.method. A unique dot-boundary suffix also resolves; an ambiguous one returns candidates. Use cgis_find_symbol to look a name up. |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `depth` | `integer` |  | Call hops around the focal node; 1 means direct callers and callees. |
+| `source_root` | `string` |  | Directory the graph's stored file paths are relative to — normally the project_path given to cgis_ingest; prefer an absolute path. Empty means the server's working directory, so source shows as unavailable when the server runs elsewhere. |
 
 ---
 
@@ -102,11 +105,11 @@ Report per-domain architectural drift against declared ideal patterns.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `db_path` | `string` |  |  |
-| `patterns_path` | `string` |  |  |
-| `max_drift` | `number` |  |  |
-| `profile` | `any` |  |  |
-| `max_residual` | `number` |  |  |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `patterns_path` | `string` |  | patterns.yaml (.yaml or .yml) declaring each domain's expected pattern and tolerance, relative to the server's working directory. cgis_init_ontology proposes one. |
+| `max_drift` | `number` |  | Drift tolerance for domains that declare no drift_tolerance of their own. |
+| `profile` | `any` |  | Score only domains with this profile, plus profile-less ones — e.g. one language when patterns.yaml mixes several. |
+| `max_residual` | `number` |  | Distance to the nearest template beyond which a domain's fit band is "none" (no template fits). |
 
 ---
 
@@ -150,10 +153,10 @@ Classes nothing in production builds, extends or names — dead-code candidates
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `db_path` | `string` |  |  |
-| `prefix` | `any` |  |  |
-| `include_tests` | `boolean` |  |  |
-| `include_generated` | `boolean` |  |  |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `prefix` | `any` |  | Only consider classes under this FQN prefix, cut on a dot boundary. |
+| `include_tests` | `boolean` |  | Count test code as a user, so the report means "unreachable from anywhere". |
+| `include_generated` | `boolean` |  | Include machine-generated classes, which are hidden by default. |
 
 ---
 
@@ -170,11 +173,11 @@ Resolve a partial symbol name to candidate FQNs (substring match, ranked).
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `query` | `string` | ✓ |  |
-| `db_path` | `string` |  |  |
-| `kind` | `any` |  |  |
-| `fqn_prefix` | `any` |  |  |
-| `limit` | `integer` |  |  |
+| `query` | `string` | ✓ | Leaf symbol name to search for, without dots (e.g. get_flow_result) — not an FQN. Case-insensitive substring match, ranked exact > prefix > substring. |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `kind` | `any` |  | Only return this node type, e.g. FUNCTION, METHOD or CLASS (any case). An unknown type matches nothing rather than raising an error. |
+| `fqn_prefix` | `any` |  | Only return symbols at or under this FQN prefix, matched on whole dot-segments: app.svc does not match app.svc_alt, and a partial segment matches nothing. |
+| `limit` | `integer` |  | Maximum number of candidates to return. |
 
 ---
 
@@ -200,7 +203,7 @@ Report the motif census across the repository's structural tiers.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `db_path` | `string` |  |  |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
 
 ---
 
@@ -215,10 +218,10 @@ Show the structural layout (CONTAINS/DECLARES) of a module or class.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `fqn` | `string` | ✓ |  |
-| `db_path` | `string` |  |  |
-| `depth` | `integer` |  |  |
-| `output_format` | `string` |  |  |
+| `fqn` | `string` | ✓ | Fully qualified name, e.g. pkg.module.Class.method. A unique dot-boundary suffix also resolves; an ambiguous one returns candidates. Use cgis_find_symbol to look a name up. |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `depth` | `integer` |  | Maximum containment levels to descend (module → class → method). |
+| `output_format` | `string` |  | "mermaid" for a diagram, or "json" for a payload with real FQNs (case-insensitive). Any other value returns an error. |
 
 ---
 
@@ -245,9 +248,9 @@ Scan a local directory, extract all symbols, resolve links, and build the graph
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `project_path` | `string` | ✓ |  |
-| `db_path` | `string` |  |  |
-| `full_rebuild` | `boolean` |  |  |
+| `project_path` | `string` | ✓ | Root directory of the project to scan. A relative path resolves against the MCP server's working directory. |
+| `db_path` | `string` |  | Where to write the graph: must end in .db, .sqlite or .sqlite3, in a directory that already exists, and must not be an existing non-SQLite file. A relative path resolves against the server's working directory. |
+| `full_rebuild` | `boolean` |  | Re-scan every file from scratch instead of the incremental default. |
 
 ---
 
@@ -263,10 +266,10 @@ Propose a starter patterns.yaml from the measured graph (read-only).
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `db_path` | `string` |  |  |
-| `margin` | `number` |  |  |
-| `min_nodes` | `integer` |  |  |
-| `depth` | `any` |  |  |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `margin` | `number` |  | Headroom added to each measured score to form the proposed tolerance. |
+| `min_nodes` | `integer` |  | Domains with fewer nodes stay hygiene-only instead of getting a label. |
+| `depth` | `any` |  | Fixed FQN segment depth for domain discovery (positive); omit to pick it automatically. |
 
 ---
 
@@ -297,10 +300,10 @@ Whole-graph architectural metrics — coupling bottlenecks + God classes (#16).
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `db_path` | `string` |  |  |
-| `limit` | `integer` |  |  |
-| `exclude` | `any` |  |  |
-| `scope` | `any` |  |  |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `limit` | `integer` |  | Top-N rows returned per section. |
+| `exclude` | `any` |  | Drop nodes whose FQN contains any of these dot-segments, e.g. ["tests"]; they are removed from PageRank propagation too. |
+| `scope` | `any` |  | Keep only nodes under any of these dot-prefixes, e.g. ["domains.billing"]; rank still propagates over the whole graph. |
 
 ---
 
@@ -319,10 +322,10 @@ Suggest sub-package boundaries for a package from its dependency communities.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `db_path` | `string` |  |  |
-| `prefix` | `any` |  |  |
-| `with_calls` | `boolean` |  |  |
-| `min_q` | `number` |  |  |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `prefix` | `any` |  | FQN prefix of the package to analyse, e.g. cgis.query, matched on whole dot-segments. Needed in practice: without it the verdict is no_signal. |
+| `with_calls` | `boolean` |  | Use the combined import + call graph instead of imports only. |
+| `min_q` | `number` |  | Modularity threshold: at or above it, a package whose layout disagrees with its communities is flagged split (or consolidate, if over-split). |
 
 ---
 
@@ -341,10 +344,10 @@ Trace the execution call-graph starting from a specific FQN downwards.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `fqn` | `string` | ✓ |  |
-| `db_path` | `string` |  |  |
-| `depth` | `integer` |  |  |
-| `output_format` | `string` |  |  |
+| `fqn` | `string` | ✓ | Fully qualified name, e.g. pkg.module.Class.method. A unique dot-boundary suffix also resolves; an ambiguous one returns candidates. Use cgis_find_symbol to look a name up. |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `depth` | `integer` |  | Maximum edge hops downstream. Every edge type counts as a hop — CALLS, but also IMPORTS, CONTAINS and REFERENCES — so from a module the first hops are mostly imports and structure. |
+| `output_format` | `string` |  | "mermaid" for a diagram, or "json" for a payload with real FQNs (case-insensitive). Any other value returns an error. |
 
 ---
 
@@ -357,7 +360,7 @@ Report graph integrity as JSON: edge resolution stats + health verdict.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `db_path` | `string` |  |  |
-| `threshold` | `number` |  |  |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `threshold` | `number` |  | Highest unresolved-edge ratio (0-1) still reported as healthy. |
 
 ---

{codegraph_brain-0.23.0 → codegraph_brain-0.23.1}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.23.0"
+version = "0.23.1"
 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.23.0 → codegraph_brain-0.23.1}/server.json

@@ -8,13 +8,13 @@
     "source": "github",
     "id": "1260843154"
   },
-  "version": "0.23.0",
+  "version": "0.23.1",
   "packages": [
     {
       "registryType": "pypi",
       "registryBaseUrl": "https://pypi.org",
       "identifier": "codegraph-brain",
-      "version": "0.23.0",
+      "version": "0.23.1",
       "runtimeHint": "uvx",
       "transport": {
         "type": "stdio"

{codegraph_brain-0.23.0 → codegraph_brain-0.23.1}/src/cgis/api/mcp_server.py

@@ -966,8 +966,9 @@ def cgis_audit_reachability(
         str | None,
         Field(
             description="Only audit sources at or under this FQN prefix, matched on whole "
-            "dot-segments — a partial segment selects nothing and returns an empty audit, "
-            "not a clean one. Combined with from_type when both are given."
+            "dot-segments. A selection matching no source is an error naming the "
+            "whole-segment prefixes it may have meant. Combined with from_type when both "
+            "are given."
         ),
     ] = None,
     depth: Annotated[
@@ -986,6 +987,9 @@ def cgis_audit_reachability(
     one is required. Returns JSON ``{target, covered, gaps}`` where each gap carries
     ``fqn``/``file``/``line``. Generalizes to validators, event tracking, or
     service-layer-boundary rules by pointing ``target`` at the required node.
+
+    A selection that matches no source returns a ❌ message, not an empty
+    ``{covered: [], gaps: []}`` that would read as a passing audit (#467).
     """
     if blank := _blank_fqn_error(target):
         return blank

{codegraph_brain-0.23.0 → codegraph_brain-0.23.1}/src/cgis/cli.py

@@ -42,7 +42,7 @@ from cgis.query.analysis.analyzer import AnalyzerEngine
 from cgis.query.analysis.anomaly import AnomalyType, ArchitecturalAnomaly
 from cgis.query.analysis.health import HealthScorer
 from cgis.query.analysis.suggest_service import SuggestReport, report_to_dict, suggest_packages
-from cgis.query.context.audit import ReachabilityAudit, audit_reachability
+from cgis.query.context.audit import NoAuditSourcesError, ReachabilityAudit, audit_reachability
 from cgis.query.context.context_service import build_context
 from cgis.query.context.orphans import OrphanReport, find_orphan_classes
 from cgis.query.drift.drift import DriftReport, FitQuality
@@ -1445,7 +1445,7 @@ def audit(
         help="Only audit nodes of this type (e.g. ROUTE_HANDLER, API_ENDPOINT).",
     ),
     from_prefix: str | None = typer.Option(
-        None, "--from-prefix", help="Only audit nodes whose FQN starts with this prefix."
+        None, "--from-prefix", help="Only audit nodes under this FQN prefix (whole dot-segments)."
     ),
     db: str = typer.Option(_DEFAULT_DB, "--db", "-d", help=_DEFAULT_DB_HELP),
     depth: int = typer.Option(
@@ -1487,13 +1487,19 @@ def audit(
 
     with SQLiteStore(db) as store:
         resolved = _resolve_checkpoint(store, target)
-        result = audit_reachability(
-            store,
-            target_fqn=resolved,
-            from_type=from_type,
-            from_prefix=from_prefix,
-            max_depth=depth,
-        )
+        try:
+            result = audit_reachability(
+                store,
+                target_fqn=resolved,
+                from_type=from_type,
+                from_prefix=from_prefix,
+                max_depth=depth,
+            )
+        except NoAuditSourcesError as exc:
+            # Exit 2 like a bad selector: exit 0 here let a typo'd prefix pass a CI gate (#467).
+            # stderr, like _resolve_checkpoint: `--format json` stdout stays a clean payload.
+            err_console.print(f"[bold red]❌ {escape(str(exc))}[/bold red]")
+            raise typer.Exit(code=2) from exc
 
     if output_format == OutputFormat.JSON:
         typer.echo(_json.dumps(dataclasses.asdict(result), indent=2))

{codegraph_brain-0.23.0 → codegraph_brain-0.23.1}/src/cgis/query/context/audit.py

@@ -51,29 +51,100 @@ class ReachabilityAudit:
     gaps: list[NodeRef]
 
 
+class NoAuditSourcesError(ValueError):
+    """The selectors matched no source to audit, so there is no result to report (#467).
+
+    Raised instead of returning empty ``covered``/``gaps``: callers — and CI gates
+    reading ``gaps == []`` — would otherwise take an audit of nothing for a clean one.
+    """
+
+
+_SUGGESTION_LIMIT = 5
+
+
+def _describe_selection(from_type: NodeType | None, from_prefix: str | None) -> str:
+    """Render the selectors the way a caller passed them, for the error message."""
+    parts = []
+    if from_type is not None:
+        parts.append(f"from_type={from_type.value}")
+    if from_prefix is not None:
+        parts.append(f"from_prefix={from_prefix!r}")
+    return " and ".join(parts)
+
+
 def _prefix_matches(fqn: str, prefix: str) -> bool:
     """Dot-boundary prefix match — ``app.routes`` matches ``app.routes.x``, not ``app.routesX``."""
     return fqn == prefix or fqn.startswith(f"{prefix}.")
 
 
+def _is_candidate(node: Node, from_type: NodeType | None, target_fqn: str) -> bool:
+    """An INTERNAL node of the requested type that is not the checkpoint — a possible source."""
+    return (
+        node.namespace == NodeNamespace.INTERNAL
+        and (from_type is None or node.type == from_type)
+        and node.id != target_fqn
+    )
+
+
 def _select_sources(
-    store: SQLiteStore, from_type: NodeType | None, from_prefix: str | None
+    nodes: list[Node], target_fqn: str, from_type: NodeType | None, from_prefix: str | None
 ) -> list[Node]:
     """Select INTERNAL source nodes by node type and/or dot-boundary FQN prefix (AND-combined).
 
     Restricted to INTERNAL nodes so the audit never flags stdlib/third-party
     code, and the prefix is boundary-aware so a name overlap (``app.routesX``)
-    can't sneak into an ``app.routes`` selection.
+    can't sneak into an ``app.routes`` selection. The checkpoint is never its
+    own source.
     """
     return [
         node
-        for node in store.get_all_nodes()
-        if node.namespace == NodeNamespace.INTERNAL
-        and (from_type is None or node.type == from_type)
+        for node in nodes
+        if _is_candidate(node, from_type, target_fqn)
         and (from_prefix is None or _prefix_matches(node.id, from_prefix))
     ]
 
 
+def _empty_selection_hint(
+    nodes: list[Node], target_fqn: str, from_type: NodeType | None, from_prefix: str | None
+) -> str:
+    """Explain an empty selection: the whole-segment prefix meant, or what the prefix does hold.
+
+    Suggestions come from the same candidates ``_select_sources`` would accept, so
+    every suggested prefix selects at least one source. That also means the input
+    is never offered back: a candidate completing to ``from_prefix`` would itself
+    have been selected. A trailing dot is dropped first: ``app.routes.`` meant
+    ``app.routes``.
+    """
+    if from_prefix is None:
+        return ""
+    stem = from_prefix.rstrip(".")
+    suggestions: set[str] = set()
+    for node in nodes:
+        if _is_candidate(node, from_type, target_fqn) and node.id.startswith(stem):
+            next_dot = node.id.find(".", len(stem))
+            suggestions.add(node.id if next_dot == -1 else node.id[:next_dot])
+    if suggestions:
+        listing = ", ".join(sorted(suggestions)[:_SUGGESTION_LIMIT])
+        return f"Prefixes match whole dot-segments; did you mean: {listing}?"
+    under = [
+        n for n in nodes if n.namespace == NodeNamespace.INTERNAL and _prefix_matches(n.id, stem)
+    ]
+    if under and all(n.id == target_fqn for n in under):
+        return "Only the checkpoint itself is under that prefix, and it is never its own source."
+    if under and from_type is not None:
+        return f"There are nodes under that prefix, but none of type {from_type.value}."
+    return ""
+
+
+def _no_sources_error(
+    nodes: list[Node], target_fqn: str, from_type: NodeType | None, from_prefix: str | None
+) -> NoAuditSourcesError:
+    """Build the error for an empty selection, with a hint when one can be given."""
+    msg = f"No sources matched {_describe_selection(from_type, from_prefix)} — nothing was audited."
+    hint = _empty_selection_hint(nodes, target_fqn, from_type, from_prefix)
+    return NoAuditSourcesError(f"{msg} {hint}" if hint else msg)
+
+
 def _ref(node: Node) -> NodeRef:
     """Build a located reference from a node."""
     return NodeRef(fqn=node.id, file=node.file_path, line=node.start_line)
@@ -112,11 +183,20 @@ def audit_reachability(
     already-injected instance — so a dependency-injected collaborator looks like
     a gap. Target the specific method (or the constructor) when auditing "does X
     use this collaborator".
+
+    Raises:
+        NoAuditSourcesError: The selectors match no source other than the checkpoint
+            itself. An empty ``covered``/``gaps`` pair would read as a passing audit.
     """
     from_prefix = from_prefix.strip() or None if from_prefix is not None else None
     if from_type is None and from_prefix is None:
         msg = "audit_reachability requires from_type or a non-empty from_prefix to select sources."
         raise ValueError(msg)
+    nodes = store.get_all_nodes()
+    # Select before traversing: an empty selection has nothing to prove.
+    sources = _select_sources(nodes, target_fqn, from_type, from_prefix)
+    if not sources:
+        raise _no_sources_error(nodes, target_fqn, from_type, from_prefix)
     engine = QueryEngine(store)
     # `is not None`, not `or`: an explicit empty frozenset (no-traversal, target-only)
     # is a valid intent and must not be overridden by the enforcement default.
@@ -127,8 +207,6 @@ def audit_reachability(
     reaching = {node.id for node in upstream_nodes}
     covered: list[NodeRef] = []
     gaps: list[NodeRef] = []
-    for source in sorted(_select_sources(store, from_type, from_prefix), key=lambda n: n.id):
-        if source.id == target_fqn:
-            continue
+    for source in sorted(sources, key=lambda n: n.id):
         (covered if source.id in reaching else gaps).append(_ref(source))
     return ReachabilityAudit(target=target_fqn, covered=covered, gaps=gaps)

{codegraph_brain-0.23.0 → codegraph_brain-0.23.1}/tests/unit/test_audit.py

@@ -4,8 +4,8 @@ from pathlib import Path
 
 import pytest
 
-from cgis.core.models import Edge, EdgeType, Node, NodeType
-from cgis.query.context.audit import audit_reachability
+from cgis.core.models import Edge, EdgeType, Node, NodeNamespace, NodeType
+from cgis.query.context.audit import NoAuditSourcesError, audit_reachability
 from cgis.storage.sqlite_store import SQLiteStore
 
 
@@ -105,6 +105,102 @@ def test_audit_from_prefix_selects_sources(tmp_path: Path) -> None:
     assert {r.fqn for r in result.gaps} == {"app.routes.h3"}
 
 
+@pytest.mark.parametrize(
+    ("selector", "named"),
+    [
+        ({"from_prefix": "app.rou"}, "from_prefix='app.rou'"),  # partial dot-segment
+        ({"from_prefix": "nope"}, "from_prefix='nope'"),
+        ({"from_type": NodeType.API_ENDPOINT}, "from_type=API_ENDPOINT"),
+        ({"from_type": NodeType.ROUTE_HANDLER, "from_prefix": "app.svc"}, "from_prefix='app.svc'"),
+    ],
+)
+def test_audit_selecting_no_sources_raises_instead_of_an_empty_result(
+    tmp_path: Path, selector: dict[str, object], named: str
+) -> None:
+    """Zero audited sources is not a clean audit — `gaps == []` would pass a CI gate (#467)."""
+    db = _store(tmp_path, *_graph())
+    with SQLiteStore(db) as store, pytest.raises(NoAuditSourcesError) as excinfo:
+        audit_reachability(store, target_fqn="app.verify_owner", **selector)  # type: ignore[arg-type]
+    message = str(excinfo.value)
+    assert "nothing was audited" in message
+    assert named in message
+
+
+def test_audit_no_sources_error_suggests_whole_segment_prefixes(tmp_path: Path) -> None:
+    """A partial last segment names the dot-complete prefixes that would have matched."""
+    db = _store(tmp_path, *_graph())
+    with (
+        SQLiteStore(db) as store,
+        pytest.raises(NoAuditSourcesError, match=r"did you mean: app\.routes\?"),
+    ):
+        audit_reachability(store, target_fqn="app.verify_owner", from_prefix="app.rou")
+
+
+@pytest.mark.parametrize(
+    ("selector", "hint"),
+    [
+        # Whole segment, wrong type: the fix is the type, not the prefix.
+        (
+            {"from_type": NodeType.ROUTE_HANDLER, "from_prefix": "app.svc"},
+            "none of type ROUTE_HANDLER",
+        ),
+        # Whole segment naming the checkpoint: nothing else lives there.
+        ({"from_prefix": "app.verify_owner"}, "Only the checkpoint itself"),
+    ],
+)
+def test_audit_no_sources_error_never_suggests_the_prefix_back(
+    tmp_path: Path, selector: dict[str, object], hint: str
+) -> None:
+    """A suggestion equal to the input is noise; say why the whole segment selected nothing."""
+    db = _store(tmp_path, *_graph())
+    with SQLiteStore(db) as store, pytest.raises(NoAuditSourcesError) as excinfo:
+        audit_reachability(store, target_fqn="app.verify_owner", **selector)  # type: ignore[arg-type]
+    message = str(excinfo.value)
+    assert "did you mean" not in message
+    assert hint in message
+
+
+def test_audit_no_sources_suggestions_respect_type_and_namespace(tmp_path: Path) -> None:
+    """Suggest only prefixes that would select sources: same type, INTERNAL only."""
+    nodes, edges = _graph()
+    nodes.append(
+        Node(
+            id="app.roulette.spin",
+            type=NodeType.ROUTE_HANDLER,
+            name="spin",
+            file_path="<stdlib>",
+            start_line=0,
+            end_line=0,
+            namespace=NodeNamespace.STDLIB,
+        )
+    )
+    nodes.append(_node("app.robots.index", NodeType.FUNCTION, 80))
+    db = _store(tmp_path, nodes, edges)
+    with SQLiteStore(db) as store, pytest.raises(NoAuditSourcesError) as excinfo:
+        audit_reachability(
+            store,
+            target_fqn="app.verify_owner",
+            from_type=NodeType.ROUTE_HANDLER,
+            from_prefix="app.ro",
+        )
+    assert "did you mean: app.routes?" in str(excinfo.value)
+
+
+def test_audit_trailing_dot_suggests_the_prefix_without_it(tmp_path: Path) -> None:
+    """`app.routes.` meant `app.routes`, not a list of its children."""
+    db = _store(tmp_path, *_graph())
+    with SQLiteStore(db) as store, pytest.raises(NoAuditSourcesError) as excinfo:
+        audit_reachability(store, target_fqn="app.verify_owner", from_prefix="app.routes.")
+    assert "did you mean: app.routes?" in str(excinfo.value)
+
+
+def test_audit_selecting_only_the_target_raises(tmp_path: Path) -> None:
+    """The checkpoint is never its own source, so a selection of just it audits nothing."""
+    db = _store(tmp_path, *_graph())
+    with SQLiteStore(db) as store, pytest.raises(NoAuditSourcesError):
+        audit_reachability(store, target_fqn="app.verify_owner", from_prefix="app.verify_owner")
+
+
 def test_audit_empty_prefix_is_treated_as_unset(tmp_path: Path) -> None:
     """A whitespace-only from_prefix is treated as unset — error if it's the only selector."""
     db = _store(tmp_path, *_graph())

{codegraph_brain-0.23.0 → codegraph_brain-0.23.1}/tests/unit/test_cli.py

@@ -1393,6 +1393,19 @@ def test_audit_requires_a_selector(tmp_path: Path) -> None:
     assert "from-type" in result.output
 
 
+@pytest.mark.parametrize("output_format", ["text", "json"])
+def test_audit_selecting_no_sources_fails_the_gate(tmp_path: Path, output_format: str) -> None:
+    """Zero sources exits 2 — before #467 it exited 0, so a typo'd prefix passed CI."""
+    db = _audit_db(tmp_path)
+    result = runner.invoke(
+        app,
+        ["audit", "verify_owner", "--from-prefix", "app.h", "--db", db, "--format", output_format],
+    )
+    assert result.exit_code == 2
+    assert "nothing was audited" in result.stderr
+    assert "nothing was audited" not in result.stdout  # keeps --format json stdout clean
+
+
 # --- suggest-packages command tests ---
 
 

{codegraph_brain-0.23.0 → codegraph_brain-0.23.1}/tests/unit/test_mcp_server.py

@@ -829,6 +829,15 @@ def test_cgis_audit_whitespace_prefix_is_rejected(tmp_path: Path) -> None:
     assert "from_type or from_prefix" in result
 
 
+def test_cgis_audit_selecting_no_sources_is_an_error_not_an_empty_audit(tmp_path: Path) -> None:
+    """A partial prefix must not come back as JSON with empty covered/gaps (#467)."""
+    db = _audit_graph_db(tmp_path)
+    result = cgis_audit_reachability("app.guard", db, from_prefix="ap")
+    assert result.startswith("❌")
+    assert "nothing was audited" in result
+    assert '"gaps"' not in result
+
+
 def test_cgis_audit_none_params_do_not_crash(tmp_path: Path) -> None:
     """JSON null for from_type/from_prefix must not crash on .strip() (#236)."""
     db = _audit_graph_db(tmp_path)

{codegraph_brain-0.23.0 → codegraph_brain-0.23.1}/uv.lock

@@ -261,7 +261,7 @@ wheels = [
 
 [[package]]
 name = "codegraph-brain"
-version = "0.23.0"
+version = "0.23.1"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },

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

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