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
fix(graph): keep execution-flow entry-point scores from being wiped on update (#585)
Raghav Chamadiya9e6da4bffba9
diff --git a/packages/core/src/repowise/core/analysis/execution_flows.py b/packages/core/src/repowise/core/analysis/execution_flows.pyindex 87efe5a83..4ff1fffac 100644--- a/packages/core/src/repowise/core/analysis/execution_flows.py+++ b/packages/core/src/repowise/core/analysis/execution_flows.py@@ -8,7 +8,7 @@ intra-community or cross-community based on community assignments.from __future__ import annotationsimport re-from collections import deque+from collections import defaultdictfrom dataclasses import dataclass, fieldimport networkx as nx@@ -59,6 +59,10 @@ class FlowConfig:max_flows: int = 50min_fan_out: int = 2deduplicate: bool = True+ # Minimum number of call hops (trace nodes - 1) for a flow to be reported.+ # A single call (depth 1) is not a meaningful "flow"; the onboarding+ # "How It Works" page already gates at >= 3 trace nodes.+ min_flow_depth: int = 2@dataclass@@ -81,6 +85,10 @@ class ExecutionFlowReport:total_entry_points_scored: inttotal_flows: intflows: list[ExecutionFlow]+ # {node_id: score} for *every* candidate scoring >= the entry-point+ # threshold, not just the ones that produced a traced flow. Persisted so+ # the symbol-level "entry point" indicator works for all entry points.+ entry_point_scores: dict[str, float] = field(default_factory=dict)# ---------------------------------------------------------------------------@@ -88,25 +96,38 @@ class ExecutionFlowReport:# ----------------------------------------------------------------------------def _count_edges_by_type(- node_id: str, graph: nx.DiGraph, edge_type: str, direction: str,-) -> int:- """Count edges of a specific type in a given direction."""- if direction == "out":- return sum(- 1 for _, _, d in graph.out_edges(node_id, data=True)- if d.get("edge_type") == edge_type- )- return sum(- 1 for _, _, d in graph.in_edges(node_id, data=True)- if d.get("edge_type") == edge_type+def _build_call_degree_maps(+ graph: nx.DiGraph,+) -> tuple[dict[str, int], dict[str, int]]:+ """Precompute call-edge in/out degree per node in a single edge pass.++ Replaces repeated per-node ``out_edges``/``in_edges`` rescans (which made+ scoring and successor ordering O(nodes x degree)) with O(1) lookups.+ """+ out_deg: dict[str, int] = defaultdict(int)+ in_deg: dict[str, int] = defaultdict(int)+ for u, v, d in graph.edges(data=True):+ if d.get("edge_type") == "calls":+ out_deg[u] += 1+ in_deg[v] += 1+ return out_deg, in_deg+++def _is_excluded_node(graph: nx.DiGraph, node_id: str) -> bool:+ """True if the node lives in a test/demo/fixture/script path."""+ data = graph.nodes.get(node_id, {})+ file_path = data.get("file_path") or (+ node_id.split("::", 1)[0] if "::" in node_id else "")+ return bool(_EXCLUDE_PATH_PATTERNS.search(file_path))def _score_entry_point(node_id: str,graph: nx.DiGraph,community_map: dict[str, int],+ out_deg: dict[str, int],+ in_deg: dict[str, int],) -> float:"""Score a symbol as a potential entry point. Returns 0.0-1.0."""data = graph.nodes.get(node_id, {})@@ -119,8 +140,8 @@ def _score_entry_point(return 0.0# Signal 1: Fan-out ratio (weight 0.35)- out_calls = _count_edges_by_type(node_id, graph, "calls", "out")- in_calls = _count_edges_by_type(node_id, graph, "calls", "in")+ out_calls = out_deg.get(node_id, 0)+ in_calls = in_deg.get(node_id, 0)total = in_calls + out_calls + 1fan_out_signal = out_calls / total@@ -174,22 +195,25 @@ def _score_entry_point(def _get_call_successors(- node_id: str, graph: nx.DiGraph,+ node_id: str, graph: nx.DiGraph, out_deg: dict[str, int],) -> list[str]:- """Get outgoing call targets, sorted by out-degree descending."""+ """Get outgoing call targets, sorted by out-degree descending.++ Test/demo/fixture nodes are dropped so traces stay on production code+ even when a call edge mis-resolves to a test fake (e.g. a fake+ ``fetchall`` in a unit test).+ """successors = []for _, target, d in graph.out_edges(node_id, data=True):- if d.get("edge_type") == "calls" and d.get("confidence", 0) >= 0.5:+ if (+ d.get("edge_type") == "calls"+ and d.get("confidence", 0) >= 0.5+ and not _is_excluded_node(graph, target)+ ):successors.append(target)- # Sort by out-degree descending to follow primary execution path- successors.sort(- key=lambda n: sum(- 1 for _, _, d in graph.out_edges(n, data=True)- if d.get("edge_type") == "calls"- ),- reverse=True,- )+ # Sort by out-degree descending to follow primary execution path.+ successors.sort(key=lambda n: out_deg.get(n, 0), reverse=True)return successors@@ -198,8 +222,9 @@ def _bfs_trace(graph: nx.DiGraph,community_map: dict[str, int],config: FlowConfig,+ out_deg: dict[str, int],) -> ExecutionFlow | None:- """BFS trace from an entry point following call edges.+ """Trace from an entry point following call edges.Follows the highest-fan-out successor at each step to buildthe primary execution path.@@ -212,7 +237,7 @@ def _bfs_trace(current = entry_idfor _ in range(config.max_depth):- successors = _get_call_successors(current, graph)+ successors = _get_call_successors(current, graph, out_deg)# Pick the first unvisited successor (highest fan-out)next_node = Nonefor s in successors:@@ -302,6 +327,8 @@ def trace_execution_flows(total_entry_points_scored=0, total_flows=0, flows=[],)+ out_deg, in_deg = _build_call_degree_maps(graph)+# Score all symbol nodes that are functions/methodscandidates: list[tuple[str, float]] = []for node_id, data in graph.nodes(data=True):@@ -312,25 +339,26 @@ def trace_execution_flows(continue# Must have minimum fan-out to be interesting- out_calls = sum(- 1 for _, _, d in graph.out_edges(node_id, data=True)- if d.get("edge_type") == "calls"- )- if out_calls < config.min_fan_out:+ if out_deg.get(node_id, 0) < config.min_fan_out:continue- score = _score_entry_point(node_id, graph, community_map)+ score = _score_entry_point(node_id, graph, community_map, out_deg, in_deg)if score >= _MIN_ENTRY_POINT_SCORE:candidates.append((node_id, score))candidates.sort(key=lambda x: -x[1])++ # Every scored candidate is a persistable entry point, independent of+ # whether it produced a long enough trace below.+ entry_point_scores = {node_id: score for node_id, score in candidates}+top_candidates = candidates[:config.max_flows]# Trace from each candidateflows: list[ExecutionFlow] = []for node_id, score in top_candidates:- flow = _bfs_trace(node_id, graph, community_map, config)- if flow is not None:+ flow = _bfs_trace(node_id, graph, community_map, config, out_deg)+ if flow is not None and flow.depth >= config.min_flow_depth:flow.entry_point_score = scoreflows.append(flow)@@ -356,4 +384,5 @@ def trace_execution_flows(total_entry_points_scored=len(candidates),total_flows=len(flows),flows=flows,+ entry_point_scores=entry_point_scores,)diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.pyindex 699c30160..3c4b97856 100644--- a/packages/core/src/repowise/core/pipeline/persist.py+++ b/packages/core/src/repowise/core/pipeline/persist.py@@ -80,6 +80,31 @@ async def mark_tombstone_pages(return marked+def _derive_entry_point_scores(graph_builder: Any) -> dict[str, float]:+ """Best-effort entry-point scores from the builder's execution-flow report.++ Returns ``{node_id: score}`` for every scored entry-point candidate (not+ just the ones that produced a traced flow). The call is cached on the+ builder, so this is cheap when flows were already computed.+ """+ try:+ report = graph_builder.execution_flows()+ except Exception as exc: # analysis is non-load-bearing for persistence+ logger.warning("entry_point_scores_derive_failed", error=str(exc))+ return {}+ if report is None:+ return {}+ scores = getattr(report, "entry_point_scores", None)+ if scores:+ return dict(scores)+ # Back-compat: older reports only expose per-flow scores.+ return {+ f.entry_point_id: f.entry_point_score+ for f in getattr(report, "flows", []) or []+ if hasattr(f, "entry_point_id") and hasattr(f, "entry_point_score")+ }++async def persist_graph_nodes(session: Any,repo_id: str,@@ -105,7 +130,13 @@ async def persist_graph_nodes(cd = graph_builder.community_detection()sc = graph_builder.symbol_communities()ci = graph_builder.community_info()- ep_scores = ep_scores or {}+ # ``None`` means "derive scores from the graph" (the incremental update+ # path passes nothing). An explicit ``{}`` means "no scores" and is left+ # untouched. Without this, every ``update`` re-upserted symbol nodes with+ # empty community_meta and wiped the entry_point_scores written at init,+ # leaving get_execution_flows / the dashboard panel permanently empty.+ if ep_scores is None:+ ep_scores = _derive_entry_point_scores(graph_builder)nodes = []for node_id in graph.nodes:@@ -368,13 +399,21 @@ async def persist_ingestion(result: Any, session: Any, repo_id: str) -> int:)# ---- Graph nodes ---------------------------------------------------------- ep_scores: dict[str, float] = {}- if result.execution_flow_report and getattr(result.execution_flow_report, "flows", None):+ # Prefer the full candidate-score map (all scored entry points), falling+ # back to deriving from the builder when no report rode along on the+ # result. Passing ``None`` lets persist_graph_nodes derive them itself.+ report = result.execution_flow_report+ ep_scores: dict[str, float] | None+ if report is not None and getattr(report, "entry_point_scores", None):+ ep_scores = dict(report.entry_point_scores)+ elif report is not None and getattr(report, "flows", None):ep_scores = {f.entry_point_id: f.entry_point_score- for f in result.execution_flow_report.flows+ for f in report.flowsif hasattr(f, "entry_point_id") and hasattr(f, "entry_point_score")}+ else:+ ep_scores = Noneawait persist_graph_nodes(session, repo_id, result.graph_builder, ep_scores)# ---- Graph edges ---------------------------------------------------------diff --git a/packages/server/src/repowise/server/mcp_server/_graph_utils.py b/packages/server/src/repowise/server/mcp_server/_graph_utils.pyindex b82e38a6b..f067d68a5 100644--- a/packages/server/src/repowise/server/mcp_server/_graph_utils.py+++ b/packages/server/src/repowise/server/mcp_server/_graph_utils.py@@ -7,9 +7,9 @@ across `tool_flows.py` and `routers/graph.py`.from __future__ import annotationsimport json-from collections import dequefrom typing import Any+from repowise.core.analysis.execution_flows import _EXCLUDE_PATH_PATTERNSfrom repowise.core.persistence.crud import (get_graph_edges_for_node,get_graph_nodes_by_ids,@@ -17,6 +17,17 @@ from repowise.core.persistence.crud import (from repowise.core.persistence.models import GraphNode+def _node_id_is_excluded(node_id: str) -> bool:+ """True if a ``path::Name`` node id lives in a test/demo/fixture path.++ Uses the same pattern as the core entry-point scorer so server-side+ traces never wander into test fakes that a mis-resolved call edge points+ at (e.g. a fake ``fetchall``).+ """+ path = node_id.split("::", 1)[0] if "::" in node_id else node_id+ return bool(_EXCLUDE_PATH_PATTERNS.search(path))++def parse_community_meta(node: GraphNode) -> dict[str, Any]:"""Safely parse ``community_meta_json`` from a GraphNode."""try:@@ -44,7 +55,7 @@ def entry_point_score(node: GraphNode) -> float:def percentile_rank(value: float, all_values: list[float]) -> int:- """Compute the percentile rank (0–100) of *value* within *all_values*."""+ """Compute the percentile rank (0-100) of *value* within *all_values*."""if not all_values:return 0count_below = sum(1 for v in all_values if v < value)@@ -58,24 +69,24 @@ async def bfs_trace(max_depth: int,node_cache: dict[str, GraphNode] | None = None,) -> list[str]:- """BFS trace from *entry_id* following ``calls`` edges.-- Returns an ordered list of symbol IDs in the trace. Uses greedy- successor ordering (highest confidence first for the primary path)- and a visited set for cycle safety.+ """Trace the primary execution path from *entry_id* along ``calls`` edges.++ Returns an ordered list of symbol IDs forming a single linear chain — the+ same shape the core analysis (``analysis/execution_flows``) produces for+ docs, so the MCP/REST/dashboard traces match the wiki. At each hop it+ follows the highest-confidence unvisited successor (confidence is the+ DB-cheap proxy for the core scorer's fan-out ordering). Test/demo/fixture+ nodes and low-confidence (< 0.5) edges are skipped; a visited set keeps it+ cycle-safe."""if node_cache is None:node_cache = {}trace: list[str] = [entry_id]visited: set[str] = {entry_id}- queue: deque[tuple[str, int]] = deque([(entry_id, 0)])-- while queue:- current, depth = queue.popleft()- if depth >= max_depth:- continue+ current = entry_id+ for _ in range(max_depth):edges = await get_graph_edges_for_node(session,repo_id,@@ -85,19 +96,27 @@ async def bfs_trace(limit=20,)- successors: list[tuple[str, float]] = []+ best_id: str | None = None+ best_conf = -1.0for e in edges:- if e.target_node_id not in visited:- successors.append((e.target_node_id, e.confidence or 0.0))+ 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)+ ):+ continue+ if conf > best_conf:+ best_conf = conf+ best_id = tid- successors.sort(key=lambda x: -x[1])+ if best_id is None:+ break- for target_id, _ in successors:- if target_id in visited:- continue- visited.add(target_id)- trace.append(target_id)- queue.append((target_id, depth + 1))+ visited.add(best_id)+ trace.append(best_id)+ current = best_idreturn tracediff --git a/tests/unit/analysis/test_execution_flows.py b/tests/unit/analysis/test_execution_flows.pynew file mode 100644index 000000000..ef5ac885e--- /dev/null+++ b/tests/unit/analysis/test_execution_flows.py@@ -0,0 +1,111 @@+"""Tests for execution-flow tracing (analysis/execution_flows)."""++from __future__ import annotations++import networkx as nx++from repowise.core.analysis.execution_flows import (+ FlowConfig,+ trace_execution_flows,+)+++def _sym(g: nx.DiGraph, node_id: str, name: str, **kw) -> None:+ g.add_node(+ node_id,+ node_type="symbol",+ kind="function",+ name=name,+ file_path=node_id.split("::", 1)[0],+ visibility="public",+ **kw,+ )+++def _call(g: nx.DiGraph, src: str, dst: str, confidence: float = 1.0) -> None:+ g.add_edge(src, dst, edge_type="calls", confidence=confidence)+++def _chain_graph() -> nx.DiGraph:+ """main -> a -> b -> c, with a couple of leaf calls to give fan-out."""+ g = nx.DiGraph()+ for nid, nm in [+ ("src/app.py::main", "main"),+ ("src/app.py::a", "a"),+ ("src/app.py::b", "b"),+ ("src/app.py::c", "c"),+ ("src/util.py::leaf1", "leaf1"),+ ("src/util.py::leaf2", "leaf2"),+ ]:+ _sym(g, nid, nm)+ _call(g, "src/app.py::main", "src/app.py::a")+ _call(g, "src/app.py::main", "src/util.py::leaf1")+ _call(g, "src/app.py::a", "src/app.py::b")+ _call(g, "src/app.py::a", "src/util.py::leaf2")+ _call(g, "src/app.py::b", "src/app.py::c")+ return g+++def test_all_candidates_scored_are_exposed():+ g = _chain_graph()+ report = trace_execution_flows(g, {}, FlowConfig())+ # main, a, b all have fan-out >= 2 / >= 1 and score above threshold.+ assert report.entry_point_scores # populated for persistence+ assert "src/app.py::main" in report.entry_point_scores+ # Every scored candidate is represented, not just the traced flows.+ assert len(report.entry_point_scores) >= report.total_flows+++def test_trace_follows_primary_chain():+ g = _chain_graph()+ report = trace_execution_flows(g, {}, FlowConfig(min_flow_depth=1))+ main_flow = next(+ f for f in report.flows if f.entry_point_id == "src/app.py::main"+ )+ # Primary path follows the highest-fan-out successor at each hop.+ assert main_flow.trace[:4] == [+ "src/app.py::main",+ "src/app.py::a",+ "src/app.py::b",+ "src/app.py::c",+ ]+++def test_trace_skips_test_nodes():+ """A call edge into a test fake must not leak into the trace."""+ g = _chain_graph()+ _sym(g, "tests/unit/test_app.py::_FakeResult", "_FakeResult")+ # b "calls" a test fake (mis-resolved edge); it must be skipped.+ _call(g, "src/app.py::b", "tests/unit/test_app.py::_FakeResult")+ report = trace_execution_flows(g, {}, FlowConfig(min_flow_depth=1))+ for flow in report.flows:+ assert not any("tests/" in node for node in flow.trace)+++def test_min_flow_depth_filters_trivial_flows():+ """A lone single-call entry point is not reported as a flow by default."""+ g = nx.DiGraph()+ _sym(g, "src/x.py::solo", "solo")+ _sym(g, "src/x.py::one", "one")+ _sym(g, "src/x.py::two", "two")+ # solo has fan-out 2 (qualifies as a candidate) but no deeper chain.+ _call(g, "src/x.py::solo", "src/x.py::one")+ _call(g, "src/x.py::solo", "src/x.py::two")+ default = trace_execution_flows(g, {}, FlowConfig())+ assert default.total_flows == 0 # depth-1 flow dropped+ # ...but the candidate is still scored and persistable.+ assert "src/x.py::solo" in default.entry_point_scores+ permissive = trace_execution_flows(g, {}, FlowConfig(min_flow_depth=1))+ assert permissive.total_flows == 1+++def test_test_files_never_score_as_entry_points():+ g = nx.DiGraph()+ _sym(g, "tests/unit/test_app.py::helper", "helper")+ _sym(g, "tests/unit/test_app.py::a", "a")+ _sym(g, "tests/unit/test_app.py::b", "b")+ _call(g, "tests/unit/test_app.py::helper", "tests/unit/test_app.py::a")+ _call(g, "tests/unit/test_app.py::helper", "tests/unit/test_app.py::b")+ report = trace_execution_flows(g, {}, FlowConfig(min_flow_depth=1))+ assert report.total_entry_points_scored == 0+ assert report.entry_point_scores == {}diff --git a/tests/unit/pipeline/test_entry_point_score_persistence.py b/tests/unit/pipeline/test_entry_point_score_persistence.pynew file mode 100644index 000000000..2e667c23f--- /dev/null+++ b/tests/unit/pipeline/test_entry_point_score_persistence.py@@ -0,0 +1,45 @@+"""The incremental update path must not wipe persisted entry-point scores.++``persist_graph_nodes(..., ep_scores=None)`` (how the update path calls it)+should *derive* scores from the graph builder rather than writing empty+community-meta, which previously left get_execution_flows / the dashboard+panel permanently empty after the first ``update``.+"""++from __future__ import annotations++from types import SimpleNamespace++from repowise.core.analysis.execution_flows import ExecutionFlowReport+from repowise.core.pipeline.persist import _derive_entry_point_scores+++def _builder_with_report(report) -> SimpleNamespace:+ return SimpleNamespace(execution_flows=lambda: report)+++def test_derive_uses_all_candidate_scores():+ report = ExecutionFlowReport(+ total_entry_points_scored=2,+ total_flows=1,+ flows=[],+ entry_point_scores={"a.py::main": 0.9, "a.py::handle": 0.5},+ )+ scores = _derive_entry_point_scores(_builder_with_report(report))+ assert scores == {"a.py::main": 0.9, "a.py::handle": 0.5}+++def test_derive_falls_back_to_flow_scores_for_legacy_reports():+ flow = SimpleNamespace(entry_point_id="a.py::main", entry_point_score=0.8)+ report = SimpleNamespace(flows=[flow], entry_point_scores={})+ scores = _derive_entry_point_scores(_builder_with_report(report))+ assert scores == {"a.py::main": 0.8}+++def test_derive_is_safe_when_report_missing_or_raises():+ assert _derive_entry_point_scores(_builder_with_report(None)) == {}++ def _boom():+ raise RuntimeError("flow tracing failed")++ assert _derive_entry_point_scores(SimpleNamespace(execution_flows=_boom)) == {}