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(pipeline): make `repowise init --resume` actually resume (#343)

Raghav Chamadiyaf433e4c97030
diff --git a/docs/CONFIG.md b/docs/CONFIG.md
index a4069fd7a..17ba3059b 100644
--- a/docs/CONFIG.md
+++ b/docs/CONFIG.md
@@ -185,7 +185,14 @@ The `.repowise/.env` file is gitignored automatically.
## Exclude patterns
repowise respects your `.gitignore` automatically (same `gitwildmatch` format git
-uses). On top of that, add extra patterns via `--exclude` / `-x`:
+uses). Like git, it reads **nested `.gitignore` files** too — a `.gitignore` in
+any subdirectory applies to that directory's contents. This matters for
+monorepos and yarn/npm workspaces, where a package keeps its own `.gitignore`
+excluding that package's build output (e.g. `dist/`, `coverage/`, generated
+bundles) — those exclusions are now honoured without duplicating them at the
+repo root.
+
+On top of that, add extra patterns via `--exclude` / `-x`:
```bash
repowise init -x vendor/ -x "*.generated.ts" -x proto/ -x "**/*.pb.go"
@@ -193,7 +200,7 @@ repowise init -x vendor/ -x "*.generated.ts" -x proto/ -x "**/*.pb.go"
Patterns are saved to `config.yaml` and applied on subsequent `update` runs. You
can also create a `.repowiseIgnore` file (same gitignore syntax) at the repo root
-or in any subdirectory for more granular control.
+or in any subdirectory for more granular control without touching `.gitignore`.
Built-in exclusions (always applied): `.git/`, `.repowise/`, `node_modules/`,
`__pycache__/`, `*.pyc`, `.venv/`, binary files, lockfiles, and minified assets.
diff --git a/packages/cli/src/repowise/cli/commands/_generation_persist.py b/packages/cli/src/repowise/cli/commands/_generation_persist.py
new file mode 100644
index 000000000..72f31e6a3
--- /dev/null
+++ b/packages/cli/src/repowise/cli/commands/_generation_persist.py
@@ -0,0 +1,147 @@
+"""Incremental, resume-friendly page generation for ``repowise init``.
+
+The orchestrator's :func:`run_generation` buffers every page in memory and the
+CLI writes them to the database only once, at the very end of the run, from
+``_persist_result``. That is fine for a clean run but loses everything when a
+long generation phase is interrupted: the pages already embedded into the
+vector store are skipped on the next resume (the store is the resume ground
+truth) yet were never written to the ``pages`` table, so the wiki ends up
+permanently missing them.
+
+:func:`run_generation_with_persistence` closes that gap with two cooperating
+mechanisms, both best-effort so neither can fail a generation run:
+
+* **prior-page reuse** — every persisted page is loaded up front and handed to
+ the generator, which skips the LLM call whenever a freshly rendered prompt
+ still hashes to the stored value under the same model (the same reuse
+ ``repowise update`` performs).
+* **incremental flush** — each page is written to the database the instant it
+ is generated, via the generator's ``on_page_ready`` sink. An interrupt then
+ leaves a usable, partially-complete wiki on disk, and the next resume reuses
+ those pages instead of regenerating them.
+
+The flush runs on its own engine and is the sole writer of ``wiki.db`` during
+generation (cost rows are buffered and flushed afterwards, issue #326), so it
+introduces no write contention. Writes are idempotent — :func:`upsert_page`
+is a no-op when content, prompt hash and model are unchanged — so the
+end-of-run ``_persist_result`` re-write of the same pages neither bumps their
+version nor spawns redundant history.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+# Hard cap on how long the drain of the persistence queue may take after
+# generation finishes, so a wedged DB write can never hang the CLI.
+_DRAIN_TIMEOUT_SECS = 60.0
+
+
+async def run_generation_with_persistence(
+ *,
+ repo_path: Path,
+ repo_name: str,
+ reuse_prior_pages: bool = True,
+ **generation_kwargs: Any,
+) -> list[Any]:
+ """Run :func:`run_generation`, reusing + incrementally persisting pages.
+
+ ``generation_kwargs`` are forwarded verbatim to ``run_generation``; callers
+ must not pass ``prior_pages`` or ``on_page_ready`` (this wrapper owns both).
+ Returns the generated pages exactly as ``run_generation`` would.
+ """
+ from repowise.cli.helpers import get_db_url_for_repo
+ from repowise.core.persistence import (
+ create_engine,
+ create_session_factory,
+ get_session,
+ init_db,
+ load_prior_pages,
+ upsert_repository,
+ )
+ from repowise.core.persistence.crud import upsert_page_from_generated
+ from repowise.core.pipeline import run_generation
+
+ url = get_db_url_for_repo(repo_path)
+ engine = create_engine(url)
+ await init_db(engine)
+ sf = create_session_factory(engine)
+
+ async with get_session(sf) as session:
+ repo_id = (
+ await upsert_repository(session, name=repo_name, local_path=str(repo_path))
+ ).id
+
+ prior_pages: dict[str, Any] = {}
+ if reuse_prior_pages:
+ try:
+ async with get_session(sf) as session:
+ prior_pages = await load_prior_pages(session, repo_id)
+ if prior_pages:
+ logger.info("generation.prior_pages_loaded", count=len(prior_pages))
+ except Exception as exc:
+ logger.debug("generation.prior_pages_load_failed", error=str(exc))
+ prior_pages = {}
+
+ # A bounded handoff queue decouples the synchronous on_page_ready callback
+ # (fired inside the generation loop) from the async DB writes, so a slow
+ # write never stalls page generation. A sentinel closes the consumer.
+ queue: asyncio.Queue[Any] = asyncio.Queue()
+ sentinel = object()
+ saved = 0
+
+ async def _consumer() -> None:
+ nonlocal saved
+ while True:
+ page = await queue.get()
+ try:
+ if page is sentinel:
+ return
+ try:
+ async with get_session(sf) as session:
+ await upsert_page_from_generated(session, page, repo_id)
+ saved += 1
+ except Exception as exc:
+ logger.debug(
+ "generation.incremental_persist_failed",
+ page_id=getattr(page, "page_id", "?"),
+ error=str(exc),
+ )
+ finally:
+ queue.task_done()
+
+ consumer_task = asyncio.create_task(_consumer())
+
+ def _on_page_ready(page: Any) -> None:
+ # Synchronous, called from the generation loop — must never raise.
+ with contextlib.suppress(Exception):
+ queue.put_nowait(page)
+
+ try:
+ pages = await run_generation(
+ repo_path=repo_path,
+ **generation_kwargs,
+ prior_pages=prior_pages,
+ on_page_ready=_on_page_ready,
+ )
+ finally:
+ await queue.put(sentinel)
+ try:
+ await asyncio.wait_for(consumer_task, timeout=_DRAIN_TIMEOUT_SECS)
+ except TimeoutError:
+ logger.warning("generation.persist_drain_timeout", saved=saved)
+ consumer_task.cancel()
+ except Exception as exc:
+ logger.debug("generation.persist_consumer_error", error=str(exc))
+ await engine.dispose()
+
+ if saved:
+ logger.info("generation.incremental_persist_done", pages_flushed=saved)
+ return pages
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd.py b/packages/cli/src/repowise/cli/commands/init_cmd.py
index f712728b8..e24816810 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd.py
@@ -185,6 +185,35 @@ _build_embedder = build_embedder
# ---------------------------------------------------------------------------
+async def _build_resume_controller(repo_path: Path, *, resume: bool) -> tuple[Any, Any]:
+ """Create the repo row + a ResumeController bound to a fresh engine.
+
+ Returns ``(controller, engine)``. The caller runs the pipeline in the same
+ event loop and disposes the engine afterwards. The repository row is
+ created up front so the controller checkpoints against a real
+ ``Repository.id`` (not ``str(repo_path)``), and so an interrupted run
+ leaves a resumable, persisted index behind.
+ """
+ from repowise.cli.helpers import get_db_url_for_repo
+ from repowise.core.persistence import (
+ create_engine,
+ create_session_factory,
+ get_session,
+ init_db,
+ upsert_repository,
+ )
+ from repowise.core.pipeline.resume import ResumeController
+
+ engine = create_engine(get_db_url_for_repo(repo_path))
+ await init_db(engine)
+ sf = create_session_factory(engine)
+ async with get_session(sf) as session:
+ repo_id = (
+ await upsert_repository(session, name=repo_path.name, local_path=str(repo_path))
+ ).id
+ return ResumeController(sf, repo_id, resume=resume), engine
+
+
async def _persist_result(
result: Any,
repo_path: Path,
@@ -202,13 +231,23 @@ async def _persist_result(
init_db,
upsert_repository,
)
- from repowise.core.pipeline import persist_pipeline_result
+ from repowise.core.pipeline import (
+ persist_analysis,
+ persist_generation,
+ persist_pipeline_result,
+ )
url = get_db_url_for_repo(repo_path)
engine = create_engine(url)
await init_db(engine)
sf = create_session_factory(engine)
+ # When a ResumeController persisted the INDEX phase incrementally during
+ # the run, the graph + git + symbols are already on disk — write only the
+ # analysis + generation outputs here (avoids re-persisting a rehydrated
+ # graph and a redundant full index write).
+ index_done = bool(getattr(result, "index_persisted_incrementally", False))
+
fts = None
if result.generated_pages:
fts = FullTextSearch(engine)
@@ -236,7 +275,11 @@ async def _persist_result(
existing = {}
existing["tech_stack"] = result.tech_stack
repo.settings_json = _json.dumps(existing)
- await persist_pipeline_result(result, session, repo.id)
+ if index_done:
+ await persist_analysis(result, session, repo.id)
+ await persist_generation(result, session, repo.id)
+ else:
+ await persist_pipeline_result(result, session, repo.id)
# Record a completed GenerationJob so the web UI can show
# "last synced" / "last re-indexed" timestamps.
@@ -263,6 +306,20 @@ async def _persist_result(
for page in result.generated_pages:
await fts.index(page.page_id, page.title, page.content)
+ # Stamp the analysis (+ generation) phases in the resume ledger now that
+ # they're persisted, so a future resume can skip them too.
+ if index_done:
+ from repowise.core.pipeline.resume import ResumeLedger, ResumePhase
+
+ async with get_session(sf) as _ls:
+ repo_id = (
+ await upsert_repository(_ls, name=result.repo_name, local_path=str(repo_path))
+ ).id
+ ledger = ResumeLedger(sf, repo_id)
+ await ledger.mark_completed(ResumePhase.ANALYSIS)
+ if result.generated_pages:
+ await ledger.mark_completed(ResumePhase.GENERATION)
+
await engine.dispose()
@@ -297,7 +354,8 @@ def _run_workspace_generation(
from repowise.cli.cost_estimator import build_generation_plan, estimate_cost
from repowise.cli.ui import RichProgressCallback
from repowise.core.generation import GenerationConfig
- from repowise.core.pipeline import run_generation
+
+ from ._generation_persist import run_generation_with_persistence
# Build embedder + vector store
embedder_impl: Any = build_embedder(embedder_name_resolved)
@@ -413,8 +471,9 @@ def _run_workspace_generation(
gen_callback = RichProgressCallback(gen_progress, console)
generated_pages = run_async(
- run_generation(
+ run_generation_with_persistence(
repo_path=repo_path,
+ repo_name=result.repo_name,
parsed_files=result.parsed_files,
source_map=result.source_map,
graph_builder=result.graph_builder,
@@ -488,6 +547,7 @@ class _WorkspaceCtx:
resolved_reasoning: str
embedder_name_resolved: str
resolved_commit_limit: int
+ run_mode: str = "standard"
@dataclass
@@ -511,6 +571,7 @@ def _ingest_and_generate_repo(repo: Any, idx: int, total: int, ctx: _WorkspaceCt
from datetime import datetime
from repowise.core.pipeline import PhaseTimingRecorder, run_pipeline
+ from repowise.core.pipeline.modes import OrchestratorMode
console.print(
f" [{BRAND}][{idx}/{total}][/] Indexing [bold]{repo.alias}[/bold] ({repo.path.name})..."
@@ -541,6 +602,11 @@ def _ingest_and_generate_repo(repo: Any, idx: int, total: int, ctx: _WorkspaceCt
exclude_patterns=ctx.exclude_patterns if ctx.exclude_patterns else None,
include_submodules=ctx.include_submodules,
generate_docs=False,
+ mode=(
+ OrchestratorMode.FAST
+ if ctx.run_mode == "fast"
+ else OrchestratorMode.STANDARD
+ ),
progress=callback,
existing_kg_fingerprint=_prev_kg_fp,
)
@@ -776,6 +842,7 @@ def _workspace_init(
onboarding: bool = True,
coverage_pct: float | None = None,
harvest_decisions: bool = True,
+ run_mode: str = "standard",
) -> None:
"""Multi-repo workspace initialization.
@@ -928,6 +995,7 @@ def _workspace_init(
resolved_reasoning=resolved_reasoning,
embedder_name_resolved=embedder_name_resolved,
resolved_commit_limit=resolved_commit_limit,
+ run_mode=run_mode,
)
for i, repo in enumerate(selected, 1):
@@ -1192,8 +1260,9 @@ def _run_generation_phase(
embedder_impl: Any = build_embedder(embedder_name_resolved)
vector_store: Any = build_vector_store(repo_path, embedder_impl)
- # Run generation via the pipeline's generation function
- from repowise.core.pipeline import run_generation
+ # Run generation via the pipeline's generation function, wrapped so
+ # pages are reused + flushed incrementally (resume-friendly).
+ from ._generation_persist import run_generation_with_persistence
with Progress(
SpinnerColumn(),
@@ -1217,8 +1286,9 @@ def _run_generation_phase(
provider._cost_tracker = cost_tracker
generated_pages = run_async(
- run_generation(
+ run_generation_with_persistence(
repo_path=repo_path,
+ repo_name=result.repo_name,
parsed_files=result.parsed_files,
source_map=result.source_map,
graph_builder=result.graph_builder,
@@ -1276,6 +1346,31 @@ def _run_generation_phase(
return False, cost_declined
+def _git_tier_for_run_mode(run_mode: str) -> str:
+ """Map a CLI run-mode to the git index tier it persisted.
+
+ Fast mode indexes the ESSENTIAL tier (no per-file blame / co-change);
+ standard mode indexes FULL. Recorded in state.json so ``--resume`` and
+ ``repowise update`` know which tier already exists on disk.
+ """
+ return "essential" if run_mode == "fast" else "full"
+
+
+def _effective_run_mode_for_resume(repo_path: Path, run_mode: str, resume: bool) -> str:
+ """On ``--resume``, continue the git tier the prior run used.
+
+ A fast (ESSENTIAL-tier) run resumed *without* re-passing ``--mode fast``
+ would otherwise default to STANDARD and silently redo the expensive FULL
+ git indexing the first run deliberately skipped (issue #341). We restore
+ the persisted ``run_mode`` unless the user explicitly asked for fast on
+ the resume invocation (in which case fast already wins).
+ """
+ if not resume or run_mode == "fast":
+ return run_mode
+ prev = load_state(repo_path).get("run_mode")
+ return prev if prev in ("fast", "standard") else run_mode
+
+
def _save_full_state_and_config(
*,
repo_path: Path,
@@ -1323,6 +1418,9 @@ def _save_full_state_and_config(
state["provider"] = provider.provider_name
state["model"] = provider.model_name
state["docs_enabled"] = True
+ # Full-mode docs runs always index the FULL git tier.
+ state["run_mode"] = "standard"
+ state["git_tier"] = "full"
total_tokens = sum(p.total_tokens for p in (result.generated_pages or []))
state["total_tokens"] = total_tokens
if phase_timings:
@@ -1690,6 +1788,7 @@ def init_command(
onboarding=onboarding,
coverage_pct=coverage_pct,
harvest_decisions=harvest_decisions,
+ run_mode=run_mode,
)
return
@@ -1704,6 +1803,13 @@ def init_command(
# Suppress library/structlog output — progress bars are the only output needed.
setup_logging_silence()
+ # On --resume, continue the prior run's git tier so a resumed fast index
+ # doesn't silently fall back to the expensive FULL tier (issue #341). Done
+ # before the interactive gate so a resume never re-prompts for the mode.
+ run_mode = _effective_run_mode_for_resume(repo_path, run_mode, resume)
+ if run_mode == "fast":
+ index_only = True
+
# ---- Interactive mode (TTY, no explicit flags) ----
is_interactive = sys.stdin.isatty() and provider_name is None and not index_only
@@ -1896,24 +2002,53 @@ def init_command(
_prev_state.get("knowledge_graph", {}).get("fingerprint") if not force else None
)
- result = run_async(
- run_pipeline(
- repo_path,
- commit_depth=resolved_commit_limit,
- follow_renames=resolved_follow_renames,
- skip_tests=skip_tests,
- skip_infra=skip_infra,
- exclude_patterns=exclude_patterns if exclude_patterns else None,
- include_submodules=include_submodules,
- generate_docs=False,
- llm_client=llm_client,
- concurrency=concurrency,
- test_run=test_run,
- mode=orchestrator_mode,
- progress=callback,
- existing_kg_fingerprint=_prev_kg_fp,
+ async def _index_with_resume() -> Any:
+ # Create the engine, session factory, and repository row *before*
+ # the pipeline (all in this one event loop) so the resume
+ # controller has a stable Repository.id to checkpoint against —
+ # fixing the old str(repo_path) FK wiring — and so an interrupt
+ # mid-run leaves a resumable, persisted index behind. Skipped on a
+ # dry run, which must not touch the database at all.
+ controller = None
+ engine = None
+ if not dry_run:
+ controller, engine = await _build_resume_controller(repo_path, resume=resume)
+ try:
+ return await run_pipeline(
+ repo_path,
+ commit_depth=resolved_commit_limit,
+ follow_renames=resolved_follow_renames,
+ skip_tests=skip_tests,
+ skip_infra=skip_infra,
+ exclude_patterns=exclude_patterns if exclude_patterns else None,
+ include_submodules=include_submodules,
+ generate_docs=False,
+ llm_client=llm_client,
+ concurrency=concurrency,
+ test_run=test_run,
+ mode=orchestrator_mode,
+ progress=callback,
+ existing_kg_fingerprint=_prev_kg_fp,
+ resume_controller=controller,
+ )
+ finally:
+ if engine is not None:
+ await engine.dispose()
+
+ # Make the long synchronous index/analysis phases interruptible: the
+ # first Ctrl-C unwinds them cleanly (the INDEX checkpoint already on
+ # disk is reused on the next --resume), a second forces a hard quit.
+ from repowise.core.cancellation import PipelineCancelled, cancellation_scope
+
+ try:
+ with cancellation_scope():
+ result = run_async(_index_with_resume())
+ except (PipelineCancelled, KeyboardInterrupt):
+ console.print(
+ "\n[yellow]Interrupted.[/] Indexed work so far has been saved — "
+ "run [bold]repowise init --resume[/] to continue where it stopped."
)
- )
+ return
# Surface per-phase timing data to the caller — both for the
# state.json persistence below and for any future "profile" tooling
@@ -2010,6 +2145,10 @@ def init_command(
base_state = load_state(repo_path)
base_state["last_sync_commit"] = head
base_state["docs_enabled"] = not effective_index_only and provider is not None
+ # Record the git tier this run indexed so a later --resume continues the
+ # same tier instead of silently upgrading ESSENTIAL → FULL (issue #341).
+ base_state["run_mode"] = run_mode
+ base_state["git_tier"] = _git_tier_for_run_mode(run_mode)
if phase_timings:
base_state["phase_timings"] = phase_timings
kg = getattr(result, "knowledge_graph_result", None)
diff --git a/packages/core/src/repowise/core/analysis/health/duplication/detector.py b/packages/core/src/repowise/core/analysis/health/duplication/detector.py
index 7e8063616..7396669a3 100644
--- a/packages/core/src/repowise/core/analysis/health/duplication/detector.py
+++ b/packages/core/src/repowise/core/analysis/health/duplication/detector.py
@@ -30,6 +30,8 @@ from typing import Any
import structlog
+from repowise.core.cancellation import check_cancelled
+
from .limits import DuplicationDiagnostics, DuplicationLimits, looks_minified
from .rabin_karp import WindowHash, index_by_hash, rolling_hashes
from .tokenizer import Token, tokenize_file
@@ -257,6 +259,7 @@ def _collect_windows(
all_windows: list[WindowHash] = []
for pf in parsed_files:
+ check_cancelled()
diag.files_considered += 1
path = pf.file_info.path
language = pf.file_info.language
@@ -320,7 +323,9 @@ def _pairs_from_buckets(
if len(windows) > limits.max_bucket_windows:
diag.degenerate_buckets += 1
continue
- # Check the clock occasionally (cheap) rather than per-pair.
+ # Bail promptly on Ctrl-C, and check the clock occasionally (cheap)
+ # rather than per-pair.
+ check_cancelled()
if deadline is not None and (i & 0x3FF) == 0 and time.monotonic() > deadline:
diag.timed_out = True
break
diff --git a/packages/core/src/repowise/core/cancellation.py b/packages/core/src/repowise/core/cancellation.py
new file mode 100644
index 000000000..269fc9e13
--- /dev/null
+++ b/packages/core/src/repowise/core/cancellation.py
@@ -0,0 +1,132 @@
+"""Cooperative cancellation for long synchronous pipeline phases.
+
+Heavy CPU phases (duplication detection, graph centrality, parsing) run inside
+``asyncio.to_thread`` workers. A bare Ctrl-C cannot interrupt such a worker —
+the event loop's KeyboardInterrupt frees the main thread, but the non-daemon
+worker keeps grinding, so the process never actually exits. That is the second
+half of issue #341: "Ctrl-C didn't return the terminal."
+
+The fix is cooperative: a process-global :class:`CancellationToken` is set by
+the CLI for the duration of a run, the long synchronous loops poll
+:func:`check_cancelled` at coarse intervals, and the first Ctrl-C flips the
+token so those loops unwind promptly with :class:`PipelineCancelled`.
+
+:class:`PipelineCancelled` deliberately subclasses :class:`BaseException` (like
+:class:`KeyboardInterrupt` and ``asyncio.CancelledError``) so the pipeline's
+many ``except Exception`` guards — e.g. the per-phase wrappers that downgrade a
+failure to "phase skipped" — never swallow a cancellation. It always
+propagates to the top, where the CLI turns it into a clean "run --resume" exit.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import signal
+import threading
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+class PipelineCancelled(BaseException):
+ """Raised by :func:`check_cancelled` when cancellation was requested."""
+
+
+class CancellationToken:
+ """A thread-safe one-way "please stop" flag.
+
+ Backed by :class:`threading.Event` so it can be flipped from a signal
+ handler on the main thread and observed from ``asyncio.to_thread`` workers.
+ """
+
+ def __init__(self) -> None:
+ self._event = threading.Event()
+
+ def cancel(self) -> None:
+ self._event.set()
+
+ @property
+ def cancelled(self) -> bool:
+ return self._event.is_set()
+
+
+# Process-global active token. ``None`` means cancellation is not armed, so
+# check_cancelled() is a no-op — the default everywhere except inside an active
+# cancellation_scope(). A plain module global (not a ContextVar) is intentional:
+# to_thread workers must see the same token the main thread armed.
+_active_token: CancellationToken | None = None
+
+
+def set_active_token(token: CancellationToken | None) -> None:
+ global _active_token
+ _active_token = token
+
+
+def get_active_token() -> CancellationToken | None:
+ return _active_token
+
+
+def check_cancelled() -> None:
+ """Raise :class:`PipelineCancelled` if the active token has been flipped.
+
+ Cheap enough to call inside hot loops at a coarse cadence (once per file,
+ once per hash bucket). A no-op when no token is armed.
+ """
+ token = _active_token
+ if token is not None and token.cancelled:
+ raise PipelineCancelled()
+
+
+@contextmanager
+def cancellation_scope(
+ on_first_interrupt: Callable[[], None] | None = None,
+) -> Iterator[CancellationToken]:
+ """Arm a cancellation token + a two-stage SIGINT handler for the block.
+
+ First Ctrl-C flips the token (long synchronous phases polling
+ :func:`check_cancelled` unwind cleanly) and fires ``on_first_interrupt`` if
+ given. A second Ctrl-C restores the previous handler and re-raises
+ ``KeyboardInterrupt`` to force-quit, so an impatient user is never trapped.
+
+ The previous token and signal handler are restored on exit. When not on the
+ main thread (signal handlers can only be installed there) the token is still
+ armed — callers may flip it manually — but no handler is installed.
+ """
+ token = CancellationToken()
+ prev_token = _active_token
+ set_active_token(token)
+
+ presses = {"count": 0}
+ installed = False
+ prev_handler: object = None
+
+ def _handler(signum: int, frame: object) -> None:
+ presses["count"] += 1
+ if presses["count"] >= 2:
+ # Second interrupt — hand control back to the default behaviour.
+ with contextlib.suppress(ValueError, OSError, TypeError):
+ signal.signal(signal.SIGINT, prev_handler or signal.default_int_handler) # type: ignore[arg-type]
+ raise KeyboardInterrupt
+ token.cancel()
+ if on_first_interrupt is not None:
+ # A notifier hiccup must not mask the interrupt.
+ with contextlib.suppress(Exception):
+ on_first_interrupt()
+
+ try:
+ try:
+ prev_handler = signal.getsignal(signal.SIGINT)
+ signal.signal(signal.SIGINT, _handler)
+ installed = True
+ except (ValueError, OSError):
+ # Not the main thread — proceed with the token armed but unsignaled.
+ installed = False
+ yield token
+ finally:
+ if installed:
+ with contextlib.suppress(ValueError, OSError, TypeError):
+ signal.signal(signal.SIGINT, prev_handler) # type: ignore[arg-type]
+ set_active_token(prev_token)
diff --git a/packages/core/src/repowise/core/ingestion/traverser.py b/packages/core/src/repowise/core/ingestion/traverser.py
index 62111ae25..05219a05f 100644
--- a/packages/core/src/repowise/core/ingestion/traverser.py
+++ b/packages/core/src/repowise/core/ingestion/traverser.py
@@ -2,8 +2,9 @@
FileTraverser walks a repository tree and yields FileInfo objects for each
source file that should be documented. It respects:
- 1. .gitignore (via pathspec)
- 2. .repowiseIgnore (same syntax, user overrides)
+ 1. .gitignore (via pathspec) — the repo-root file plus any nested
+ .gitignore in subdirectories (git reads one per directory, so does this)
+ 2. .repowiseIgnore (same syntax, user overrides) — root and per-directory
3. A hardcoded blocklist of dirs / file patterns
4. Binary file detection
5. File-size limit
@@ -218,8 +219,11 @@ class FileTraverser:
)
patterns = extra_exclude_patterns or []
self._extra_exclude = pathspec.PathSpec.from_lines("gitwildmatch", patterns)
- # Per-directory .repowiseIgnore cache: absolute dir path -> PathSpec.
- # Pre-seed root so it isn't read twice (we already have self._extra_ignore).
+ # Per-directory ignore cache: absolute dir path -> PathSpec built from
+ # that directory's nested .gitignore + .repowiseIgnore.
+ # Pre-seed root: its .gitignore is matched full-path via self._gitignore
+ # and its .repowiseIgnore via self._extra_ignore, so the root entry only
+ # needs the latter (avoids reading either file a second time).
self._dir_ignore_cache: dict[str, pathspec.PathSpec] = {
str(self.repo_root): self._extra_ignore,
}
@@ -315,14 +319,26 @@ class FileTraverser:
yield dirpath_obj / filename
def _get_dir_ignore(self, dirpath: Path) -> pathspec.PathSpec:
- """Return the per-directory .repowiseIgnore spec, loading and caching on first access."""
+ """Return the per-directory ignore spec, loading and caching on first access.
+
+ Merges the directory's nested ``.gitignore`` and ``.repowiseIgnore``
+ (in that order) into one spec. Git applies a ``.gitignore`` to its own
+ directory's entries — not just the repo root — so a monorepo/workspace
+ package with its own ``.gitignore`` (e.g. ``frontend/.gitignore``
+ excluding ``storybook-static/``) is honoured. Patterns are matched
+ against the immediate child name (see ``_should_skip_dir`` /
+ ``_build_file_info``), consistent with the existing per-directory
+ ``.repowiseIgnore`` handling.
+ """
key = str(dirpath)
if key not in self._dir_ignore_cache:
- ignore_file = dirpath / self._extra_ignore_filename
- if ignore_file.exists():
- lines = ignore_file.read_text(encoding="utf-8", errors="ignore").splitlines()
- else:
- lines = []
+ lines: list[str] = []
+ for name in (".gitignore", self._extra_ignore_filename):
+ ignore_file = dirpath / name
+ if ignore_file.exists():
+ lines.extend(
+ ignore_file.read_text(encoding="utf-8", errors="ignore").splitlines()
+ )
self._dir_ignore_cache[key] = pathspec.PathSpec.from_lines("gitwildmatch", lines)
return self._dir_ignore_cache[key]
diff --git a/packages/core/src/repowise/core/persistence/crud/pages.py b/packages/core/src/repowise/core/persistence/crud/pages.py
index 1d01a0078..cf17ae43e 100644
--- a/packages/core/src/repowise/core/persistence/crud/pages.py
+++ b/packages/core/src/repowise/core/persistence/crud/pages.py
@@ -64,6 +64,23 @@ async def upsert_page(
existing = existing_result.scalar_one_or_none()
if existing is not None:
+ # Idempotent no-op: when the content, prompt hash and model are all
+ # unchanged, re-persisting must not bump the version or spawn a
+ # PageVersion snapshot. This makes the write safe to repeat — e.g. an
+ # incremental per-page flush during generation followed by the
+ # end-of-run persist of the same page — without inflating history.
+ if (
+ existing.content == content
+ and existing.source_hash == source_hash
+ and existing.model_name == model_name
+ ):
+ existing.summary = summary
+ existing.target_path = target_path
+ existing.freshness_status = freshness_status
+ existing.metadata_json = meta_json
+ await session.flush()
+ return existing
+
# Archive the current state before overwriting
snapshot = PageVersion(
id=_new_uuid(),
diff --git a/packages/core/src/repowise/core/pipeline/__init__.py b/packages/core/src/repowise/core/pipeline/__init__.py
index 2bb45b116..13f8fcab8 100644
--- a/packages/core/src/repowise/core/pipeline/__init__.py
+++ b/packages/core/src/repowise/core/pipeline/__init__.py
@@ -11,7 +11,13 @@ Usage::
"""
from .orchestrator import PipelineResult, run_generation, run_pipeline
-from .persist import persist_pipeline_result
+from .persist import (
+ persist_analysis,
+ persist_generation,
+ persist_git,
+ persist_ingestion,
+ persist_pipeline_result,
+)
from .phase_timing import PhaseTimingRecorder
from .progress import LoggingProgressCallback, ProgressCallback
from .upgrade import rehydrate_graph_builder
@@ -21,6 +27,10 @@ __all__ = [
"PhaseTimingRecorder",
"PipelineResult",
"ProgressCallback",
+ "persist_analysis",
+ "persist_generation",
+ "persist_git",
+ "persist_ingestion",
"persist_pipeline_result",
"rehydrate_graph_builder",
"run_generation",
diff --git a/packages/core/src/repowise/core/pipeline/orchestrator.py b/packages/core/src/repowise/core/pipeline/orchestrator.py
index 4aee6ce7a..4639cbaae 100644
--- a/packages/core/src/repowise/core/pipeline/orchestrator.py
+++ b/packages/core/src/repowise/core/pipeline/orchestrator.py
@@ -34,7 +34,9 @@ from .phases.analysis import (
)
from .phases.generation import run_generation
from .phases.git import _run_git_indexing, drop_transient_git_signals
-from .phases.ingestion import _run_ingestion
+from .phases.ingestion import _run_ingestion, reparse_for_resume
+from .resume import ResumePhase
+from .resume.controller import ResumeController
logger = structlog.get_logger(__name__)
@@ -128,6 +130,12 @@ class PipelineResult:
search_codebase). None when no store was configured (semantic dedup is
then skipped; title dedup still runs)."""
+ index_persisted_incrementally: bool = False
+ """True when a ResumeController persisted (or rehydrated) the INDEX phase
+ during the run. The caller's final persist then skips the index portion —
+ it is already on disk — and writes only analysis + generation. False for
+ every non-resume caller, which persist the full result as before."""
+
# ---------------------------------------------------------------------------
# Pipeline
@@ -158,6 +166,7 @@ async def run_pipeline(
generation_config: Any | None = None,
existing_kg_fingerprint: str | None = None,
on_page_ready: Any | None = None,
+ resume_controller: ResumeController | None = None,
) -> PipelineResult:
"""Run the repowise indexing/analysis/generation pipeline.
@@ -263,26 +272,62 @@ async def run_pipeline(
progress=progress,
)
- (
- (
- parsed_files,
- file_infos,
- repo_structure,
- source_map,
- graph_builder,
- traversal_stats,
- tech_items,
- ),
- (
- git_summary,
- git_metadata_list,
- git_meta_map,
- ),
- ) = await asyncio.gather(_ingestion_stage(), _git_stage())
+ # Resume fast-path: when a prior run already persisted the INDEX phase
+ # (graph + git), rehydrate it from the DB and only re-parse source files —
+ # skipping the git history walk and the graph centrality kernels, which
+ # are the minutes-long work that makes a first index slow. Falls back to a
+ # full compute if rehydration yields no graph (nothing was persisted).
+ skip_index = bool(resume_controller and await resume_controller.can_skip(ResumePhase.INDEX))
+ git_summary = None
+ if skip_index:
+ try:
+ graph_builder, git_meta_map = await resume_controller.rehydrate_index(repo_path)
+ if progress:
+ progress.on_message(
+ "info", " ↳ Resuming — reusing persisted graph + git index"
+ )
+ (
+ parsed_files,
+ file_infos,
+ repo_structure,
+ source_map,
+ tech_items,
+ ) = await reparse_for_resume(
+ repo_path,
+ exclude_patterns=exclude_patterns,
+ include_submodules=include_submodules,
+ include_nested_repos=include_nested_repos,
+ skip_tests=skip_tests,
+ skip_infra=skip_infra,
+ progress=progress,
+ )
+ traversal_stats = None
+ git_metadata_list = list(git_meta_map.values())
+ except Exception as exc:
+ logger.warning("resume_rehydrate_failed_recomputing", error=str(exc))
+ skip_index = False
- # Add co-change edges to the graph
- if git_meta_map:
- graph_builder.add_co_change_edges(git_meta_map)
+ if not skip_index:
+ (
+ (
+ parsed_files,
+ file_infos,
+ repo_structure,
+ source_map,
+ graph_builder,
+ traversal_stats,
+ tech_items,
+ ),
+ (
+ git_summary,
+ git_metadata_list,
+ git_meta_map,
+ ),
+ ) = await asyncio.gather(_ingestion_stage(), _git_stage())
+
+ # Add co-change edges to the graph (rehydrated graphs already carry them)
+ if git_meta_map:
+ graph_builder.add_co_change_edges(git_meta_map)
# ---- External systems (C4 L1) ------------------------------------------
# Parse repo manifests for declared third-party dependencies. Failure here
@@ -315,6 +360,19 @@ async def run_pipeline(
logger.warning("external_systems_extraction_failed", error=str(_ext_err))
_phase_done(progress, "external_systems")
+ # ---- Checkpoint: INDEX -------------------------------------------------
+ # Persist the freshly-computed graph + git + symbols now so an interrupt
+ # during the analysis phase below can resume without redoing the expensive
+ # index. Skipped when we rehydrated (already persisted) — best-effort.
+ if resume_controller is not None and not skip_index:
+ await resume_controller.checkpoint_index(
+ parsed_files=parsed_files,
+ graph_builder=graph_builder,
+ git_metadata_list=git_metadata_list,
+ git_summary=git_summary,
+ external_systems=external_systems,
+ )
+
# Emit rich insight summary for the ingestion phase
if progress:
_g = graph_builder.graph()
@@ -358,26 +416,60 @@ async def run_pipeline(
if progress:
progress.on_message("info", "Phase 2: Analysis")
- dead_code_report = await _run_dead_code_analysis(graph_builder, git_meta_map, progress=progress)
-
- health_report = await _run_health_analysis(
- graph_builder, git_meta_map, parsed_files, repo_path=repo_path, progress=progress
+ # Resume fast-path: when a prior run already completed (and persisted) the
+ # ANALYSIS phase, skip recomputing dead code / health / decisions — the
+ # last is the costly one (LLM-backed, minutes on large repos). We rehydrate
+ # only the thin views generation reads; the persisted rows stay
+ # authoritative and are never re-written from these. ``health_report`` is
+ # not a generation input, so it stays None on this path (its persisted rows
+ # are untouched). Falls back to a full recompute if rehydration errors.
+ skip_analysis = bool(
+ resume_controller and await resume_controller.can_skip(ResumePhase.ANALYSIS)
)
+ dead_code_report = None
+ health_report = None
+ decision_report = None
+ # Reports actually fed to generation + KG — rehydrated on the skip path,
+ # the freshly computed ones otherwise.
+ gen_dead_code_report = None
+ gen_decision_report = None
+ if skip_analysis:
+ try:
+ (
+ gen_dead_code_report,
+ gen_decision_report,
+ ) = await resume_controller.rehydrate_analysis()
+ if progress:
+ progress.on_message("info", " ↳ Resuming — reusing persisted analysis")
+ except Exception as exc:
+ logger.warning("resume_rehydrate_analysis_failed_recomputing", error=str(exc))
+ skip_analysis = False
+
+ if not skip_analysis:
+ dead_code_report = await _run_dead_code_analysis(
+ graph_builder, git_meta_map, progress=progress
+ )
- # Drop the in-memory-only ``BlameIndex`` now that the health biomarkers
- # have consumed it — before it can leak into ``PipelineResult`` and the
- # downstream JSON artifact writers / DB persistence. ``git_meta_map`` shares
- # these dict objects, so this cleans both views.
- drop_transient_git_signals(git_metadata_list)
+ health_report = await _run_health_analysis(
+ graph_builder, git_meta_map, parsed_files, repo_path=repo_path, progress=progress
+ )
- decision_report = await _run_decision_extraction(
- repo_path,
- llm_client=llm_client,
- graph_builder=graph_builder,
- git_meta_map=git_meta_map,
- parsed_files=parsed_files,
- progress=progress,
- )
+ # Drop the in-memory-only ``BlameIndex`` now that the health biomarkers
+ # have consumed it — before it can leak into ``PipelineResult`` and the
+ # downstream JSON artifact writers / DB persistence. ``git_meta_map``
+ # shares these dict objects, so this cleans both views.
+ drop_transient_git_signals(git_metadata_list)
+
+ decision_report = await _run_decision_extraction(
+ repo_path,
+ llm_client=llm_client,
+ graph_builder=graph_builder,
+ git_meta_map=git_meta_map,
+ parsed_files=parsed_files,
+ progress=progress,
+ )
+ gen_dead_code_report = dead_code_report
+ gen_decision_report = decision_report
# ---- Knowledge Graph skeleton (deterministic, no LLM) ----------------
knowledge_graph_result = None
@@ -421,7 +513,7 @@ async def run_pipeline(
tech_stack=tech_stack_dicts,
external_systems=external_systems,
git_meta_map=git_meta_map,
- dead_code_report=dead_code_report,
+ dead_code_report=gen_dead_code_report,
repo_path=repo_path,
)
knowledge_graph_result.fingerprint = new_fingerprint
@@ -436,6 +528,19 @@ async def run_pipeline(
except (ValueError, KeyError, OSError, RuntimeError) as kg_err:
logger.error("kg_skeleton_building_failed", error=str(kg_err), exc_info=True)
+ # ---- Checkpoint: ANALYSIS ----------------------------------------------
+ # Persist dead code + health + decisions now that the analysis phase is
+ # complete, so an interrupt during the long generation phase below can
+ # resume past analysis instead of recomputing it. Skipped when we already
+ # rehydrated analysis (it's by definition persisted) — best-effort.
+ if resume_controller is not None and not skip_analysis:
+ await resume_controller.checkpoint_analysis(
+ dead_code_report=dead_code_report,
+ health_report=health_report,
+ decision_report=decision_report,
+ git_metadata_list=git_metadata_list,
+ )
+
# ---- Phase 3: Generation (optional) ------------------------------------
generated_pages: list[Any] | None = None
if generate_docs and llm_client is not None:
@@ -481,8 +586,8 @@ async def run_pipeline(
progress=progress,
resume=resume,
generation_config=resolved_generation_config,
- dead_code_report=dead_code_report,
- decision_report=decision_report,
+ dead_code_report=gen_dead_code_report,
+ decision_report=gen_decision_report,
external_systems=external_systems,
on_page_ready=on_page_ready,
)
@@ -566,6 +671,9 @@ async def run_pipeline(
],
external_systems=external_systems,
vector_store=vector_store,
+ index_persisted_incrementally=(
+ resume_controller.index_persisted if resume_controller is not None else False
+ ),
)
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index 80401ed73..454dac6b8 100644
--- a/packages/core/src/repowise/core/pipeline/persist.py
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -108,54 +108,24 @@ async def persist_graph_nodes(
logger.warning("graph_metrics_materialize_skipped", error=str(exc))
-async def persist_pipeline_result(
- result: Any,
- session: Any,
- repo_id: str,
-) -> None:
- """Persist all outputs from a :class:`PipelineResult` into the database.
-
- Parameters
- ----------
- result:
- A ``PipelineResult`` from ``run_pipeline()``.
- session:
- An active SQLAlchemy ``AsyncSession`` (caller manages commit/rollback).
- repo_id:
- The repository ID to associate all records with.
+async def persist_ingestion(result: Any, session: Any, repo_id: str) -> int:
+ """Persist ingestion-phase outputs: graph nodes/edges, external systems,
+ symbols, and the per-file security scan.
- Note
- ----
- FTS indexing is intentionally excluded here — callers must do it after
- this session closes to avoid SQLite write-lock conflicts.
+ Every write here is an idempotent UPSERT keyed by ``(repo_id, …)``, so
+ this is safe to call incrementally (per phase) and to re-run on resume.
- This function mutates ``sym.file_path`` on parsed-file symbols that
- lack one. Callers should treat *result* as consumed after this call.
+ Returns the number of symbols written (for the summary log). Mutates
+ ``sym.file_path`` on symbols that lack one — callers should treat the
+ parsed-file symbols as consumed after this call.
"""
from repowise.core.persistence import (
batch_upsert_graph_edges,
batch_upsert_symbols,
bulk_upsert_external_systems,
link_graph_nodes_to_external_systems,
- upsert_page_from_generated,
- )
- from repowise.core.persistence.crud import (
- bulk_upsert_decisions,
- recompute_decision_staleness,
- save_dead_code_findings,
- save_health_findings,
- save_health_metrics,
- save_health_snapshot,
- upsert_git_commits_bulk,
- upsert_git_function_blame_bulk,
- upsert_git_metadata_bulk,
)
- # ---- Pages (if generated) -----------------------------------------------
- if result.generated_pages:
- for page in result.generated_pages:
- await upsert_page_from_generated(session, page, repo_id)
-
# ---- Graph nodes ---------------------------------------------------------
ep_scores: dict[str, float] = {}
if result.execution_flow_report and getattr(result.execution_flow_report, "flows", None):
@@ -208,10 +178,9 @@ async def persist_pipeline_result(
await batch_upsert_symbols(session, repo_id, all_symbols)
# ---- Security scan -------------------------------------------------------
- # Choice: persist.py (rather than orchestrator.py) because there is already
- # a clear per-file loop over parsed_files here, and the instructions ask for
- # a minimal, non-invasive addition. The orchestrator parse stage is owned
- # by another agent and must not be touched.
+ # There is already a clear per-file loop over parsed_files here, so the
+ # scan rides alongside symbol persistence. Best-effort — never breaks
+ # the rest of the phase.
try:
from repowise.core.analysis.security_scan import SecurityScanner
@@ -224,15 +193,47 @@ async def persist_pipeline_result(
except Exception as _sec_err:
logger.warning("security_scan_skipped", error=str(_sec_err))
- # ---- Git metadata --------------------------------------------------------
+ return len(all_symbols)
+
+
+async def persist_git(result: Any, session: Any, repo_id: str) -> None:
+ """Persist git-phase outputs: per-file metadata and per-commit rows.
+
+ Both writes are idempotent UPSERTs keyed by ``(repo_id, file_path)`` /
+ ``(repo_id, sha)`` — safe to call incrementally and on resume.
+ """
+ from repowise.core.persistence.crud import (
+ upsert_git_commits_bulk,
+ upsert_git_metadata_bulk,
+ )
+
if result.git_metadata_list:
await upsert_git_metadata_bulk(session, repo_id, result.git_metadata_list)
- # ---- Per-commit rows + change-risk (ride on the git summary) -------------
+ # Per-commit rows + change-risk ride on the git summary.
commit_rows = getattr(getattr(result, "git_summary", None), "commit_rows", None)
if commit_rows:
await upsert_git_commits_bulk(session, repo_id, commit_rows)
+
+async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
+ """Persist analysis-phase outputs: dead code, health, decisions, governance.
+
+ Dead-code and health writes are repo-wide DELETE-THEN-INSERT (so they
+ converge on re-run but don't support partial-within-phase resume);
+ decisions/governance are idempotent. Intended to run once the analysis
+ phase has fully completed.
+ """
+ from repowise.core.persistence.crud import (
+ bulk_upsert_decisions,
+ recompute_decision_staleness,
+ save_dead_code_findings,
+ save_health_findings,
+ save_health_metrics,
+ save_health_snapshot,
+ upsert_git_function_blame_bulk,
+ )
+
# ---- Dead code findings --------------------------------------------------
if result.dead_code_report and result.dead_code_report.findings:
await save_dead_code_findings(session, repo_id, result.dead_code_report.findings)
@@ -356,7 +357,21 @@ async def persist_pipeline_result(
except Exception as _gov_err:
logger.debug("governance_findings_skipped", error=str(_gov_err))
- # ---- Knowledge graph layers & tour steps -----------------------------------
+
+async def persist_generation(result: Any, session: Any, repo_id: str) -> None:
+ """Persist generation-phase outputs: wiki pages and knowledge-graph layers.
+
+ Pages upsert per ``page_id`` (archiving prior versions); KG layers/tour
+ are full-replace. Both safe to call incrementally / on resume.
+ """
+ from repowise.core.persistence import upsert_page_from_generated
+
+ # ---- Pages (if generated) -----------------------------------------------
+ if result.generated_pages:
+ for page in result.generated_pages:
+ await upsert_page_from_generated(session, page, repo_id)
+
+ # ---- Knowledge graph layers & tour steps --------------------------------
kg = getattr(result, "knowledge_graph_result", None)
if kg is not None:
from repowise.core.persistence.crud import upsert_kg_layers, upsert_kg_tour_steps
@@ -366,11 +381,47 @@ async def persist_pipeline_result(
if hasattr(kg, "tour") and kg.tour:
await upsert_kg_tour_steps(session, repo_id, kg.tour)
+
+async def persist_pipeline_result(
+ result: Any,
+ session: Any,
+ repo_id: str,
+) -> None:
+ """Persist all outputs from a :class:`PipelineResult` into the database.
+
+ Thin composition of the four phase-scoped persisters
+ (:func:`persist_ingestion`, :func:`persist_git`, :func:`persist_analysis`,
+ :func:`persist_generation`) in dependency order. The same functions are
+ reused by the incremental-persistence path so a resumed run can persist
+ one phase at a time.
+
+ Parameters
+ ----------
+ result:
+ A ``PipelineResult`` from ``run_pipeline()``.
+ session:
+ An active SQLAlchemy ``AsyncSession`` (caller manages commit/rollback).
+ repo_id:
+ The repository ID to associate all records with.
+
+ Note
+ ----
+ FTS indexing is intentionally excluded here — callers must do it after
+ this session closes to avoid SQLite write-lock conflicts.
+
+ This function mutates ``sym.file_path`` on parsed-file symbols that
+ lack one. Callers should treat *result* as consumed after this call.
+ """
+ symbol_count = await persist_ingestion(result, session, repo_id)
+ await persist_git(result, session, repo_id)
+ await persist_analysis(result, session, repo_id)
+ await persist_generation(result, session, repo_id)
+
logger.info(
"pipeline_result_persisted",
repo_id=repo_id,
pages=len(result.generated_pages) if result.generated_pages else 0,
graph_nodes=result.graph_builder.graph().number_of_nodes(),
- symbols=len(all_symbols),
+ symbols=symbol_count,
git_files=len(result.git_metadata_list),
)
diff --git a/packages/core/src/repowise/core/pipeline/phases/generation.py b/packages/core/src/repowise/core/pipeline/phases/generation.py
index a6caf5a12..4d35b3563 100644
--- a/packages/core/src/repowise/core/pipeline/phases/generation.py
+++ b/packages/core/src/repowise/core/pipeline/phases/generation.py
@@ -39,10 +39,16 @@ async def run_generation(
decision_report: Any | None = None,
external_systems: list[dict] | None = None,
on_page_ready: Any | None = None,
+ prior_pages: dict[str, Any] | None = None,
) -> list[Any]:
"""Run LLM-powered page generation.
Returns a list of ``GeneratedPage`` objects.
+
+ ``prior_pages`` (a ``page_id → PriorPage`` map loaded from a previous run)
+ lets the generator skip the LLM call for any page whose freshly rendered
+ prompt still hashes to the persisted value under the same model — the same
+ cross-run reuse ``repowise update`` relies on. Defaults to empty.
"""
from repowise.core.generation import (
ContextAssembler,
@@ -111,6 +117,7 @@ async def run_generation(
config,
vector_store=vector_store,
language=config.language,
+ prior_pages=prior_pages or {},
)
generated_pages = await generator.generate_all(
diff --git a/packages/core/src/repowise/core/pipeline/phases/ingestion.py b/packages/core/src/repowise/core/pipeline/phases/ingestion.py
index 16d422115..693acf598 100644
--- a/packages/core/src/repowise/core/pipeline/phases/ingestion.py
+++ b/packages/core/src/repowise/core/pipeline/phases/ingestion.py
@@ -362,3 +362,131 @@ async def _run_ingestion(
progress.on_message("info", f" Languages: {lang_str}")
return parsed_files, file_infos, repo_structure, source_map, graph_builder, stats, tech_items
+
+
+async def reparse_for_resume(
+ repo_path: Path,
+ *,
+ exclude_patterns: list[str] | None,
+ include_submodules: bool = False,
+ include_nested_repos: bool = False,
+ skip_tests: bool,
+ skip_infra: bool,
+ progress: ProgressCallback | None,
+) -> tuple[list[Any], list[Any], Any, dict[str, bytes], list[Any]]:
+ """Parse-only ingestion for a resumed run: traverse + parse, **no graph
+ build or centrality**.
+
+ A resumed run rehydrates the graph (and its expensive centrality metrics)
+ and the git metadata from the database, so the only thing it must redo on
+ disk is parsing source into ``ParsedFile`` objects (those aren't persisted
+ in reconstructable form, and the analysis/generation phases need them).
+ Skipping the graph build + the four centrality kernels is exactly the
+ minutes-long work resume exists to avoid.
+
+ Returns ``(parsed_files, file_infos, repo_structure, source_map,
+ tech_items)`` — mirrors the prefix of :func:`_run_ingestion` minus the
+ graph builder and traversal stats.
+ """
+ from repowise.core.ingestion import ASTParser, FileTraverser
+
+ traverser = FileTraverser(
+ repo_path,
+ extra_exclude_patterns=exclude_patterns or None,
+ include_submodules=include_submodules,
+ include_nested_repos=include_nested_repos,
+ )
+
+ all_paths = list(traverser._walk())
+ if progress:
+ progress.on_phase_start("traverse", None)
+
+ file_infos: list[Any] = []
+ io_pool = ThreadPoolExecutor(max_workers=8)
+ try:
+ aws = [
+ asyncio.wrap_future(io_pool.submit(traverser._build_file_info, p)) for p in all_paths
+ ]
+ for coro in asyncio.as_completed(aws):
+ try:
+ result = await coro
+ except Exception:
+ result = None
+ if result is not None:
+ file_infos.append(result)
+ if progress:
+ progress.on_item_done("traverse")
+ finally:
+ await asyncio.to_thread(io_pool.shutdown, wait=True)
+
+ repo_structure = traverser.get_repo_structure(file_infos)
+ _phase_done(progress, "traverse")
+
+ if skip_tests:
+ file_infos = [fi for fi in file_infos if not fi.is_test]
+ if skip_infra:
+ file_infos = [
+ fi
+ for fi in file_infos
+ if fi.language not in ("dockerfile", "makefile", "terraform", "shell")
+ ]
+
+ if progress:
+ progress.on_phase_start("parse", len(file_infos))
+
+ fi_and_bytes: list[tuple] = []
+ for fi in file_infos:
+ try:
+ source = Path(fi.abs_path).read_bytes()
+ fi_and_bytes.append((fi, source))
+ except Exception:
+ if progress:
+ progress.on_item_done("parse")
+
+ parsed_files: list[Any] = []
+ source_map: dict[str, bytes] = {}
+ loop = asyncio.get_running_loop()
+ workers = max(1, os.cpu_count() or 4)
+ parse_results: list[Any] = []
+
+ try:
+ with ProcessPoolExecutor(max_workers=workers) as pool:
+ tasks = [loop.run_in_executor(pool, _parse_one, item) for item in fi_and_bytes]
+ if progress is not None:
+ _tick = lambda _fut: progress.on_item_done("parse") # noqa: E731
+ for fut in tasks:
+ fut.add_done_callback(_tick)
+ parse_results = await asyncio.gather(*tasks, return_exceptions=True)
+ except Exception as pool_exc:
+ logger.warning("resume_reparse_pool_failed_falling_back", error=str(pool_exc))
+ _fallback_parser = ASTParser()
+ for i, (fi, source) in enumerate(fi_and_bytes):
+ try:
+ parse_results.append(_fallback_parser.parse_file(fi, source))
+ except Exception as exc:
+ parse_results.append((fi.abs_path, str(exc)))
+ if progress:
+ progress.on_item_done("parse")
+ if i % 50 == 49:
+ await asyncio.sleep(0)
+
+ for idx, result in enumerate(parse_results):
+ fi, source = fi_and_bytes[idx]
+ if isinstance(result, tuple) and len(result) == 2 and isinstance(result[1], str):
+ logger.debug("parse_error_in_worker", path=result[0], error=result[1])
+ elif isinstance(result, Exception):
+ logger.debug("parse_exception_in_worker", path=fi.abs_path, error=str(result))
+ else:
+ parsed_files.append(result)
+ source_map[fi.path] = source
+ _phase_done(progress, "parse")
+
+ tech_items: list = []
+ try:
+ from repowise.core.generation.editor_files.tech_stack import detect_tech_stack
+
+ tech_items = detect_tech_stack(repo_path)
+ except Exception:
+ pass
+
+ return parsed_files, file_infos, repo_structure, source_map, tech_items
diff --git a/packages/core/src/repowise/core/pipeline/resume/__init__.py b/packages/core/src/repowise/core/pipeline/resume/__init__.py
new file mode 100644
index 000000000..7e580e173
--- /dev/null
+++ b/packages/core/src/repowise/core/pipeline/resume/__init__.py
@@ -0,0 +1,28 @@
+"""Crash-resume for the indexing pipeline.
+
+Makes ``repowise init --resume`` honor the "safe to Ctrl-C" promise: a run
+interrupted partway through skips the phases a prior run already finished and
+rehydrates their outputs from the database instead of recomputing them.
+
+Modules
+-------
+``phases`` Phase identifiers + ordering (the resume vocabulary).
+``ledger`` Durable "which phases completed" record over the SqlJobStore.
+``rehydrate`` Reconstruct phase *inputs* (graph, git metadata) from the DB.
+``controller`` The single object the orchestrator consults at phase
+ boundaries — decides skip-vs-run, persists on completion,
+ and serves rehydrated inputs. A ``None`` controller means
+ "no resume" and the pipeline behaves exactly as before.
+"""
+
+from .controller import ResumeController
+from .ledger import ResumeLedger
+from .phases import ResumePhase
+from .rehydrate import rehydrate_git_meta_map
+
+__all__ = [
+ "ResumeController",
+ "ResumeLedger",
+ "ResumePhase",
+ "rehydrate_git_meta_map",
+]
diff --git a/packages/core/src/repowise/core/pipeline/resume/controller.py b/packages/core/src/repowise/core/pipeline/resume/controller.py
new file mode 100644
index 000000000..76799bee7
--- /dev/null
+++ b/packages/core/src/repowise/core/pipeline/resume/controller.py
@@ -0,0 +1,211 @@
+"""The resume coordinator the orchestrator consults at phase boundaries.
+
+Responsibilities, all behind one object so the orchestrator stays
+DB-agnostic:
+
+- decide whether a phase may be **skipped** on a resumed run
+ (:meth:`can_skip`),
+- **persist** a phase's outputs the moment it completes and record the phase
+ in the ledger (:meth:`checkpoint_index`),
+- serve **rehydrated** inputs for skipped phases
+ (:meth:`rehydrate_index`).
+
+A ``None`` controller (the default everywhere) means resume is disabled and
+the pipeline runs exactly as before — no new DB work, no behaviour change.
+Construction requires a repo_id that already exists in the database, which
+is why the CLI creates the repository row *before* starting the pipeline
+(this also fixes the ``pipeline_jobs.repository_id`` FK that the old
+``str(repo_path)`` wiring violated — the id is now the real ``Repository.id``).
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import Any
+
+import structlog
+
+from ..persist import persist_analysis, persist_git, persist_ingestion
+from .ledger import ResumeLedger
+from .phases import RESUME_PHASE_ORDER, ResumePhase
+from .rehydrate import (
+ rehydrate_dead_code_report,
+ rehydrate_decision_report,
+ rehydrate_git_meta_map,
+ rehydrate_graph_builder,
+)
+
+logger = structlog.get_logger(__name__)
+
+
+class ResumeController:
+ """Coordinates skip/persist/rehydrate for one pipeline run."""
+
+ def __init__(
+ self,
+ session_factory: Any,
+ repo_id: str,
+ *,
+ resume: bool,
+ ) -> None:
+ self._sf = session_factory
+ self._repo_id = repo_id
+ self._resume = resume
+ self._ledger = ResumeLedger(session_factory, repo_id)
+ self._completed: set[ResumePhase] | None = None
+ # True once the INDEX phase is provably on disk — either freshly
+ # checkpointed this run or rehydrated from a prior run. The caller
+ # keys its "skip the index in the final persist" decision on this, so
+ # it must NEVER be True unless the index really was persisted (a
+ # best-effort checkpoint failure leaves it False → full persist).
+ self._index_persisted = False
+
+ @property
+ def repo_id(self) -> str:
+ return self._repo_id
+
+ @property
+ def index_persisted(self) -> bool:
+ return self._index_persisted
+
+ # -- skip decisions --------------------------------------------------------
+
+ async def _completed_phases(self) -> set[ResumePhase]:
+ if self._completed is None:
+ self._completed = await self._ledger.completed_phases() if self._resume else set()
+ return self._completed
+
+ async def can_skip(self, phase: ResumePhase) -> bool:
+ """True iff *phase* — and every phase before it — completed previously.
+
+ The prefix requirement means we never skip a phase whose inputs an
+ earlier, unfinished phase would have produced.
+ """
+ if not self._resume:
+ return False
+ done = await self._completed_phases()
+ cutoff = RESUME_PHASE_ORDER.index(phase)
+ return all(p in done for p in RESUME_PHASE_ORDER[: cutoff + 1])
+
+ # -- rehydration -----------------------------------------------------------
+
+ async def rehydrate_index(self, repo_path: Any) -> tuple[Any, dict[str, dict[str, Any]]]:
+ """Rebuild ``(graph_builder, git_meta_map)`` from persisted rows.
+
+ The graph comes back finalized (metrics served from SQL, no centrality
+ kernel re-run); git metadata carries every durable signal. The caller
+ still re-parses source files to obtain ``parsed_files`` — those aren't
+ persisted in reconstructable form, but re-parsing is far cheaper than
+ the git history + centrality work this skips.
+ """
+ from repowise.core.persistence import get_session
+
+ async with get_session(self._sf) as session:
+ graph_builder = await rehydrate_graph_builder(session, self._repo_id, repo_path)
+ git_meta_map = await rehydrate_git_meta_map(session, self._repo_id)
+ # The index is, by definition, already persisted (we just read it).
+ self._index_persisted = True
+ return graph_builder, git_meta_map
+
+ async def rehydrate_analysis(self) -> tuple[Any, Any]:
+ """Rebuild ``(dead_code_report, decision_report)`` from persisted rows.
+
+ Used **only** as generation input on a resumed run whose ANALYSIS phase
+ already completed — so the resume skips re-running dead-code detection,
+ health scoring and (the costly) decision extraction. The returned views
+ are deliberately thin (just what the page generator reads) and must
+ never be written back: the persisted analysis rows are authoritative.
+ Raises on a DB error so the caller can fall back to recomputing.
+ """
+ from repowise.core.persistence import get_session
+
+ async with get_session(self._sf) as session:
+ dead_code_report = await rehydrate_dead_code_report(session, self._repo_id)
+ decision_report = await rehydrate_decision_report(session, self._repo_id)
+ return dead_code_report, decision_report
+
+ # -- checkpoints -----------------------------------------------------------
+
+ async def checkpoint_index(
+ self,
+ *,
+ parsed_files: list[Any],
+ graph_builder: Any,
+ git_metadata_list: list[dict],
+ git_summary: Any | None = None,
+ external_systems: list[dict] | None = None,
+ execution_flow_report: Any | None = None,
+ ) -> None:
+ """Persist the INDEX phase (graph + symbols + git) and record it.
+
+ Idempotent UPSERTs throughout, so a later full persist that re-writes
+ the same rows (e.g. graph nodes with entry-point scores once execution
+ flow is known) is harmless. Best-effort: a persistence hiccup is logged
+ and swallowed so it can never abort the in-memory run.
+ """
+ from repowise.core.persistence import get_session
+
+ view = SimpleNamespace(
+ parsed_files=parsed_files,
+ graph_builder=graph_builder,
+ git_metadata_list=git_metadata_list,
+ git_summary=git_summary,
+ external_systems=external_systems or [],
+ execution_flow_report=execution_flow_report,
+ )
+ await self._ledger.mark_started(ResumePhase.INDEX)
+ try:
+ async with get_session(self._sf) as session:
+ await persist_ingestion(view, session, self._repo_id)
+ await persist_git(view, session, self._repo_id)
+ except Exception as exc:
+ logger.warning("resume_checkpoint_index_failed", error=str(exc))
+ return
+ self._index_persisted = True
+ await self._ledger.mark_completed(ResumePhase.INDEX)
+ logger.info("resume_checkpoint_index", repo_id=self._repo_id)
+
+ async def checkpoint_analysis(
+ self,
+ *,
+ dead_code_report: Any | None,
+ health_report: Any | None,
+ decision_report: Any | None,
+ git_metadata_list: list[dict],
+ vector_store: Any | None = None,
+ ) -> None:
+ """Persist the ANALYSIS phase (dead code + health + decisions) and record it.
+
+ Mirrors :meth:`checkpoint_index`: writing these rows the moment the
+ analysis phase finishes — *before* the long generation phase — is what
+ lets a generation interrupt resume past analysis instead of recomputing
+ it (decision extraction in particular can run for minutes). Best-effort:
+ a persistence hiccup is logged and swallowed, leaving ANALYSIS unmarked
+ so the resumed run simply recomputes it. ``generated_pages`` is empty at
+ this point, so harvested-decision folding still happens at the final
+ end-of-run persist.
+ """
+ from repowise.core.persistence import get_session
+
+ view = SimpleNamespace(
+ dead_code_report=dead_code_report,
+ health_report=health_report,
+ decision_report=decision_report,
+ git_metadata_list=git_metadata_list,
+ generated_pages=None,
+ vector_store=vector_store,
+ )
+ await self._ledger.mark_started(ResumePhase.ANALYSIS)
+ try:
+ async with get_session(self._sf) as session:
+ await persist_analysis(view, session, self._repo_id)
+ except Exception as exc:
+ logger.warning("resume_checkpoint_analysis_failed", error=str(exc))
+ return
+ await self._ledger.mark_completed(ResumePhase.ANALYSIS)
+ logger.info("resume_checkpoint_analysis", repo_id=self._repo_id)
+
+ async def mark_phase_complete(self, phase: ResumePhase) -> None:
+ """Record *phase* as completed (analysis / generation persisted by the
+ normal end-of-run persist; this just stamps the ledger)."""
+ await self._ledger.mark_completed(phase)
diff --git a/packages/core/src/repowise/core/pipeline/resume/ledger.py b/packages/core/src/repowise/core/pipeline/resume/ledger.py
new file mode 100644
index 000000000..a8d6c6630
--- /dev/null
+++ b/packages/core/src/repowise/core/pipeline/resume/ledger.py
@@ -0,0 +1,90 @@
+"""Durable record of which pipeline phases have completed for a repo.
+
+Async wrapper over the ``pipeline_jobs`` table (via ``SqlJobStore``). A phase
+is "done" iff a COMPLETED job row exists for it. On crash, the in-flight
+phase's job is left in RUNNING — never COMPLETED — so a re-run re-does it.
+
+Each method opens and **commits** its own short-lived session, because the
+whole point is cross-process durability: a phase marked completed must
+survive the process being killed. Every method is best-effort — a ledger
+write must never crash the pipeline, so failures are logged and swallowed
+(worst case is redoing work, never losing it).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import structlog
+
+from .phases import ResumePhase
+
+logger = structlog.get_logger(__name__)
+
+
+def _store(session: Any) -> Any:
+ from repowise.core.persistence.stores.sql_job_store import SqlJobStore
+
+ return SqlJobStore(session)
+
+
+class ResumeLedger:
+ """Records phase lifecycle for one repository, committing each write."""
+
+ def __init__(self, session_factory: Any, repo_id: str) -> None:
+ self._sf = session_factory
+ self._repo_id = repo_id
+ # phase value -> job id, so mark_completed can transition the row we
+ # opened in mark_started (the id survives across sessions once committed).
+ self._job_ids: dict[str, str] = {}
+
+ async def completed_phases(self) -> set[ResumePhase]:
+ """Return the set of phases already COMPLETED for this repo."""
+ from repowise.core.persistence import get_session
+ from repowise.core.persistence._interfaces.job_store import JobState
+
+ try:
+ async with get_session(self._sf) as session:
+ jobs = await _store(session).list_jobs(repository_id=self._repo_id)
+ except Exception as exc:
+ logger.debug("resume_ledger_read_failed", error=str(exc))
+ return set()
+ done: set[ResumePhase] = set()
+ for j in jobs:
+ if j.state != JobState.COMPLETED:
+ continue
+ try:
+ done.add(ResumePhase(j.phase))
+ except ValueError:
+ continue # an unrelated job phase — ignore
+ return done
+
+ async def mark_started(self, phase: ResumePhase) -> None:
+ from repowise.core.persistence import get_session
+ from repowise.core.persistence._interfaces.job_store import JobState
+
+ try:
+ async with get_session(self._sf) as session:
+ store = _store(session)
+ job = await store.create_job(repository_id=self._repo_id, phase=str(phase))
+ await store.update_state(job.id, JobState.RUNNING)
+ self._job_ids[str(phase)] = job.id
+ except Exception as exc:
+ logger.debug("resume_ledger_start_failed", phase=str(phase), error=str(exc))
+
+ async def mark_completed(self, phase: ResumePhase) -> None:
+ from repowise.core.persistence import get_session
+ from repowise.core.persistence._interfaces.job_store import JobState
+
+ try:
+ async with get_session(self._sf) as session:
+ store = _store(session)
+ job_id = self._job_ids.get(str(phase))
+ if job_id is None:
+ # No open job (e.g. mark_started failed) — open one so the
+ # COMPLETED state still lands.
+ job = await store.create_job(repository_id=self._repo_id, phase=str(phase))
+ job_id = job.id
+ await store.update_state(job_id, JobState.COMPLETED)
+ except Exception as exc:
+ logger.debug("resume_ledger_complete_failed", phase=str(phase), error=str(exc))
diff --git a/packages/core/src/repowise/core/pipeline/resume/phases.py b/packages/core/src/repowise/core/pipeline/resume/phases.py
new file mode 100644
index 000000000..89f487465
--- /dev/null
+++ b/packages/core/src/repowise/core/pipeline/resume/phases.py
@@ -0,0 +1,36 @@
+"""Resume phase vocabulary.
+
+These are *coarse* checkpoint boundaries chosen for resume value, distinct
+from the fine-grained progress-bar phases the orchestrator emits. Each maps
+to one persist step and one rehydration recipe:
+
+- ``INDEX`` parse + graph build (incl. centrality) + git history. The
+ expensive part of a first run (the reporter's log: ~18 min
+ git + ~20 min centrality). Persisted as graph nodes/edges/
+ metrics + symbols + git metadata/commits.
+- ``ANALYSIS`` dead code + health + decisions + governance.
+- ``GENERATION`` LLM wiki pages + knowledge-graph enrichment.
+
+INDEX is treated as a single unit because its two halves (ingestion and git)
+run concurrently and analysis needs both; resuming "half an index" buys
+nothing over rebuilding it.
+"""
+
+from __future__ import annotations
+
+import enum
+
+
+class ResumePhase(enum.StrEnum):
+ INDEX = "index"
+ ANALYSIS = "analysis"
+ GENERATION = "generation"
+
+
+# Persisted order — a phase may only be skipped on resume if it and every
+# phase before it completed in a prior run.
+RESUME_PHASE_ORDER: tuple[ResumePhase, ...] = (
+ ResumePhase.INDEX,
+ ResumePhase.ANALYSIS,
+ ResumePhase.GENERATION,
+)
diff --git a/packages/core/src/repowise/core/pipeline/resume/rehydrate.py b/packages/core/src/repowise/core/pipeline/resume/rehydrate.py
new file mode 100644
index 000000000..cd3194873
--- /dev/null
+++ b/packages/core/src/repowise/core/pipeline/resume/rehydrate.py
@@ -0,0 +1,134 @@
+"""Reconstruct phase *inputs* from persisted DB rows for a resumed run.
+
+The graph is rehydrated by the existing :func:`rehydrate_graph_builder`
+(re-exported here for a single resume import surface). This module adds the
+git side: turning persisted ``git_metadata`` rows back into the
+``git_meta_map`` dict that the analysis phases consume.
+
+Caveat — the transient per-line ``BlameIndex`` is intentionally never
+persisted (see ``phases/git.py: drop_transient_git_signals``), so a
+rehydrated ``git_meta_map`` carries every durable signal but no
+``blame_index``. Blame-dependent biomarkers treat its absence as "no
+signal" — which is exactly the case for FAST/ESSENTIAL-tier runs that
+never computed blame in the first place.
+"""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+from typing import Any
+
+import structlog
+
+from ..upgrade import rehydrate_graph_builder
+
+logger = structlog.get_logger(__name__)
+
+__all__ = [
+ "rehydrate_dead_code_report",
+ "rehydrate_decision_report",
+ "rehydrate_git_meta_map",
+ "rehydrate_graph_builder",
+]
+
+
+def _git_metadata_to_dict(row: Any) -> dict[str, Any]:
+ """Project a ``GitMetadata`` ORM row to the dict shape analysis expects.
+
+ Uses column introspection so every persisted signal is carried faithfully
+ and the keys match the column names the fresh git indexer writes (the
+ upsert path sets attributes by matching dict keys to columns). JSON
+ columns stay as their stored strings — consumers (e.g. the duplication
+ co-change scorer) ``json.loads`` them on demand.
+ """
+ out: dict[str, Any] = {}
+ for col in row.__table__.columns:
+ name = col.name
+ if name in ("id", "repository_id"):
+ continue
+ out[name] = getattr(row, name)
+ return out
+
+
+async def rehydrate_git_meta_map(session: Any, repo_id: str) -> dict[str, dict[str, Any]]:
+ """Rebuild ``{file_path -> git metadata dict}`` from persisted rows.
+
+ Returns an empty dict when nothing was persisted (so a caller can detect
+ "git was never indexed" and fall back to recomputing).
+ """
+ from repowise.core.persistence import get_all_git_metadata
+
+ try:
+ rows = await get_all_git_metadata(session, repo_id)
+ except Exception as exc:
+ logger.debug("rehydrate_git_meta_failed", error=str(exc))
+ return {}
+ return {path: _git_metadata_to_dict(row) for path, row in rows.items()}
+
+
+# ---------------------------------------------------------------------------
+# Analysis reports (generation INPUT only — never re-persisted)
+# ---------------------------------------------------------------------------
+#
+# These thin views carry exactly the fields the page generator reads off a
+# dead-code / decision report (see ``page_generator/helpers.py``:
+# ``build_dead_code_map`` / ``build_decision_maps``) — nothing more. They are
+# deliberately *not* the analysis dataclasses: a resumed run feeds them into
+# generation but must never write them back (the persisted rows are already
+# authoritative), so they skip ``deletable_lines`` / ``by_source`` and the
+# other persist/summary-only fields a faithful round-trip would need.
+
+
+async def rehydrate_dead_code_report(session: Any, repo_id: str) -> Any:
+ """Rebuild a generation-shaped dead-code report from persisted findings.
+
+ Returns a namespace with a ``findings`` list (empty when the completed
+ analysis legitimately found none). Raises on a DB error so the caller can
+ fall back to recomputing.
+ """
+ from repowise.core.persistence.crud import get_dead_code_findings
+
+ rows = await get_dead_code_findings(session, repo_id, status="open")
+ findings = [
+ SimpleNamespace(
+ file_path=r.file_path,
+ symbol_name=r.symbol_name,
+ symbol_kind=r.symbol_kind,
+ kind=r.kind, # stored as the clean string label, e.g. "unused_export"
+ reason=r.reason,
+ confidence=r.confidence,
+ safe_to_delete=r.safe_to_delete,
+ )
+ for r in rows
+ ]
+ return SimpleNamespace(findings=findings)
+
+
+async def rehydrate_decision_report(session: Any, repo_id: str) -> Any:
+ """Rebuild a generation-shaped decision report from persisted records.
+
+ Returns a namespace with a ``decisions`` list (empty when none were
+ recorded). Raises on a DB error so the caller can fall back to recomputing.
+ """
+ from repowise.core.persistence.crud import list_decisions
+
+ rows = await list_decisions(session, repo_id, limit=100_000)
+ decisions = []
+ for r in rows:
+ try:
+ affected = json.loads(r.affected_files_json or "[]")
+ except Exception:
+ affected = []
+ decisions.append(
+ SimpleNamespace(
+ title=r.title,
+ decision=r.decision,
+ rationale=r.rationale,
+ source=r.source,
+ confidence=r.confidence,
+ evidence_file=r.evidence_file,
+ affected_files=affected,
+ )
+ )
+ return SimpleNamespace(decisions=decisions)
diff --git a/tests/integration/test_persistence.py b/tests/integration/test_persistence.py
index 106ed3d5a..6b1270036 100644
--- a/tests/integration/test_persistence.py
+++ b/tests/integration/test_persistence.py
@@ -314,6 +314,53 @@ class TestVersionHistory:
assert isinstance(stored.created_at, datetime)
+ async def test_idempotent_reupsert_is_noop(self, persisted, sf):
+ """Re-upserting identical content/hash/model bumps nothing.
+
+ This is what makes incremental per-page flushing during generation safe
+ to combine with the end-of-run persist of the same pages: the second
+ write neither increments the version nor archives a PageVersion. A real
+ content change still snapshots + bumps as before.
+ """
+ from repowise.core.persistence.crud import upsert_page
+
+ repo_id = persisted["repo_id"]
+ pid = "idempotent-reupsert-probe"
+ fields = dict(
+ page_id=pid,
+ repository_id=repo_id,
+ page_type="file_page",
+ title="Probe",
+ content="stable content",
+ target_path="probe/a.py",
+ source_hash="hash-stable",
+ model_name="model-1",
+ provider_name="provider-1",
+ )
+
+ async with sf() as session:
+ await upsert_page(session, **fields)
+ await session.commit()
+ async with sf() as session:
+ await upsert_page(session, **fields) # identical → no-op
+ await session.commit()
+
+ async with sf() as session:
+ stored = await get_page(session, pid)
+ versions = await get_page_versions(session, pid)
+ assert stored.version == 1
+ assert versions == []
+
+ # A genuine change still archives the prior state and bumps.
+ async with sf() as session:
+ await upsert_page(session, **{**fields, "content": "changed content"})
+ await session.commit()
+ async with sf() as session:
+ stored2 = await get_page(session, pid)
+ versions2 = await get_page_versions(session, pid)
+ assert stored2.version == 2
+ assert len(versions2) == 1
+
# ---------------------------------------------------------------------------
# Full-text search tests
diff --git a/tests/integration/test_pipeline_resume.py b/tests/integration/test_pipeline_resume.py
new file mode 100644
index 000000000..45341c58e
--- /dev/null
+++ b/tests/integration/test_pipeline_resume.py
@@ -0,0 +1,142 @@
+"""Integration test for `repowise init --resume` (issue #341).
+
+Proves the resume contract end-to-end against the real pipeline + sample
+repo: a first run persists the INDEX phase, and a resumed run reuses it —
+rehydrating the graph + git metadata and only re-parsing source, *without*
+re-running git indexing or the full ingestion/graph-build. That is the
+minutes-long work the "safe to Ctrl-C, then --resume" promise exists to skip.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.pool import StaticPool
+
+from repowise.core.persistence import get_session
+from repowise.core.persistence.crud import upsert_repository
+from repowise.core.persistence.database import init_db
+from repowise.core.pipeline import run_pipeline
+from repowise.core.pipeline.modes import OrchestratorMode
+from repowise.core.pipeline.resume import ResumeLedger, ResumePhase
+from repowise.core.pipeline.resume.controller import ResumeController
+
+
+async def sf():
+ engine = create_async_engine(
+ "sqlite+aiosqlite:///:memory:",
+ connect_args={"check_same_thread": False},
+ poolclass=StaticPool,
+ )
+ await init_db(engine)
+ yield async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)
+ await engine.dispose()
+
+
+async def _make_repo(sf, path: Path) -> str:
+ async with get_session(sf) as session:
+ repo = await upsert_repository(session, name="sample", local_path=str(path))
+ return repo.id
+
+
+async def test_first_run_checkpoints_index(sf, sample_repo_path: Path) -> None:
+ repo_id = await _make_repo(sf, sample_repo_path)
+ ctrl = ResumeController(sf, repo_id, resume=False)
+
+ result = await run_pipeline(
+ sample_repo_path,
+ mode=OrchestratorMode.FAST,
+ resume_controller=ctrl,
+ )
+ assert result.parsed_files, "expected a parsed sample repo"
+
+ # INDEX was persisted + recorded so a later run can resume.
+ completed = await ResumeLedger(sf, repo_id).completed_phases()
+ assert ResumePhase.INDEX in completed
+
+
+async def test_resume_skips_index_compute(sf, sample_repo_path: Path, monkeypatch) -> None:
+ repo_id = await _make_repo(sf, sample_repo_path)
+
+ # First run persists the INDEX phase.
+ await run_pipeline(
+ sample_repo_path,
+ mode=OrchestratorMode.FAST,
+ resume_controller=ResumeController(sf, repo_id, resume=False),
+ )
+
+ # On the resumed run, the expensive ingestion + git indexing must NOT run.
+ # Patch both to blow up so the test fails loudly if the skip path regresses.
+ import repowise.core.pipeline.orchestrator as orch
+
+ async def _boom_ingestion(*a, **k): # pragma: no cover - must never be called
+ raise AssertionError("_run_ingestion ran on resume — index was not skipped")
+
+ async def _boom_git(*a, **k): # pragma: no cover - must never be called
+ raise AssertionError("_run_git_indexing ran on resume — index was not skipped")
+
+ monkeypatch.setattr(orch, "_run_ingestion", _boom_ingestion)
+ monkeypatch.setattr(orch, "_run_git_indexing", _boom_git)
+
+ result = await run_pipeline(
+ sample_repo_path,
+ mode=OrchestratorMode.FAST,
+ resume_controller=ResumeController(sf, repo_id, resume=True),
+ )
+
+ # The resumed run still produced a usable index: graph rehydrated from the
+ # DB and source re-parsed.
+ assert result.parsed_files, "resume should re-parse source files"
+ assert result.graph_builder.graph().number_of_nodes() > 0, "graph should be rehydrated"
+
+
+async def test_first_run_checkpoints_analysis(sf, sample_repo_path: Path) -> None:
+ repo_id = await _make_repo(sf, sample_repo_path)
+ await run_pipeline(
+ sample_repo_path,
+ mode=OrchestratorMode.FAST,
+ resume_controller=ResumeController(sf, repo_id, resume=False),
+ )
+
+ # ANALYSIS is checkpointed mid-run (before generation), so a later
+ # generation-interrupted resume can skip recomputing it.
+ completed = await ResumeLedger(sf, repo_id).completed_phases()
+ assert ResumePhase.ANALYSIS in completed
+
+
+async def test_resume_skips_analysis_recompute(sf, sample_repo_path: Path, monkeypatch) -> None:
+ repo_id = await _make_repo(sf, sample_repo_path)
+
+ # First run persists INDEX + ANALYSIS.
+ await run_pipeline(
+ sample_repo_path,
+ mode=OrchestratorMode.FAST,
+ resume_controller=ResumeController(sf, repo_id, resume=False),
+ )
+
+ # On resume, none of the analysis recompute paths may run — patch all three
+ # to fail loudly if the skip regresses.
+ import repowise.core.pipeline.orchestrator as orch
+
+ async def _boom_dead_code(*a, **k): # pragma: no cover - must never be called
+ raise AssertionError("dead-code analysis ran on resume — analysis not skipped")
+
+ async def _boom_health(*a, **k): # pragma: no cover - must never be called
+ raise AssertionError("health analysis ran on resume — analysis not skipped")
+
+ async def _boom_decisions(*a, **k): # pragma: no cover - must never be called
+ raise AssertionError("decision extraction ran on resume — analysis not skipped")
+
+ monkeypatch.setattr(orch, "_run_dead_code_analysis", _boom_dead_code)
+ monkeypatch.setattr(orch, "_run_health_analysis", _boom_health)
+ monkeypatch.setattr(orch, "_run_decision_extraction", _boom_decisions)
+
+ result = await run_pipeline(
+ sample_repo_path,
+ mode=OrchestratorMode.FAST,
+ resume_controller=ResumeController(sf, repo_id, resume=True),
+ )
+ assert result.parsed_files, "resume should still produce a usable index"
diff --git a/tests/unit/cli/test_generation_persist.py b/tests/unit/cli/test_generation_persist.py
new file mode 100644
index 000000000..004f796b2
--- /dev/null
+++ b/tests/unit/cli/test_generation_persist.py
@@ -0,0 +1,138 @@
+"""Unit tests for the resume-friendly generation wrapper.
+
+Covers :func:`run_generation_with_persistence`: pages handed to the
+``on_page_ready`` sink are flushed to the database during the run, and a
+subsequent run loads them back as ``prior_pages`` for reuse.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+import pytest
+
+from repowise.cli.commands._generation_persist import run_generation_with_persistence
+from repowise.core.generation.models import GeneratedPage
+from repowise.core.persistence import (
+ create_engine,
+ create_session_factory,
+ get_session,
+ init_db,
+ upsert_repository,
+)
+
+
+def _page(page_id: str, content: str = "body") -> GeneratedPage:
+ now = datetime.now(UTC).isoformat()
+ return GeneratedPage(
+ page_id=page_id,
+ page_type="file_page",
+ title=f"Title {page_id}",
+ content=content,
+ source_hash=f"hash-{page_id}",
+ model_name="model-1",
+ provider_name="provider-1",
+ input_tokens=10,
+ output_tokens=5,
+ cached_tokens=0,
+ generation_level=2,
+ target_path=f"{page_id}.py",
+ created_at=now,
+ updated_at=now,
+ )
+
+
+def repo_dir(tmp_path, monkeypatch):
+ (tmp_path / ".repowise").mkdir(parents=True, exist_ok=True)
+ db = tmp_path / ".repowise" / "wiki.db"
+ monkeypatch.setenv("REPOWISE_DB_URL", f"sqlite+aiosqlite:///{db.as_posix()}")
+ return tmp_path
+
+
+async def _read_db_page_ids(repo_dir) -> set[str]:
+ import os
+
+ engine = create_engine(os.environ["REPOWISE_DB_URL"])
+ await init_db(engine)
+ sf = create_session_factory(engine)
+ try:
+ async with get_session(sf) as session:
+ repo = await upsert_repository(session, name=repo_dir.name, local_path=str(repo_dir))
+ from repowise.core.persistence.crud import list_pages
+
+ pages = await list_pages(session, repo.id, limit=100)
+ return {p.id for p in pages}
+ finally:
+ await engine.dispose()
+
+
+async def test_pages_flushed_incrementally(repo_dir, monkeypatch):
+ """Every page handed to on_page_ready lands in the DB by the time the
+ wrapper returns — even though the caller never persists explicitly."""
+ emitted = [_page("alpha"), _page("beta")]
+
+ async def fake_run_generation(*, repo_path, on_page_ready=None, prior_pages=None, **_kw):
+ # ``repo_path`` is required (no default) so a wrapper that stops
+ # forwarding it fails here instead of silently passing — the gap that
+ # let the real ``run_generation``'s required ``repo_path`` go unpassed.
+ assert repo_path == repo_dir
+ # Mirror the generator: fire the sink the instant each page is ready.
+ for p in emitted:
+ on_page_ready(p)
+ return emitted
+
+ monkeypatch.setattr(
+ "repowise.core.pipeline.run_generation", fake_run_generation, raising=True
+ )
+
+ pages = await run_generation_with_persistence(
+ repo_path=repo_dir,
+ repo_name=repo_dir.name,
+ )
+
+ assert {p.page_id for p in pages} == {"alpha", "beta"}
+ stored = await _read_db_page_ids(repo_dir)
+ assert stored == {"alpha", "beta"}
+
+
+async def test_prior_pages_loaded_on_second_run(repo_dir, monkeypatch):
+ """A second run sees the first run's pages as prior_pages for reuse."""
+ seen_prior: dict = {}
+
+ async def first_run(*, repo_path, on_page_ready=None, prior_pages=None, **_kw):
+ on_page_ready(_page("gamma"))
+ return [_page("gamma")]
+
+ async def second_run(*, repo_path, on_page_ready=None, prior_pages=None, **_kw):
+ seen_prior.update(prior_pages or {})
+ return []
+
+ monkeypatch.setattr("repowise.core.pipeline.run_generation", first_run, raising=True)
+ await run_generation_with_persistence(repo_path=repo_dir, repo_name=repo_dir.name)
+
+ monkeypatch.setattr("repowise.core.pipeline.run_generation", second_run, raising=True)
+ await run_generation_with_persistence(repo_path=repo_dir, repo_name=repo_dir.name)
+
+ assert "gamma" in seen_prior
+
+
+async def test_sink_failure_never_breaks_generation(repo_dir, monkeypatch):
+ """A page the persister can't store must not abort the run."""
+
+ async def fake_run_generation(*, repo_path, on_page_ready=None, prior_pages=None, **_kw):
+ # A bare object lacks GeneratedPage attributes → upsert raises inside
+ # the consumer, which must swallow it.
+ on_page_ready(object())
+ on_page_ready(_page("delta"))
+ return [_page("delta")]
+
+ monkeypatch.setattr(
+ "repowise.core.pipeline.run_generation", fake_run_generation, raising=True
+ )
+
+ pages = await run_generation_with_persistence(repo_path=repo_dir, repo_name=repo_dir.name)
+ assert {p.page_id for p in pages} == {"delta"}
+ # The valid page still persisted despite the bad one.
+ stored = await _read_db_page_ids(repo_dir)
+ assert "delta" in stored
diff --git a/tests/unit/cli/test_resume_run_mode.py b/tests/unit/cli/test_resume_run_mode.py
new file mode 100644
index 000000000..39ed3885e
--- /dev/null
+++ b/tests/unit/cli/test_resume_run_mode.py
@@ -0,0 +1,56 @@
+"""Resume should continue the prior run's git tier (issue #341).
+
+A fast (ESSENTIAL-tier) index resumed without re-passing ``--mode fast``
+must not silently fall back to STANDARD and redo the expensive FULL git
+indexing the first run deliberately skipped.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from repowise.cli.commands.init_cmd import (
+ _effective_run_mode_for_resume,
+ _git_tier_for_run_mode,
+)
+from repowise.cli.helpers import save_state
+
+
+def test_git_tier_for_run_mode():
+ assert _git_tier_for_run_mode("fast") == "essential"
+ assert _git_tier_for_run_mode("standard") == "full"
+
+
+def test_resume_restores_fast_run_mode(tmp_path: Path):
+ save_state(tmp_path, {"run_mode": "fast", "git_tier": "essential"})
+ # Default CLI run_mode is "standard"; resume should restore "fast".
+ assert _effective_run_mode_for_resume(tmp_path, "standard", resume=True) == "fast"
+
+
+def test_resume_keeps_standard_when_prior_was_standard(tmp_path: Path):
+ save_state(tmp_path, {"run_mode": "standard", "git_tier": "full"})
+ assert _effective_run_mode_for_resume(tmp_path, "standard", resume=True) == "standard"
+
+
+def test_no_resume_is_a_noop(tmp_path: Path):
+ save_state(tmp_path, {"run_mode": "fast"})
+ # Without --resume we honour the invocation's mode, not persisted state.
+ assert _effective_run_mode_for_resume(tmp_path, "standard", resume=False) == "standard"
+
+
+def test_explicit_fast_on_resume_still_wins(tmp_path: Path):
+ save_state(tmp_path, {"run_mode": "standard"})
+ assert _effective_run_mode_for_resume(tmp_path, "fast", resume=True) == "fast"
+
+
+def test_resume_without_prior_state_falls_back_to_invocation(tmp_path: Path):
+ # No state.json at all → keep whatever the invocation requested.
+ assert _effective_run_mode_for_resume(tmp_path, "standard", resume=True) == "standard"
+
+
[email protected]("bad", [None, "", "weird"])
+def test_resume_ignores_unknown_persisted_mode(tmp_path: Path, bad):
+ save_state(tmp_path, {"run_mode": bad} if bad is not None else {})
+ assert _effective_run_mode_for_resume(tmp_path, "standard", resume=True) == "standard"
diff --git a/tests/unit/ingestion/test_traverser.py b/tests/unit/ingestion/test_traverser.py
index 3845f7fcc..83276dfab 100644
--- a/tests/unit/ingestion/test_traverser.py
+++ b/tests/unit/ingestion/test_traverser.py
@@ -266,6 +266,72 @@ class TestPerDirectoryrepowiseIgnore:
assert any("visible.py" in p for p in paths)
+# ---------------------------------------------------------------------------
+# Nested (per-directory) .gitignore
+# ---------------------------------------------------------------------------
+
+
+class TestNestedGitignore:
+ """Git reads a ``.gitignore`` in every directory, not just the repo root.
+ A workspace/monorepo package with its own ``.gitignore`` must be honoured.
+ """
+
+ def test_nested_gitignore_excludes_dir(self, tmp_path: Path) -> None:
+ # Mirrors the #341 case: a yarn-workspace `frontend/` with its own
+ # .gitignore excluding generated bundle output.
+ frontend = tmp_path / "frontend"
+ frontend.mkdir()
+ (frontend / ".gitignore").write_text("storybook-static/\n")
+ (frontend / "storybook-static").mkdir()
+ (frontend / "storybook-static" / "bundle.js").write_text("/* minified */")
+ (frontend / "app.ts").write_text("const x = 1;")
+ traverser = FileTraverser(tmp_path)
+ paths = [f.path for f in traverser.traverse()]
+ assert any("app.ts" in p for p in paths)
+ assert not any("storybook-static" in p for p in paths)
+
+ def test_nested_gitignore_excludes_files(self, tmp_path: Path) -> None:
+ pkg = tmp_path / "pkg"
+ pkg.mkdir()
+ (pkg / ".gitignore").write_text("*.generated.ts\n")
+ (pkg / "real.ts").write_text("const x = 1;")
+ (pkg / "types.generated.ts").write_text("export type T = string;")
+ traverser = FileTraverser(tmp_path)
+ paths = [f.path for f in traverser.traverse()]
+ assert any("real.ts" in p for p in paths)
+ assert not any("types.generated.ts" in p for p in paths)
+
+ def test_nested_gitignore_does_not_affect_sibling_dirs(self, tmp_path: Path) -> None:
+ a = tmp_path / "a"
+ a.mkdir()
+ (a / ".gitignore").write_text("artifacts/\n")
+ (a / "artifacts").mkdir()
+ (a / "artifacts" / "out.py").write_text("pass")
+ b = tmp_path / "b"
+ (b / "artifacts").mkdir(parents=True)
+ (b / "artifacts" / "keep.py").write_text("pass")
+ traverser = FileTraverser(tmp_path)
+ paths = [f.path for f in traverser.traverse()]
+ assert not any("a/artifacts" in p for p in paths)
+ # b/artifacts is not excluded — different directory, no .gitignore there
+ assert any("keep.py" in p for p in paths)
+
+ def test_nested_gitignore_and_repowise_ignore_merge(self, tmp_path: Path) -> None:
+ pkg = tmp_path / "pkg"
+ pkg.mkdir()
+ (pkg / ".gitignore").write_text("bundles/\n")
+ (pkg / ".repowiseIgnore").write_text("*.snap\n")
+ (pkg / "bundles").mkdir()
+ (pkg / "bundles" / "bundle.js").write_text("// built")
+ (pkg / "comp.tsx").write_text("<div />")
+ (pkg / "comp.snap").write_text("snapshot")
+ traverser = FileTraverser(tmp_path)
+ paths = [f.path for f in traverser.traverse()]
+ assert any("comp.tsx" in p for p in paths)
+ assert not any("bundles" in p for p in paths)
+ assert not any("comp.snap" in p for p in paths)
+
+
# ---------------------------------------------------------------------------
# Monorepo detection
# ---------------------------------------------------------------------------
diff --git a/tests/unit/pipeline/test_cancellation.py b/tests/unit/pipeline/test_cancellation.py
new file mode 100644
index 000000000..78ccbf902
--- /dev/null
+++ b/tests/unit/pipeline/test_cancellation.py
@@ -0,0 +1,96 @@
+"""Unit tests for cooperative cancellation (issue #341, Ctrl-C half).
+
+The signal-handler installation is interactive and not exercised here; these
+cover the token mechanics, the BaseException contract that keeps broad
+``except Exception`` guards from swallowing a cancellation, scope restoration,
+and the duplication detector's polling of :func:`check_cancelled`.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from repowise.core.cancellation import (
+ CancellationToken,
+ PipelineCancelled,
+ cancellation_scope,
+ check_cancelled,
+ get_active_token,
+ set_active_token,
+)
+
+
[email protected](autouse=True)
+def _reset_token():
+ """Never let a test leak the global token into the next one."""
+ set_active_token(None)
+ yield
+ set_active_token(None)
+
+
+def test_check_cancelled_noop_without_token():
+ assert get_active_token() is None
+ check_cancelled() # must not raise
+
+
+def test_check_cancelled_noop_when_not_cancelled():
+ token = CancellationToken()
+ set_active_token(token)
+ check_cancelled() # armed but not flipped → no-op
+ assert token.cancelled is False
+
+
+def test_check_cancelled_raises_when_cancelled():
+ token = CancellationToken()
+ token.cancel()
+ set_active_token(token)
+ with pytest.raises(PipelineCancelled):
+ check_cancelled()
+
+
+def test_pipeline_cancelled_is_base_exception_not_exception():
+ """Broad ``except Exception`` must not swallow a cancellation."""
+ assert issubclass(PipelineCancelled, BaseException)
+ assert not issubclass(PipelineCancelled, Exception)
+
+ token = CancellationToken()
+ token.cancel()
+ set_active_token(token)
+ caught_by_exception = False
+ try:
+ try:
+ check_cancelled()
+ except Exception:
+ caught_by_exception = True
+ except PipelineCancelled:
+ pass
+ assert caught_by_exception is False
+
+
+def test_cancellation_scope_arms_and_restores():
+ assert get_active_token() is None
+ with cancellation_scope() as token:
+ assert get_active_token() is token
+ assert token.cancelled is False
+ # Restored to the prior (absent) token on exit.
+ assert get_active_token() is None
+
+
+def test_cancellation_scope_restores_even_on_error():
+ with pytest.raises(ValueError), cancellation_scope():
+ raise ValueError("boom")
+ assert get_active_token() is None
+
+
+def test_detect_clones_bails_when_cancelled():
+ from repowise.core.analysis.health.duplication.detector import detect_clones
+
+ token = CancellationToken()
+ token.cancel()
+ set_active_token(token)
+
+ files = [SimpleNamespace(file_info=SimpleNamespace(path="a.py", abs_path="a.py", language="python"), symbols=[])]
+ with pytest.raises(PipelineCancelled):
+ detect_clones(files)
diff --git a/tests/unit/pipeline/test_resume.py b/tests/unit/pipeline/test_resume.py
new file mode 100644
index 000000000..e9e5e6afa
--- /dev/null
+++ b/tests/unit/pipeline/test_resume.py
@@ -0,0 +1,225 @@
+"""Unit tests for the pipeline resume building blocks (issue #341).
+
+Covers the durable phase ledger, git-metadata rehydration, and the
+controller's skip-decision logic against an in-memory SQLite database. The
+full checkpoint→rehydrate-graph round-trip is exercised by the resume
+integration test once wiring lands.
+"""
+
+from __future__ import annotations
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.pool import StaticPool
+
+from repowise.core.persistence import get_session
+from repowise.core.persistence.crud import upsert_git_metadata_bulk, upsert_repository
+from repowise.core.persistence.database import init_db
+from repowise.core.pipeline.resume import (
+ ResumeController,
+ ResumeLedger,
+ ResumePhase,
+ rehydrate_git_meta_map,
+)
+
+
+async def sf():
+ engine = create_async_engine(
+ "sqlite+aiosqlite:///:memory:",
+ connect_args={"check_same_thread": False},
+ poolclass=StaticPool,
+ )
+ await init_db(engine)
+ yield async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)
+ await engine.dispose()
+
+
+async def _make_repo(sf) -> str:
+ async with get_session(sf) as session:
+ repo = await upsert_repository(session, name="r", local_path="/tmp/r")
+ return repo.id
+
+
+# ---------------------------------------------------------------------------
+# Ledger
+# ---------------------------------------------------------------------------
+
+
+async def test_ledger_marks_and_reads_completed(sf):
+ repo_id = await _make_repo(sf)
+ ledger = ResumeLedger(sf, repo_id)
+
+ assert await ledger.completed_phases() == set()
+
+ await ledger.mark_started(ResumePhase.INDEX)
+ # RUNNING is not COMPLETED.
+ assert await ledger.completed_phases() == set()
+
+ await ledger.mark_completed(ResumePhase.INDEX)
+ assert ResumePhase.INDEX in await ledger.completed_phases()
+
+
+async def test_ledger_completion_survives_a_fresh_ledger(sf):
+ """A new ledger (simulating a re-run process) sees prior completions."""
+ repo_id = await _make_repo(sf)
+ await ResumeLedger(sf, repo_id).mark_completed(ResumePhase.INDEX)
+
+ fresh = ResumeLedger(sf, repo_id)
+ assert ResumePhase.INDEX in await fresh.completed_phases()
+
+
+# ---------------------------------------------------------------------------
+# git_meta_map rehydration
+# ---------------------------------------------------------------------------
+
+
+async def test_rehydrate_git_meta_map_round_trips(sf):
+ repo_id = await _make_repo(sf)
+ rows = [
+ {
+ "file_path": "src/a.py",
+ "commit_count_total": 42,
+ "is_hotspot": True,
+ "co_change_partners_json": '[{"file_path": "src/b.py", "co_change_count": 3}]',
+ },
+ {"file_path": "src/b.py", "commit_count_total": 7, "is_hotspot": False},
+ ]
+ async with get_session(sf) as session:
+ await upsert_git_metadata_bulk(session, repo_id, rows)
+
+ async with get_session(sf) as session:
+ meta = await rehydrate_git_meta_map(session, repo_id)
+
+ assert set(meta) == {"src/a.py", "src/b.py"}
+ assert meta["src/a.py"]["commit_count_total"] == 42
+ assert meta["src/a.py"]["is_hotspot"] is True
+ # JSON columns come back as their stored strings (consumers json.loads them).
+ assert "src/b.py" in meta["src/a.py"]["co_change_partners_json"]
+ # No blame_index is ever persisted.
+ assert "blame_index" not in meta["src/a.py"]
+
+
+async def test_rehydrate_git_meta_map_empty_when_unindexed(sf):
+ repo_id = await _make_repo(sf)
+ async with get_session(sf) as session:
+ assert await rehydrate_git_meta_map(session, repo_id) == {}
+
+
+# ---------------------------------------------------------------------------
+# Controller skip decisions
+# ---------------------------------------------------------------------------
+
+
+async def test_controller_no_skip_without_resume(sf):
+ repo_id = await _make_repo(sf)
+ await ResumeLedger(sf, repo_id).mark_completed(ResumePhase.INDEX)
+
+ ctrl = ResumeController(sf, repo_id, resume=False)
+ assert await ctrl.can_skip(ResumePhase.INDEX) is False
+
+
+async def test_controller_skips_completed_index_on_resume(sf):
+ repo_id = await _make_repo(sf)
+ await ResumeLedger(sf, repo_id).mark_completed(ResumePhase.INDEX)
+
+ ctrl = ResumeController(sf, repo_id, resume=True)
+ assert await ctrl.can_skip(ResumePhase.INDEX) is True
+ # ANALYSIS not completed → cannot skip it (prefix rule).
+ assert await ctrl.can_skip(ResumePhase.ANALYSIS) is False
+
+
+async def test_controller_prefix_rule(sf):
+ """A later phase is only skippable when every earlier phase also completed."""
+ repo_id = await _make_repo(sf)
+ ledger = ResumeLedger(sf, repo_id)
+ # ANALYSIS completed but INDEX not → analysis must NOT be skipped.
+ await ledger.mark_completed(ResumePhase.ANALYSIS)
+
+ ctrl = ResumeController(sf, repo_id, resume=True)
+ assert await ctrl.can_skip(ResumePhase.ANALYSIS) is False
+
+
+async def test_controller_skips_analysis_when_index_and_analysis_complete(sf):
+ repo_id = await _make_repo(sf)
+ ledger = ResumeLedger(sf, repo_id)
+ await ledger.mark_completed(ResumePhase.INDEX)
+ await ledger.mark_completed(ResumePhase.ANALYSIS)
+
+ ctrl = ResumeController(sf, repo_id, resume=True)
+ assert await ctrl.can_skip(ResumePhase.ANALYSIS) is True
+
+
+# ---------------------------------------------------------------------------
+# Analysis rehydration (generation input on a resumed run)
+# ---------------------------------------------------------------------------
+
+
+async def test_rehydrate_dead_code_report_maps_generation_fields(sf):
+ from repowise.core.persistence.models import DeadCodeFinding
+ from repowise.core.pipeline.resume.rehydrate import rehydrate_dead_code_report
+
+ repo_id = await _make_repo(sf)
+ async with get_session(sf) as session:
+ session.add(
+ DeadCodeFinding(
+ repository_id=repo_id,
+ kind="unused_export",
+ file_path="pkg/a.py",
+ symbol_name="foo",
+ symbol_kind="function",
+ confidence=0.9,
+ reason="never imported",
+ safe_to_delete=True,
+ status="open",
+ )
+ )
+
+ async with get_session(sf) as session:
+ report = await rehydrate_dead_code_report(session, repo_id)
+
+ assert len(report.findings) == 1
+ f = report.findings[0]
+ assert f.file_path == "pkg/a.py"
+ assert f.symbol_name == "foo"
+ assert f.kind == "unused_export"
+ assert f.safe_to_delete is True
+
+
+async def test_rehydrate_decision_report_parses_affected_files(sf):
+ from repowise.core.persistence.models import DecisionRecord
+ from repowise.core.pipeline.resume.rehydrate import rehydrate_decision_report
+
+ repo_id = await _make_repo(sf)
+ async with get_session(sf) as session:
+ session.add(
+ DecisionRecord(
+ repository_id=repo_id,
+ title="Adopt X",
+ decision="use X",
+ rationale="it is fast",
+ source="inline_marker",
+ confidence=0.8,
+ evidence_file="x.py",
+ affected_files_json='["x.py", "y.py"]',
+ )
+ )
+
+ async with get_session(sf) as session:
+ report = await rehydrate_decision_report(session, repo_id)
+
+ assert len(report.decisions) == 1
+ d = report.decisions[0]
+ assert d.title == "Adopt X"
+ assert d.affected_files == ["x.py", "y.py"]
+
+
+async def test_rehydrate_analysis_returns_empty_views_when_none_persisted(sf):
+ """A completed-but-empty analysis rehydrates to empty reports, not an
+ error — the caller trusts the ledger and does not recompute."""
+ repo_id = await _make_repo(sf)
+ ctrl = ResumeController(sf, repo_id, resume=True)
+
+ dead_code_report, decision_report = await ctrl.rehydrate_analysis()
+ assert dead_code_report.findings == []
+ assert decision_report.decisions == []