Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.pyindex 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 annotationsimport re-from collections import defaultdict+from collections import Counter, defaultdictfrom dataclasses import dataclass, field+from typing import Literal, get_argsimport networkx as nximport 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: intcrosses_community: boolcommunities_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 = 0for _, 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 = sbreak@@ -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 traceif 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.pyindex 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 annotationsimport json+from collections import Counterfrom 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 callersfilter the returned trace afterwards, and a positional list would thendescribe 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 = 0best_id: str | None = Nonebest_conf = -1.0@@ -108,11 +136,14 @@ async def bfs_trace(for e in edges:tid = e.target_node_idconf = 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 += 1continueif 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 tracediff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.pyindex 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 alwaysrenders 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 sothe 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.pyindex 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 = filteredcommunities_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.pynew file mode 100644index 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.pyindex 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_fallbadepth=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_evidencedepth=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.pyindex 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",)