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.

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.py
index 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 annotations
import re
-from collections import deque
+from collections import defaultdict
from dataclasses import dataclass, field
import networkx as nx
@@ -59,6 +59,10 @@ class FlowConfig:
max_flows: int = 50
min_fan_out: int = 2
deduplicate: 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: int
total_flows: int
flows: 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 + 1
fan_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 build
the primary execution path.
@@ -212,7 +237,7 @@ def _bfs_trace(
current = entry_id
for _ 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 = None
for 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/methods
candidates: 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 candidate
flows: 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 = score
flows.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.py
index 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.flows
if hasattr(f, "entry_point_id") and hasattr(f, "entry_point_score")
}
+ else:
+ ep_scores = None
await 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.py
index 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 annotations
import json
-from collections import deque
from typing import Any
+from repowise.core.analysis.execution_flows import _EXCLUDE_PATH_PATTERNS
from 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 0
count_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.0
for 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_id
return trace
diff --git a/tests/unit/analysis/test_execution_flows.py b/tests/unit/analysis/test_execution_flows.py
new file mode 100644
index 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.py
new file mode 100644
index 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)) == {}