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(generation): read execution flows by the field names they have (#1245)

Raghav Chamadiya617faad2d0e5
diff --git a/packages/core/src/repowise/core/generation/context/assembler.py b/packages/core/src/repowise/core/generation/context/assembler.py
index dffb5c465..a5ae20e83 100644
--- a/packages/core/src/repowise/core/generation/context/assembler.py
+++ b/packages/core/src/repowise/core/generation/context/assembler.py
@@ -679,22 +679,46 @@ class ContextAssembler:
# label, so the label is not a total order.
communities_list.sort(key=lambda c: (-c["size"], c["id"]))
communities_list = communities_list[:10]
- except Exception:
- pass
+ except Exception as exc:
+ # Same silent shape as the flow block below, which is how that
+ # one went a year unnoticed. Say something.
+ log.warning(
+ "overview_communities_unavailable",
+ error=str(exc),
+ error_type=type(exc).__name__,
+ )
try:
flow_report = graph_builder.execution_flows()
if flow_report and hasattr(flow_report, "flows"):
- for flow in flow_report.flows[:5]:
+ # Highest-scoring first: the templates render the first
+ # five, so the order here is the selection.
+ ranked = sorted(
+ flow_report.flows,
+ key=lambda f: (-f.entry_point_score, f.entry_point_id),
+ )
+ for flow in ranked[:5]:
execution_flows_list.append(
{
- "entry_point": flow.entry_point,
- "score": round(flow.score, 3),
+ "entry_point": flow.entry_point_id,
+ "entry_point_name": flow.entry_point_name,
+ "score": round(flow.entry_point_score, 3),
"trace_length": len(flow.trace) if hasattr(flow, "trace") else 0,
}
)
- except Exception:
- pass
+ except Exception as exc:
+ # This was a bare ``except: pass`` reading ``flow.entry_point``
+ # and ``flow.score`` off a dataclass whose fields are
+ # ``entry_point_id`` and ``entry_point_score``. The
+ # AttributeError was swallowed, the list stayed empty, and the
+ # template's ``{% if %}`` guard dropped the section — so no
+ # overview has ever carried an execution flow. An empty
+ # section is a fine outcome; a silent one is not.
+ log.warning(
+ "overview_execution_flows_unavailable",
+ error=str(exc),
+ error_type=type(exc).__name__,
+ )
return RepoOverviewContext(
# RepoStructure carries no name, so the old getattr fallback made
diff --git a/packages/core/src/repowise/core/generation/onboarding/subkinds/how_it_works.py b/packages/core/src/repowise/core/generation/onboarding/subkinds/how_it_works.py
index f50c69d24..cb7d06cec 100644
--- a/packages/core/src/repowise/core/generation/onboarding/subkinds/how_it_works.py
+++ b/packages/core/src/repowise/core/generation/onboarding/subkinds/how_it_works.py
@@ -19,10 +19,14 @@ from __future__ import annotations
from dataclasses import dataclass, field
from typing import Literal
+import structlog
+
from ..registry import SubkindSpec, register
from ..signals import OnboardingSignals
from ..slots import SLOT_HOW_IT_WORKS, SLOT_TITLES
+log = structlog.get_logger(__name__)
+
Archetype = Literal["service", "cli", "library", "pipeline", "module"]
_MIN_TRACE_HOPS = 3
@@ -119,21 +123,30 @@ def _collect_flows(signals: OnboardingSignals) -> list[FlowTrace]:
"""Pull execution flows from the graph builder (best-effort)."""
try:
report = signals.graph_builder.execution_flows()
- except Exception:
+ except Exception as exc:
+ log.warning(
+ "how_it_works_execution_flows_unavailable",
+ error=str(exc),
+ error_type=type(exc).__name__,
+ )
return []
if not report or not hasattr(report, "flows"):
return []
flows: list[FlowTrace] = []
+ # ``ExecutionFlow`` names these ``entry_point_id`` and
+ # ``entry_point_score``. Read as ``entry_point`` / ``score`` the getattr
+ # defaults applied instead of raising, so every page ever generated
+ # carried an empty entry point and a zero score on every flow.
for flow in getattr(report, "flows", [])[:_TOP_FLOWS]:
trace = list(getattr(flow, "trace", []) or [])
if len(trace) < _MIN_TRACE_HOPS:
continue
flows.append(
FlowTrace(
- entry_point=str(getattr(flow, "entry_point", "")),
+ entry_point=str(getattr(flow, "entry_point_id", "")),
hops=trace[:_TRACE_DISPLAY_HOPS],
- score=float(getattr(flow, "score", 0.0) or 0.0),
+ score=float(getattr(flow, "entry_point_score", 0.0) or 0.0),
)
)
return flows
diff --git a/tests/unit/generation/test_overview_execution_flows.py b/tests/unit/generation/test_overview_execution_flows.py
new file mode 100644
index 000000000..8afd666da
--- /dev/null
+++ b/tests/unit/generation/test_overview_execution_flows.py
@@ -0,0 +1,181 @@
+"""The overview's execution-flow section, end to end.
+
+``assemble_repo_overview`` reads the traced flows off the graph builder and the
+overview templates render them. Every step of that is asserted here because the
+section has never appeared on a generated page: the assembler read attribute
+names the ``ExecutionFlow`` dataclass does not have, the ``AttributeError`` was
+swallowed by a bare ``except``, and the ``{% if ctx.execution_flows %}`` guard
+then dropped the section without a word.
+"""
+
+from __future__ import annotations
+
+import pytest
+from structlog.testing import capture_logs
+
+from repowise.core.analysis.execution_flows import ExecutionFlow, ExecutionFlowReport
+from repowise.core.generation.context_assembler import ContextAssembler
+
+
+class _Builder:
+ """Minimal stand-in for the graph builder's two overview-facing calls."""
+
+ def __init__(self, flows):
+ self._flows = flows
+
+ def community_info(self):
+ return []
+
+ def execution_flows(self):
+ return ExecutionFlowReport(
+ total_entry_points_scored=len(self._flows),
+ total_flows=len(self._flows),
+ flows=list(self._flows),
+ )
+
+
+def _flow(entry_point_id: str, score: float, trace: list[str]) -> ExecutionFlow:
+ return ExecutionFlow(
+ entry_point_id=entry_point_id,
+ entry_point_name=entry_point_id.rsplit("::", 1)[-1],
+ entry_point_score=score,
+ trace=trace,
+ depth=len(trace) - 1,
+ crosses_community=False,
+ communities_visited=[0],
+ )
+
+
+def flows():
+ return [
+ _flow("packages/cli/src/repowise/cli/main.py::main", 0.9123, ["a", "b", "c"]),
+ _flow("packages/server/src/repowise/server/app.py::create_app", 0.4567, ["d", "e"]),
+ ]
+
+
+def test_overview_context_carries_traced_flows(sample_config, sample_repo_structure, flows):
+ """The reason the section never rendered: this list was always empty."""
+ assembler = ContextAssembler(sample_config)
+ ctx = assembler.assemble_repo_overview(
+ sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows)
+ )
+
+ assert len(ctx.execution_flows) == 2
+ first = ctx.execution_flows[0]
+ assert first["entry_point"] == "packages/cli/src/repowise/cli/main.py::main"
+ assert first["entry_point_name"] == "main"
+ assert first["score"] == 0.912
+ assert first["trace_length"] == 3
+
+
+def test_overview_context_ranks_flows_by_score(sample_config, sample_repo_structure):
+ """The template renders the first five, so the order is the selection."""
+ assembler = ContextAssembler(sample_config)
+ unordered = [
+ _flow("low.py::f", 0.1, ["a", "b"]),
+ _flow("high.py::f", 0.9, ["a", "b"]),
+ _flow("mid.py::f", 0.5, ["a", "b"]),
+ ]
+ ctx = assembler.assemble_repo_overview(
+ sample_repo_structure, {}, [], {}, graph_builder=_Builder(unordered)
+ )
+ assert [f["entry_point"] for f in ctx.execution_flows] == [
+ "high.py::f",
+ "mid.py::f",
+ "low.py::f",
+ ]
+
+
+def test_overview_context_warns_when_flows_cannot_be_read(sample_config, sample_repo_structure):
+ """A builder that raises must say so. This is the failure that hid for a year."""
+
+ class _Broken:
+ def community_info(self):
+ return []
+
+ def execution_flows(self):
+ raise RuntimeError("graph not built")
+
+ assembler = ContextAssembler(sample_config)
+ with capture_logs() as logs:
+ ctx = assembler.assemble_repo_overview(
+ sample_repo_structure, {}, [], {}, graph_builder=_Broken()
+ )
+
+ assert ctx.execution_flows == []
+ warned = [e for e in logs if e["event"] == "overview_execution_flows_unavailable"]
+ assert len(warned) == 1
+ assert warned[0]["error_type"] == "RuntimeError"
+ assert warned[0]["log_level"] == "warning"
+
+
+def test_overview_context_no_builder_is_silent(sample_config, sample_repo_structure):
+ """No builder is not a failure, so it must not warn."""
+ assembler = ContextAssembler(sample_config)
+ with capture_logs() as logs:
+ ctx = assembler.assemble_repo_overview(sample_repo_structure, {}, [], {})
+ assert ctx.execution_flows == []
+ assert [e for e in logs if e["event"].startswith("overview_")] == []
+
+
+# ---------------------------------------------------------------------------
+# rendered output — both templates read the same context key
+# ---------------------------------------------------------------------------
+
+
[email protected]("template", ["repo_overview.j2", "stub/repo_overview.j2"])
+def test_rendered_overview_names_the_entry_point(
+ sample_config, sample_repo_structure, flows, template
+):
+ """Both templates were always correct — they read the context dict, whose
+ keys never changed. They rendered nothing because the list reaching them
+ was empty. Asserted on both so a future key rename fails here rather than
+ quietly emptying the section again."""
+ from repowise.core.generation.page_generator import PageGenerator
+ from repowise.core.providers.llm.mock import MockProvider
+
+ assembler = ContextAssembler(sample_config)
+ gen = PageGenerator(MockProvider(), assembler, sample_config)
+ ctx = assembler.assemble_repo_overview(
+ sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows)
+ )
+ out = gen._render(template, ctx=ctx, repo_git_summary=None)
+
+ assert "## Primary Execution Flows" in out
+ assert "packages/cli/src/repowise/cli/main.py::main" in out
+ assert "``" not in out.split("## Primary Execution Flows", 1)[1].split("##", 1)[0]
+
+
+# ---------------------------------------------------------------------------
+# the same field names, read by the other consumer
+# ---------------------------------------------------------------------------
+
+
+def test_how_it_works_flow_traces_carry_entry_point_and_score(flows):
+ """``_collect_flows`` reads the same dataclass and had the same defect.
+
+ Its two ``getattr`` calls carried defaults, so instead of raising it
+ produced a ``FlowTrace`` with an empty entry point and a zero score for
+ every flow on every page ever generated.
+ """
+ from types import SimpleNamespace
+
+ from repowise.core.generation.onboarding.subkinds.how_it_works import _collect_flows
+
+ long_enough = [
+ _flow("packages/cli/src/repowise/cli/main.py::main", 0.9, ["a", "b", "c", "d"]),
+ ]
+ signals = SimpleNamespace(
+ graph_builder=SimpleNamespace(
+ execution_flows=lambda: ExecutionFlowReport(
+ total_entry_points_scored=1, total_flows=1, flows=long_enough
+ )
+ )
+ )
+
+ traces = _collect_flows(signals)
+
+ assert len(traces) == 1
+ assert traces[0].entry_point == "packages/cli/src/repowise/cli/main.py::main"
+ assert traces[0].score == pytest.approx(0.9)