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(progress): decompose graph build into reportable sub-phases (#150)

Raghav Chamadiya1ac24cc14dab
diff --git a/packages/cli/src/repowise/cli/ui.py b/packages/cli/src/repowise/cli/ui.py
index 7c25db73d..0d5b22f4e 100644
--- a/packages/cli/src/repowise/cli/ui.py
+++ b/packages/cli/src/repowise/cli/ui.py
@@ -1126,6 +1126,12 @@ _PHASE_LABELS: dict[str, str] = {
"traverse": "Scanning & filtering files...",
"parse": "Parsing files...",
"graph": "Building dependency graph...",
+ "graph.imports": " ↳ Resolving imports",
+ "graph.heritage": " ↳ Resolving inheritance",
+ "graph.calls": " ↳ Resolving call edges",
+ "graph.metrics": " ↳ Computing PageRank / centrality",
+ "graph.communities": " ↳ Detecting communities",
+ "graph.flows": " ↳ Tracing execution flows",
"git": "Indexing file history...",
"co_change": "Analyzing co-changes...",
"dead_code": "Detecting dead code...",
diff --git a/packages/core/src/repowise/core/ingestion/graph.py b/packages/core/src/repowise/core/ingestion/graph.py
index 9b0c80077..3bde3ddea 100644
--- a/packages/core/src/repowise/core/ingestion/graph.py
+++ b/packages/core/src/repowise/core/ingestion/graph.py
@@ -181,8 +181,14 @@ class GraphBuilder:
)
self._graph.add_edge(path, module_sym_id, edge_type="defines")
- def build(self) -> nx.DiGraph:
- """Resolve imports and calls, add edges. Returns the finalized graph."""
+ def build(self, progress: Any | None = None) -> nx.DiGraph:
+ """Resolve imports and calls, add edges. Returns the finalized graph.
+
+ *progress* is an optional ``ProgressCallback`` (duck-typed). When
+ provided, sub-phase events ``graph.imports`` / ``graph.heritage`` /
+ ``graph.calls`` are emitted so the CLI can surface per-file progress
+ instead of a single opaque "0/1" bar over the whole build.
+ """
# Invalidate cached metrics
self._community_cache = None
self._symbol_community_cache = None
@@ -220,6 +226,8 @@ class GraphBuilder:
# --- Phase 1: Resolve file-level imports ---
import_targets: dict[str, set[str]] = {} # file → set of imported files
+ if progress:
+ progress.on_phase_start("graph.imports", len(self._parsed_files))
for path, parsed in self._parsed_files.items():
file_imports: set[str] = set()
for imp in parsed.imports:
@@ -240,12 +248,18 @@ class GraphBuilder:
imported_names=list(imp.imported_names),
)
import_targets[path] = file_imports
+ if progress:
+ progress.on_item_done("graph.imports")
+ if progress:
+ _phase_done = getattr(progress, "on_phase_done", None)
+ if _phase_done is not None:
+ _phase_done("graph.imports")
# --- Phase 2: Resolve heritage (extends/implements) ---
- self._resolve_heritage(import_targets)
+ self._resolve_heritage(import_targets, progress=progress)
# --- Phase 3: Resolve symbol-level calls ---
- self._resolve_calls(import_targets)
+ self._resolve_calls(import_targets, progress=progress)
self._built = True
@@ -271,17 +285,23 @@ class GraphBuilder:
)
return self._graph
- def _resolve_heritage(self, import_targets: dict[str, set[str]]) -> None:
+ def _resolve_heritage(
+ self,
+ import_targets: dict[str, set[str]],
+ progress: Any | None = None,
+ ) -> None:
"""Resolve heritage relations and add EXTENDS/IMPLEMENTS edges."""
from .heritage_resolver import HeritageResolver
resolver = HeritageResolver(self._parsed_files, import_targets)
total_resolved = 0
- for path, parsed in self._parsed_files.items():
- if not parsed.heritage:
- continue
-
+ files_with_heritage = [
+ (p, pf) for p, pf in self._parsed_files.items() if pf.heritage
+ ]
+ if progress:
+ progress.on_phase_start("graph.heritage", len(files_with_heritage))
+ for path, parsed in files_with_heritage:
resolved = resolver.resolve_file(path, parsed.heritage)
for rh in resolved:
if rh.child_id in self._graph and rh.parent_id in self._graph:
@@ -297,20 +317,32 @@ class GraphBuilder:
existing = self._graph[rh.child_id][rh.parent_id]
if rh.confidence > existing.get("confidence", 0):
existing["confidence"] = rh.confidence
+ if progress:
+ progress.on_item_done("graph.heritage")
+ if progress:
+ _phase_done = getattr(progress, "on_phase_done", None)
+ if _phase_done is not None:
+ _phase_done("graph.heritage")
log.info("Heritage edges resolved", total=total_resolved)
- def _resolve_calls(self, import_targets: dict[str, set[str]]) -> None:
+ def _resolve_calls(
+ self,
+ import_targets: dict[str, set[str]],
+ progress: Any | None = None,
+ ) -> None:
"""Run three-tier call resolution and add CALLS edges to the graph."""
from .call_resolver import CallResolver
resolver = CallResolver(self._parsed_files, import_targets)
total_resolved = 0
- for path, parsed in self._parsed_files.items():
- if not parsed.calls:
- continue
-
+ files_with_calls = [
+ (p, pf) for p, pf in self._parsed_files.items() if pf.calls
+ ]
+ if progress:
+ progress.on_phase_start("graph.calls", len(files_with_calls))
+ for path, parsed in files_with_calls:
resolved = resolver.resolve_file(path, parsed.calls)
for rc in resolved:
if rc.caller_id in self._graph and rc.callee_id in self._graph:
@@ -326,7 +358,13 @@ class GraphBuilder:
existing = self._graph[rc.caller_id][rc.callee_id]
if rc.confidence > existing.get("confidence", 0):
existing["confidence"] = rc.confidence
+ if progress:
+ progress.on_item_done("graph.calls")
+ if progress:
+ _phase_done = getattr(progress, "on_phase_done", None)
+ if _phase_done is not None:
+ _phase_done("graph.calls")
log.info("Call edges resolved", total=total_resolved)
def graph(self) -> nx.DiGraph:
diff --git a/packages/core/src/repowise/core/pipeline/orchestrator.py b/packages/core/src/repowise/core/pipeline/orchestrator.py
index 10f0b5ce6..64b3c1721 100644
--- a/packages/core/src/repowise/core/pipeline/orchestrator.py
+++ b/packages/core/src/repowise/core/pipeline/orchestrator.py
@@ -339,10 +339,13 @@ async def run_pipeline(
# ---- Execution flow tracing -----------------------------------------------
execution_flow_report = None
+ if progress:
+ progress.on_phase_start("graph.flows", None)
try:
- execution_flow_report = graph_builder.execution_flows()
+ execution_flow_report = await asyncio.to_thread(graph_builder.execution_flows)
except Exception as _flow_err:
logger.warning("execution_flow_tracing_skipped", error=str(_flow_err))
+ _phase_done(progress, "graph.flows")
# ---- Build result -------------------------------------------------------
elapsed = time.monotonic() - start
@@ -522,14 +525,17 @@ async def _run_ingestion(
logger.warning("tsconfig_resolver_init_failed", error=str(_resolver_exc))
# ---- Graph build phase -------------------------------------------------
+ # Sub-phases (graph.imports / graph.heritage / graph.calls) are emitted
+ # from inside GraphBuilder.build(); the orchestrator drives metrics/
+ # communities/flows below so the longest-running step is no longer an
+ # opaque "graph 0/1" spinner.
if progress:
- progress.on_phase_start("graph", 1)
progress.on_message(
"info",
" (graph build can take several minutes on first run — safe to "
"Ctrl-C, then run 'repowise init --resume' to continue)",
)
- await asyncio.to_thread(graph_builder.build)
+ await asyncio.to_thread(graph_builder.build, progress)
# Add framework-aware synthetic edges (conftest, Django, FastAPI, Flask)
try:
@@ -551,9 +557,22 @@ async def _run_ingestion(
except Exception as hints_exc:
logger.warning("dynamic_hints_failed", error=str(hints_exc))
+ # ---- Graph metrics: prime caches with live progress ---------------------
+ # pagerank/betweenness/community/symbol_communities/execution_flows are
+ # otherwise computed lazily during persist + generation, where they hide
+ # behind opaque progress bars. Pre-compute them here so each is its own
+ # visible sub-phase.
+ if progress:
+ progress.on_phase_start("graph.metrics", None)
+ await asyncio.to_thread(graph_builder.pagerank)
+ await asyncio.to_thread(graph_builder.betweenness_centrality)
+ _phase_done(progress, "graph.metrics")
+
if progress:
- progress.on_item_done("graph")
- _phase_done(progress, "graph")
+ progress.on_phase_start("graph.communities", None)
+ await asyncio.to_thread(graph_builder.community_detection)
+ await asyncio.to_thread(graph_builder.symbol_communities)
+ _phase_done(progress, "graph.communities")
# Emit filtering summary so users can see what was included/excluded
stats = traverser.stats