Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(graph): say why an execution flow stops instead of just stopping (#1650)

Raghav Chamadiya8362dbefab6a
diff --git a/packages/core/src/repowise/core/analysis/execution_flows.py b/packages/core/src/repowise/core/analysis/execution_flows.py
index 3e8189154..0a68c35a2 100644
--- a/packages/core/src/repowise/core/analysis/execution_flows.py
+++ b/packages/core/src/repowise/core/analysis/execution_flows.py
@@ -8,8 +8,9 @@ intra-community or cross-community based on community assignments.
from __future__ import annotations
import re
-from collections import defaultdict
+from collections import Counter, defaultdict
from dataclasses import dataclass, field
+from typing import Literal, get_args
import networkx as nx
import structlog
@@ -48,6 +49,65 @@ _EXCLUDE_PATH_PATTERNS = re.compile(
)
+# ---------------------------------------------------------------------------
+# Why a trace stopped
+# ---------------------------------------------------------------------------
+
+# A trace that just ends reads as "execution ends here" whether it does or
+# whether the walk ran out of things it could follow. One value per flow, first
+# match wins in the order below. Closed; pinned in both directions by
+# ``tests/unit/analysis/test_flow_termination_vocabulary.py``.
+FlowTermination = Literal[
+ # The hop budget ran out; nothing is known about what lay beyond it.
+ "depth_limit",
+ # The callee rows were cut before the walk saw them, so the three below —
+ # which each claim *every* successor — are not available.
+ "callees_truncated",
+ # Every walkable successor was already on this trace: recursion or a mutual
+ # call, not an end to the execution.
+ "cycle",
+ # Every successor sat below the confidence floor; `termination_detail`
+ # carries which origins were declined.
+ "confidence_filtered",
+ # Every successor was a test/demo/fixture node.
+ "excluded_target",
+ # No outgoing call edges were recorded. Deliberately not called a leaf: a
+ # symbol whose calls we failed to resolve looks exactly like this, and
+ # asserting the code has no callees is the claim we cannot make.
+ "no_callees",
+]
+
+FLOW_TERMINATION_VALUES: frozenset[str] = frozenset(get_args(FlowTermination))
+
+
+def classify_termination(
+ *,
+ hops_taken: int,
+ max_depth: int,
+ revisited: int,
+ low_confidence: int,
+ excluded: int,
+ truncated: bool = False,
+) -> FlowTermination:
+ """Name the one thing that stopped a trace.
+
+ Shared by both walks — the in-process one below and the query-time one in
+ ``mcp_server/_graph_utils`` — so the two cannot describe one stop with
+ different words. Only *truncated* is specific to the query-time walk.
+ """
+ if hops_taken >= max_depth:
+ return "depth_limit"
+ if truncated:
+ return "callees_truncated"
+ if revisited:
+ return "cycle"
+ if low_confidence:
+ return "confidence_filtered"
+ if excluded:
+ return "excluded_target"
+ return "no_callees"
+
+
# ---------------------------------------------------------------------------
# Data models
# ---------------------------------------------------------------------------
@@ -78,6 +138,11 @@ class ExecutionFlow:
depth: int
crosses_community: bool
communities_visited: list[int]
+ # Required, not defaulted: a flow that cannot say why it stopped is the
+ # output this field exists to replace.
+ termination: FlowTermination
+ # For ``confidence_filtered`` only: {resolution_origin: count}.
+ termination_detail: dict[str, int] = field(default_factory=dict)
@dataclass
@@ -202,9 +267,18 @@ def _score_entry_point(
# ---------------------------------------------------------------------------
+@dataclass
+class _Successors:
+ """Walkable call targets, and what was dropped to get there."""
+
+ walkable: list[str]
+ low_confidence: Counter # resolution_origin -> count
+ excluded: int
+
+
def _get_call_successors(
node_id: str, graph: nx.DiGraph, out_deg: dict[str, int],
-) -> list[str]:
+) -> _Successors:
"""Get outgoing call targets, sorted by out-degree descending.
Test/demo/fixture nodes are dropped so traces stay on production code
@@ -212,17 +286,22 @@ def _get_call_successors(
``fetchall`` in a unit test).
"""
successors = []
+ low_confidence: Counter = Counter()
+ excluded = 0
for _, target, d in graph.out_edges(node_id, data=True):
- if (
- d.get("edge_type") == "calls"
- and d.get("confidence", 0) >= 0.5
- and not _is_excluded_node(graph, target)
- ):
- successors.append(target)
+ if d.get("edge_type") != "calls":
+ continue
+ if d.get("confidence", 0) < 0.5:
+ low_confidence[d.get("resolution_origin") or "unlabelled"] += 1
+ continue
+ if _is_excluded_node(graph, target):
+ excluded += 1
+ continue
+ successors.append(target)
# Sort by out-degree descending to follow primary execution path.
successors.sort(key=lambda n: out_deg.get(n, 0), reverse=True)
- return successors
+ return _Successors(successors, low_confidence, excluded)
def _bfs_trace(
@@ -244,11 +323,12 @@ def _bfs_trace(
trace: list[str] = [entry_id]
current = entry_id
+ successors = _Successors([], Counter(), 0)
for _ in range(config.max_depth):
successors = _get_call_successors(current, graph, out_deg)
# Pick the first unvisited successor (highest fan-out)
next_node = None
- for s in successors:
+ for s in successors.walkable:
if s not in visited:
next_node = s
break
@@ -260,6 +340,17 @@ def _bfs_trace(
trace.append(next_node)
current = next_node
+ # `successors` holds the iteration that found nothing, which is what
+ # stopped the walk. When the hop budget ran out instead, that iteration did
+ # find one — `classify_termination` reports the budget before reading it.
+ termination = classify_termination(
+ hops_taken=len(trace) - 1,
+ max_depth=config.max_depth,
+ revisited=len(successors.walkable),
+ low_confidence=sum(successors.low_confidence.values()),
+ excluded=successors.excluded,
+ )
+
# Need at least 2 nodes for a meaningful trace
if len(trace) < 2:
return None
@@ -283,6 +374,12 @@ def _bfs_trace(
depth=len(trace) - 1,
crosses_community=crosses,
communities_visited=communities_seen,
+ termination=termination,
+ termination_detail=(
+ dict(successors.low_confidence)
+ if termination == "confidence_filtered"
+ else {}
+ ),
)
diff --git a/packages/server/src/repowise/server/mcp_server/_graph_utils.py b/packages/server/src/repowise/server/mcp_server/_graph_utils.py
index c68daec7e..34a656738 100644
--- a/packages/server/src/repowise/server/mcp_server/_graph_utils.py
+++ b/packages/server/src/repowise/server/mcp_server/_graph_utils.py
@@ -7,15 +7,23 @@ across `tool_flows.py` and `routers/graph.py`.
from __future__ import annotations
import json
+from collections import Counter
from typing import Any
-from repowise.core.analysis.execution_flows import _EXCLUDE_PATH_PATTERNS
+from repowise.core.analysis.execution_flows import (
+ _EXCLUDE_PATH_PATTERNS,
+ FlowTermination,
+ classify_termination,
+)
from repowise.core.persistence.crud import (
get_graph_edges_for_node,
get_graph_nodes_by_ids,
)
from repowise.core.persistence.models import GraphNode
+# Callee rows per hop; a stop behind this cut is an unknown, not a leaf.
+_CALLEE_FETCH_LIMIT = 20
+
def _node_id_is_excluded(node_id: str) -> bool:
"""True if a ``path::Name`` node id lives in a test/demo/fixture path.
@@ -69,6 +77,7 @@ async def bfs_trace(
max_depth: int,
node_cache: dict[str, GraphNode] | None = None,
hop_origins: dict[tuple[str, str], str] | None = None,
+ termination: dict[str, Any] | None = None,
) -> list[str]:
"""Trace the primary execution path from *entry_id* along ``calls`` edges.
@@ -84,6 +93,8 @@ async def bfs_trace(
for each hop taken. Keyed by pair rather than position because callers
filter the returned trace afterwards, and a positional list would then
describe the wrong hops.
+
+ *termination*, when given, is filled with ``reason`` and ``detail``.
"""
if node_cache is None:
node_cache = {}
@@ -92,15 +103,32 @@ async def bfs_trace(
visited: set[str] = {entry_id}
current = entry_id
+ revisited = 0
+ low_confidence: Counter = Counter()
+ excluded = 0
+ truncated = False
+
for _ in range(max_depth):
- edges = await get_graph_edges_for_node(
+ # One row over the limit, so a node with exactly the limit reads as
+ # uncut rather than as a stop we cannot explain.
+ rows = await get_graph_edges_for_node(
session,
repo_id,
current,
direction="callees",
edge_types=["calls"],
- limit=20,
+ limit=_CALLEE_FETCH_LIMIT + 1,
)
+ edges = rows[:_CALLEE_FETCH_LIMIT]
+ # Rows arrive most-confident first, so a tail below the floor is
+ # provably unwalkable and hides nothing: only a cut whose last kept row
+ # is still walkable leaves a real unknown.
+ truncated = len(rows) > _CALLEE_FETCH_LIMIT and (
+ edges[-1].confidence or 0.0
+ ) >= 0.5
+ revisited = 0
+ low_confidence = Counter()
+ excluded = 0
best_id: str | None = None
best_conf = -1.0
@@ -108,11 +136,14 @@ async def bfs_trace(
for e in edges:
tid = e.target_node_id
conf = e.confidence if e.confidence is not None else 0.0
- if (
- tid in visited
- or conf < 0.5
- or _node_id_is_excluded(tid)
- ):
+ if conf < 0.5:
+ low_confidence[e.resolution_origin or "unlabelled"] += 1
+ continue
+ if _node_id_is_excluded(tid):
+ excluded += 1
+ continue
+ if tid in visited:
+ revisited += 1
continue
if conf > best_conf:
best_conf = conf
@@ -128,6 +159,20 @@ async def bfs_trace(
trace.append(best_id)
current = best_id
+ if termination is not None:
+ reason: FlowTermination = classify_termination(
+ hops_taken=len(trace) - 1,
+ max_depth=max_depth,
+ revisited=revisited,
+ low_confidence=sum(low_confidence.values()),
+ excluded=excluded,
+ truncated=truncated,
+ )
+ termination["reason"] = reason
+ termination["detail"] = (
+ dict(low_confidence) if reason == "confidence_filtered" else {}
+ )
+
return trace
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
index 43e163163..fbd74139f 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
@@ -591,8 +591,7 @@ def build_homonym_union_bodies(
plus ``truncated`` / ``continuation`` when the body was line-capped)
rendered greedily until ``char_budget`` is exhausted. The first def always
renders even if it alone exceeds the budget (a homonym with one huge def
- must still answer), matching the CodeGraph "first match always renders"
- contract.
+ must still answer).
* ``more_definitions``: the defs that did not fit, each ``{file, name,
line, symbol_id, hint}`` with a "call get_symbol, do NOT Read" redirect so
the agent never falls back to Read for the remainder.
diff --git a/packages/server/src/repowise/server/mcp_server/tool_flows.py b/packages/server/src/repowise/server/mcp_server/tool_flows.py
index 6f9869515..137b4f41a 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_flows.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_flows.py
@@ -112,13 +112,28 @@ async def get_execution_flows(
for ep_node, ep_score in entry_nodes:
hop_origins: dict[tuple[str, str], str] = {}
+ termination: dict[str, Any] = {}
trace = await bfs_trace(
- session, repo_id, ep_node.node_id, max_depth, node_cache, hop_origins
+ session,
+ repo_id,
+ ep_node.node_id,
+ max_depth,
+ node_cache,
+ hop_origins,
+ termination,
)
# Drop excluded files reached downstream so they don't leak via the
# trace (entry-point filtering above doesn't cover BFS descendants).
if exclude_spec:
- trace = filter_embedded_path_ids(trace, exclude_spec)
+ filtered = filter_embedded_path_ids(trace, exclude_spec)
+ # The walk classified the node it actually stopped at. When
+ # filtering drops that node, the trace we publish ends earlier
+ # and it ends there because of the exclude spec — reporting the
+ # walk's reason would assert the new last node calls nothing.
+ if filtered and filtered[-1] != trace[-1]:
+ termination["reason"] = "excluded_target"
+ termination["detail"] = {}
+ trace = filtered
communities_visited, crosses = await resolve_trace_communities(
session, repo_id, trace, node_cache
@@ -132,7 +147,10 @@ async def get_execution_flows(
"depth": len(trace) - 1,
"crosses_community": crosses,
"communities_visited": communities_visited,
+ "termination": termination.get("reason"),
}
+ if termination.get("detail"):
+ flow["termination_detail"] = termination["detail"]
# Which strategy produced each hop, aligned to `trace` pairwise.
# Omitted when no hop has one, so an older index shows no field
# rather than a list of nulls.
diff --git a/tests/unit/analysis/test_flow_termination_vocabulary.py b/tests/unit/analysis/test_flow_termination_vocabulary.py
new file mode 100644
index 000000000..a35427592
--- /dev/null
+++ b/tests/unit/analysis/test_flow_termination_vocabulary.py
@@ -0,0 +1,117 @@
+"""The flow-termination vocabulary must stay true in both directions.
+
+Same enforcement shape as the resolution-origin checks in
+``tests/unit/ingestion/test_edge_type_vocabulary.py``: a closed Literal is
+only closed while something checks both ends of it.
+
+* **Nothing returns an undeclared reason** — every string ``classify_termination``
+ can return is a member of the ``FlowTermination`` Literal.
+* **Nothing declares a reason no branch returns** — a word with no producer is
+ a value consumers can filter on and never match, which is indistinguishable
+ from a filter that works.
+
+Ceiling: this is an AST read of the ``return "..."`` literals inside one
+function. A reason assembled at runtime would slip through, so it is not a
+proof that no undeclared reason can be produced — it is a proof that the one
+function allowed to name them stays inside the vocabulary.
+"""
+
+from __future__ import annotations
+
+import ast
+import pathlib
+
+from repowise.core.analysis.execution_flows import (
+ FLOW_TERMINATION_VALUES,
+ classify_termination,
+)
+
+_SOURCE = (
+ pathlib.Path(__file__).resolve().parents[3]
+ / "packages/core/src/repowise/core/analysis/execution_flows.py"
+)
+
+
+def _returned_reasons() -> set[str]:
+ """Every string literal ``classify_termination`` can return."""
+ tree = ast.parse(_SOURCE.read_text(encoding="utf-8"))
+ for node in ast.walk(tree):
+ if isinstance(node, ast.FunctionDef) and node.name == "classify_termination":
+ return {
+ r.value.value
+ for r in ast.walk(node)
+ if isinstance(r, ast.Return)
+ and isinstance(r.value, ast.Constant)
+ and isinstance(r.value.value, str)
+ }
+ raise AssertionError("classify_termination not found — the AST scan has rotted")
+
+
+def test_nothing_returns_an_undeclared_termination() -> None:
+ returned = _returned_reasons()
+ assert returned, "found no literal returns — the AST scan has rotted"
+ assert not (returned - FLOW_TERMINATION_VALUES), (
+ "termination reason(s) returned but not declared: "
+ f"{sorted(returned - FLOW_TERMINATION_VALUES)}\n"
+ "Add them to FlowTermination in repowise.core.analysis.execution_flows."
+ " An undeclared reason reaches consumers as an unrecognised string."
+ )
+
+
+def test_every_declared_termination_has_a_producer() -> None:
+ orphans = FLOW_TERMINATION_VALUES - _returned_reasons()
+ assert not orphans, (
+ f"termination reason(s) declared with no branch returning them: {sorted(orphans)}"
+ )
+
+
+def test_the_hop_budget_outranks_everything_about_the_successors() -> None:
+ """A walk that spent its budget knows nothing about what lay beyond it.
+
+ Pinned because the counts passed alongside describe the *last* iteration,
+ which found a successor — reading them would name a cause that did not
+ stop anything.
+ """
+ assert (
+ classify_termination(
+ hops_taken=8,
+ max_depth=8,
+ revisited=3,
+ low_confidence=2,
+ excluded=1,
+ truncated=True,
+ )
+ == "depth_limit"
+ )
+
+
+def test_a_cut_callee_set_outranks_a_claim_about_all_successors() -> None:
+ """``cycle``/``confidence_filtered``/``excluded_target`` each say *every*
+ successor was one thing, which a cut set cannot support."""
+ assert (
+ classify_termination(
+ hops_taken=1,
+ max_depth=8,
+ revisited=4,
+ low_confidence=0,
+ excluded=0,
+ truncated=True,
+ )
+ == "callees_truncated"
+ )
+
+
+def test_no_successors_at_all_reports_no_callees() -> None:
+ assert (
+ classify_termination(
+ hops_taken=2, max_depth=8, revisited=0, low_confidence=0, excluded=0
+ )
+ == "no_callees"
+ )
+
+
+def test_each_drop_reason_is_reachable_on_its_own() -> None:
+ kw = {"hops_taken": 1, "max_depth": 8, "revisited": 0, "low_confidence": 0, "excluded": 0}
+ assert classify_termination(**{**kw, "revisited": 1}) == "cycle"
+ assert classify_termination(**{**kw, "low_confidence": 1}) == "confidence_filtered"
+ assert classify_termination(**{**kw, "excluded": 1}) == "excluded_target"
diff --git a/tests/unit/generation/test_onboarding.py b/tests/unit/generation/test_onboarding.py
index 69dfb06ea..9121c1cfd 100644
--- a/tests/unit/generation/test_onboarding.py
+++ b/tests/unit/generation/test_onboarding.py
@@ -485,6 +485,7 @@ async def test_how_it_works_without_usable_exact_source_preserves_generic_fallba
depth=2,
crosses_community=False,
communities_visited=[0],
+ termination="no_callees",
)
signals = _signals(files=files, source_map=source_map, flows=(flow,))
config = GenerationConfig(
@@ -566,6 +567,7 @@ async def test_how_it_works_balances_configured_and_distinct_exact_flow_evidence
depth=2,
crosses_community=True,
communities_visited=[0, 1],
+ termination="no_callees",
)
signals = _signals(
files=files,
@@ -671,6 +673,7 @@ async def test_how_it_works_grounds_identifiers_found_only_in_exact_evidence() -
depth=2,
crosses_community=False,
communities_visited=[0],
+ termination="no_callees",
)
signals = _signals(
files=[parsed],
diff --git a/tests/unit/generation/test_overview_execution_flows.py b/tests/unit/generation/test_overview_execution_flows.py
index 7a0e52e10..71d9ca327 100644
--- a/tests/unit/generation/test_overview_execution_flows.py
+++ b/tests/unit/generation/test_overview_execution_flows.py
@@ -52,6 +52,7 @@ def _flow(entry_point_id: str, score: float, trace: list[str]) -> ExecutionFlow:
depth=len(trace) - 1,
crosses_community=False,
communities_visited=[0],
+ termination="no_callees",
)