codegraph-brain 0.23.0__py3-none-any.whl → 0.23.2__py3-none-any.whl

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

cgis/cli.py

@@ -20,6 +20,7 @@ style tags you wrote yourself and pure numbers need no escaping.
 
 import dataclasses
 import json as _json
+from collections.abc import Callable
 from enum import StrEnum
 from pathlib import Path
 
@@ -42,7 +43,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
@@ -318,6 +319,40 @@ def _resolve_cli_fqn(store: SQLiteStore, target: str, kind: str) -> str:
     return resolution.resolved
 
 
+def _tree_neighbours(
+    store: SQLiteStore,
+    edges: list[Edge],
+    neighbour_of: Callable[[Edge], str],
+    *,
+    allowed_edge_types: frozenset[EdgeType] | None,
+    show_external: bool,
+    min_confidence: float | None,
+) -> list[tuple[str, Node | None]]:
+    """The neighbours one tree level shows: filtered, in edge order, each id once.
+
+    One entry per neighbour, not per edge: two call sites are separate edges to the
+    same node, and a tree row shows neither line nor edge type to tell them apart
+    (#463). A neighbour absent from the store (an unresolved target) comes back with
+    ``None``, and is dropped with the non-INTERNAL ones when ``show_external`` is off.
+    """
+    if allowed_edge_types is not None:
+        edges = [e for e in edges if e.type in allowed_edge_types]
+    if min_confidence is not None:
+        edges = [e for e in edges if e.confidence >= min_confidence]
+    ids = list(dict.fromkeys(neighbour_of(e) for e in edges))
+    nodes = {n.id: n for n in store.get_nodes(ids)}
+    return [
+        (node_id, nodes.get(node_id))
+        for node_id in ids
+        if show_external or _is_internal(nodes.get(node_id))
+    ]
+
+
+def _is_internal(node: Node | None) -> bool:
+    """True for a stored node from the ingested repository."""
+    return node is not None and node.namespace == NodeNamespace.INTERNAL
+
+
 def build_trace_tree(
     store: SQLiteStore,
     current_id: str,
@@ -333,21 +368,15 @@ def build_trace_tree(
     if current_depth >= max_depth:
         return
 
-    outgoing = store.get_outgoing_edges(current_id)
-    if allowed_edge_types is not None:
-        outgoing = [e for e in outgoing if e.type in allowed_edge_types]
-    if min_confidence is not None:
-        outgoing = [e for e in outgoing if e.confidence >= min_confidence]
-    nodes_map = {n.id: n for n in store.get_nodes([e.target for e in outgoing])}
-    for edge in outgoing:
-        target_id = edge.target
-        target_node = nodes_map.get(target_id)
-
-        if not show_external and (
-            target_node is None or target_node.namespace != NodeNamespace.INTERNAL
-        ):
-            continue
-
+    callees = _tree_neighbours(
+        store,
+        store.get_outgoing_edges(current_id),
+        lambda edge: edge.target,
+        allowed_edge_types=allowed_edge_types,
+        show_external=show_external,
+        min_confidence=min_confidence,
+    )
+    for target_id, target_node in callees:
         if target_node:
             label = (
                 f"[bold green]{target_node.type.value}[/bold green] "
@@ -470,21 +499,15 @@ def build_impact_tree(
     if current_depth >= max_depth:
         return
 
-    incoming = store.get_incoming_edges(current_id)
-    if allowed_edge_types is not None:
-        incoming = [e for e in incoming if e.type in allowed_edge_types]
-    if min_confidence is not None:
-        incoming = [e for e in incoming if e.confidence >= min_confidence]
-    nodes_map = {n.id: n for n in store.get_nodes([e.source for e in incoming])}
-    for edge in incoming:
-        source_id = edge.source
-        source_node = nodes_map.get(source_id)
-
-        if not show_external and (
-            source_node is None or source_node.namespace != NodeNamespace.INTERNAL
-        ):
-            continue
-
+    callers = _tree_neighbours(
+        store,
+        store.get_incoming_edges(current_id),
+        lambda edge: edge.source,
+        allowed_edge_types=allowed_edge_types,
+        show_external=show_external,
+        min_confidence=min_confidence,
+    )
+    for source_id, source_node in callers:
         if source_node:
             label = (
                 f"[bold magenta]{source_node.type.value}[/bold magenta] "
@@ -1445,7 +1468,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 +1510,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))

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)

cgis/query/render/graph_json.py

@@ -28,6 +28,10 @@ def graph_to_json(
     ``coverage`` is the traversal's local resolution coverage (#201). A
     structure query follows no calls and passes none, so the key is omitted
     rather than reported as a zero it did not measure.
+
+    Edges are one per distinct ``(src, type, dst)``, as in the Mermaid view: two
+    call sites to the same function are separate graph edges, but without a line
+    number the payload would state the same fact twice (#463).
     """
     payload: dict[str, Any] = {
         "root": root,
@@ -40,16 +44,26 @@ def graph_to_json(
             }
             for node in nodes
         ],
-        "edges": [
-            {
+        "edges": _distinct_edges(edges),
+    }
+    if coverage is not None:
+        payload["coverage"] = coverage.model_dump()
+    return payload
+
+
+def _distinct_edges(edges: list[Edge]) -> list[dict[str, Any]]:
+    """Collapse edges sharing ``(src, type, dst)``, first-seen order, highest confidence kept."""
+    distinct: dict[tuple[str, str, str], dict[str, Any]] = {}
+    for edge in edges:
+        key = (edge.source, edge.type.value, edge.target)
+        seen = distinct.get(key)
+        if seen is None:
+            distinct[key] = {
                 "src": edge.source,
                 "dst": edge.target,
                 "type": edge.type.value,
                 "confidence": edge.confidence,
             }
-            for edge in edges
-        ],
-    }
-    if coverage is not None:
-        payload["coverage"] = coverage.model_dump()
-    return payload
+        elif edge.confidence > seen["confidence"]:
+            seen["confidence"] = edge.confidence
+    return list(distinct.values())

{codegraph_brain-0.23.0.dist-info → codegraph_brain-0.23.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.23.0
+Version: 0.23.2
 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.dist-info → codegraph_brain-0.23.2.dist-info}/RECORD

@@ -1,11 +1,11 @@
 cgis/__init__.py,sha256=3QdRGRHRQHrjQYXrPCo1uCZKcx5C-f098rpT21gq3RU,271
 cgis/__main__.py,sha256=w9qXbHyKaCVxkdm7i_NDSc-Mz07ivIoaAAVFGvs3Plo,326
-cgis/cli.py,sha256=cMEDjjpuaDdnvBGLmmG93olTGlQWfgdIALfyDyvZLDY,69945
+cgis/cli.py,sha256=tLUfKUyEFG0LtU3xRrsBvyGOw0i08MKb7q1tJaCq1Ws,71133
 cgis/pipeline.py,sha256=c-z6MJb9H06hWZQfvVwGQL2PUN3k0-Am-PCAHfMK0nQ,17048
 cgis/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cgis/api/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cgis/api/__init__.py,sha256=wvFZK6oZspFGmonBz2rDg1aXxK7DHuE87or_w_cwY28,91
-cgis/api/mcp_server.py,sha256=7p82YJK4orChNdJN3YOkWmLNB0T_01HzPcSkAt_F3fk,44422
+cgis/api/mcp_server.py,sha256=M2lq_Eo8UO0H47yTrbyBvSPzsp8sKH01jQ4B2HWH1dg,44602
 cgis/core/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cgis/core/coverage.py,sha256=AmeZ_mij5Q382MAqtUmDRmJ_lHLPsV73k0_zksaWc6c,2469
 cgis/core/freshness.py,sha256=s1ahMqizX5jRo5Sj6T-2YfNq1d-jsRqisfne5m4yagw,1395
@@ -60,7 +60,7 @@ cgis/query/analysis/cohesion.py,sha256=o_xXGbFqD0RgRSHxbsIBD-B3Spmtxv-RCy1MbB_IG
 cgis/query/analysis/health.py,sha256=3eZokxeH_be7l7MNuLoLpRIZZ5B3N0DoA1TKMDAkjBs,4989
 cgis/query/analysis/suggest_service.py,sha256=K_eJsfP54QGRSI3rBFB1Y94G-asP30EBZoVUlr1wkm8,10059
 cgis/query/context/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cgis/query/context/audit.py,sha256=yKFc0EgzH4OFm_ZUZ1yeMAB93jCcGZmqfXrCuGup6ec,6157
+cgis/query/context/audit.py,sha256=U8ZPvFxTFwsXKTbZzXaE9GKEZ6RSD_xCGFciF1sMqHk,9566
 cgis/query/context/context_service.py,sha256=V0YtJaImgs7cwihejaBzKaOWa8Iax1T2OGrC-W6HbWs,5849
 cgis/query/context/orphans.py,sha256=-28Jc7CqXXQIlH81LGlQihLtlIQLO0UK20DuEn3ZAuI,8064
 cgis/query/context/prompt.py,sha256=H38K0MN_PBaBdK-1nmN1873rOwADVvVYmcxKECLQkLU,8222
@@ -75,7 +75,7 @@ cgis/query/drift/ontology_init.py,sha256=cWcr_UjUJRV9w8MGZITt4m6kvQ3asbKLZaN402E
 cgis/query/drift/quotient.py,sha256=4tV29yk07VYfbrAo7PIrWQ4BagZ0T6nItWP_8Macx_4,2711
 cgis/query/drift/triads.py,sha256=OoGxSAsU9QzHP2MboYkXJ3Jg7PyoE9tO6BfX65fwyYQ,6150
 cgis/query/render/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cgis/query/render/graph_json.py,sha256=wJ-bXxEC9S9fCWFRkRM4QOwEJ3OUTHYFNJ-OX2uxdU4,1899
+cgis/query/render/graph_json.py,sha256=Wxu0_4oxa7o6IKvjTnJbPgV-Hlcl211DDi_UwFjABH0,2622
 cgis/query/render/mermaid.py,sha256=OfvAIdqcqfCS8vvDdWTovGe9dYbLu_DEhRmjmDv8bEc,10749
 cgis/query/render/metrics.py,sha256=23iEdj29_Cry5VlLvDHgLM8f3_CewARgxllkPgEg3nI,18179
 cgis/resolver/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -87,8 +87,8 @@ cgis/resolver/symbols.py,sha256=A88dOb7ciEfWaS4KCK0Ho4cBC2IZisNrBfYp-f1LFYs,1254
 cgis/resolver/uplift.py,sha256=Hkye1q-kI-gKO6GIBYv3gUZj1AC0-_mkpoIpmwVsG4g,9591
 cgis/storage/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cgis/storage/sqlite_store.py,sha256=tlkg9kbiAFm0rth7ndsRPyv3cjDCj3dpvs7Pp_FTBno,45671
-codegraph_brain-0.23.0.dist-info/METADATA,sha256=eSkggudqSecXPbucmWHFtUwQrXvawtLanC9aBW2BQC0,11771
-codegraph_brain-0.23.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-codegraph_brain-0.23.0.dist-info/entry_points.txt,sha256=mWajEQlAoWuiLyCQdD1TvvguloKQFmzKb52-g9PB_R4,123
-codegraph_brain-0.23.0.dist-info/licenses/LICENSE,sha256=1X36nOG5VocDaEGzAZqIv7uawy_7sWlFoiwECwx5aBI,1065
-codegraph_brain-0.23.0.dist-info/RECORD,,
+codegraph_brain-0.23.2.dist-info/METADATA,sha256=Ul_KuCONXckwgxLZ6rE6LxtefLk-IQVyDmsJVKGhw9E,11771
+codegraph_brain-0.23.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+codegraph_brain-0.23.2.dist-info/entry_points.txt,sha256=mWajEQlAoWuiLyCQdD1TvvguloKQFmzKb52-g9PB_R4,123
+codegraph_brain-0.23.2.dist-info/licenses/LICENSE,sha256=1X36nOG5VocDaEGzAZqIv7uawy_7sWlFoiwECwx5aBI,1065
+codegraph_brain-0.23.2.dist-info/RECORD,,