Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(init): a re-run never indexes init's own files, and a fast re-init keeps the documentation (#4245)

Raghav Chamadiyadf6536f36228
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/_finish.py b/packages/cli/src/repowise/cli/commands/init_cmd/_finish.py
index b495a1f6f..3a925682a 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/_finish.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/_finish.py
@@ -41,6 +41,7 @@ from ._options import InitRun
from .persistence import (
apply_git_history_coverage_state,
git_tier_for_run_mode,
+ keep_prior_documentation,
persist_result,
save_full_state_and_config,
)
@@ -213,6 +214,7 @@ def _base_state(run: InitRun) -> dict[str, Any]:
result = run.result
run_mode = run.opts.run_mode
head = get_head_commit(repo_path)
+ prior_state = load_state(repo_path)
base_state = load_state(repo_path)
base_state["last_sync_commit"] = head
docs_mode = _docs_mode(run)
@@ -223,6 +225,7 @@ def _base_state(run: InitRun) -> dict[str, Any]:
base_state["git_tier"] = git_tier_for_run_mode(run_mode)
apply_git_history_coverage_state(base_state, result)
_stamp_scope(run, base_state, docs_mode)
+ keep_prior_documentation(base_state, prior_state, run_mode)
base_state["include_submodules"] = run.opts.include_submodules
if run.phase_timings:
base_state["phase_timings"] = run.phase_timings
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/_prepare.py b/packages/cli/src/repowise/cli/commands/init_cmd/_prepare.py
index 26d5e149d..daf353546 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/_prepare.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/_prepare.py
@@ -153,6 +153,15 @@ def _resolve_settings(run: InitRun) -> None:
run.embedder_was_requested = _embedder_was_requested(opts.embedder_name, config.get("embedder"))
+def _announce_kept_documentation(run: InitRun) -> None:
+ """Fast mode writes no pages, so documentation already here stays."""
+ if run.prior_docs_mode != "none":
+ console.print(
+ "[dim]Keeping the documentation this repo already has. "
+ "Fast mode rebuilds the index and leaves the pages as they are.[/dim]"
+ )
+
+
def _confirm_wiki_overwrite(run: InitRun) -> bool:
"""Read the prior state; False when the user keeps a model-written wiki.
@@ -169,6 +178,9 @@ def _confirm_wiki_overwrite(run: InitRun) -> bool:
run.first_index = not prior_state.get("last_sync_commit")
run.prior_docs_mode = resolve_docs_mode(prior_state)
opts = run.opts
+ if opts.run_mode == "fast":
+ _announce_kept_documentation(run)
+ return True
if not opts.index_only or run.prior_docs_mode != "llm" or opts.force or opts.yes:
return True
console.print(
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py b/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
index 558943aa3..ecb53312e 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
@@ -327,6 +327,45 @@ def git_tier_for_run_mode(run_mode: str) -> str:
return "essential" if run_mode == "fast" else "full"
+#: The ``index_scope`` sections that describe documentation.
+_DOCS_SCOPE_KEYS = ("content_provenance", "file_pages", "provider", "search")
+
+
+def keep_prior_documentation(
+ state: dict[str, Any], prior_state: dict[str, Any], run_mode: str
+) -> None:
+ """Restore the documentation stamps a fast run would otherwise clear from *state*.
+
+ Fast mode writes and removes no pages, so over an index that has them the
+ pages stay and so must what state says about them. The git tier stays
+ this run's: fast re-indexed git at the essential tier.
+ """
+ from repowise.core.docs_mode import resolve_docs_mode
+
+ prior_mode = resolve_docs_mode(prior_state)
+ if run_mode != "fast" or prior_mode == "none":
+ return
+ state.update(docs_mode_state_fields(prior_mode))
+ state["total_pages"] = prior_state.get("total_pages", 0)
+ for key in ("provider", "model"):
+ if prior_state.get(key):
+ state[key] = prior_state[key]
+ _restore_docs_scope(state["index_scope"], prior_state, prior_mode)
+
+
+def _restore_docs_scope(scope: dict[str, Any], prior_state: dict[str, Any], prior_mode: str) -> None:
+ """Put the prior run's documentation sections back into this run's *scope*."""
+ from repowise.core.index_scope import resolve_index_scope
+
+ prior_scope = resolve_index_scope(prior_state)
+ for key in _DOCS_SCOPE_KEYS:
+ scope[key] = prior_scope[key]
+ if scope["content_provenance"] in ("none", "unknown"):
+ # A state older than index_scope records only the docs mode.
+ scope["content_provenance"] = "model" if prior_mode == "llm" else "template"
+ scope["analysis"]["skipped"] = [s for s in scope["analysis"]["skipped"] if s != "generation"]
+
+
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.
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py b/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
index 6579d9bce..e6676818e 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
@@ -79,7 +79,11 @@ from .generation import (
run_repo_generation,
structural_page_summary,
)
-from .persistence import apply_git_history_coverage_state, persist_result
+from .persistence import (
+ apply_git_history_coverage_state,
+ keep_prior_documentation,
+ persist_result,
+)
from .reporting import show_workspace_completion
@@ -597,6 +601,7 @@ def _repo_state(
state["phase_timings"] = repo_phase_timings
apply_git_history_coverage_state(state, result)
_stamp_repo_scope(state, repo_path, ctx, index, docs)
+ keep_prior_documentation(state, load_state(repo_path), ctx.run_mode)
kg = getattr(result, "knowledge_graph_result", None)
if kg is not None:
state["knowledge_graph"] = build_kg_state(kg)
diff --git a/packages/core/src/repowise/core/ingestion/traverser.py b/packages/core/src/repowise/core/ingestion/traverser.py
index 781085574..0b931d9e9 100644
--- a/packages/core/src/repowise/core/ingestion/traverser.py
+++ b/packages/core/src/repowise/core/ingestion/traverser.py
@@ -9,6 +9,8 @@ source file that should be documented. It respects:
4. Binary file detection
5. File-size limit
6. Generated-file detection (header markers + filename suffixes)
+ 7. Repowise's own output (``owned_paths``), so a re-run never indexes what
+ init and its editor setup wrote
It also detects monorepo structure and returns a RepoStructure.
"""
@@ -33,6 +35,7 @@ from pathspec.patterns.gitwildmatch import GitWildMatchPattern, GitWildMatchPatt
from ..code_origin import is_generated_header
from ..dotnet_test_projects import DotnetTestProjects, read_dotnet_test_projects
from ..entry_candidacy import conventional_entry_stems, not_an_execution_start
+from ..owned_paths import MANAGED_FILES, OWNED_PATTERNS, only_repowise_differs
from ..pytest_roots import (
PYTEST_CONFIG_NAMES,
PytestRoots,
@@ -121,6 +124,7 @@ class TraversalStats:
skipped_blocked_pattern: int = 0
skipped_unknown_language: int = 0
skipped_dir_ignore: int = 0
+ skipped_repowise_output: int = 0
skipped_submodule: int = 0
skipped_nested_repo: int = 0
lang_counts: dict[str, int] = field(default_factory=dict)
@@ -292,6 +296,10 @@ _BLOCKED_FILENAME_SPEC: pathspec.PathSpec = pathspec.PathSpec.from_lines(
"gitwildmatch", _BLOCKED_FILENAME_PATTERNS
)
+#: Paths repowise writes whole, and the shared files it writes into.
+_OWNED_SPEC: pathspec.PathSpec = pathspec.PathSpec.from_lines("gitwildmatch", OWNED_PATTERNS)
+_MANAGED_FILES: frozenset[str] = frozenset(MANAGED_FILES)
+
_GENERATED_SUFFIXES: tuple[str, ...] = tuple(_LANG_REGISTRY.generated_suffixes())
# Package-root manifests for monorepo detection, from the language registry.
@@ -777,6 +785,8 @@ class FileTraverser:
return "skipped_dir_ignore"
if self._blocked_patterns.match_file(rel_str):
return "skipped_blocked_pattern"
+ if _is_repowise_output(abs_path, rel_str):
+ return "skipped_repowise_output"
return None
def _root_gitignored(self, rel_str: str) -> bool:
@@ -1685,6 +1695,23 @@ def in_blocked_dir(
)
+def _is_repowise_output(abs_path: Path, rel_str: str) -> bool:
+ """Whether repowise wrote the whole file: an owned path, or a shared one holding only its part.
+
+ A shared file (``CLAUDE.md``, ``.mcp.json``) with anything the user wrote
+ stays indexed, repowise's block included, since the user's part is theirs.
+ """
+ if _OWNED_SPEC.match_file(rel_str):
+ return True
+ if rel_str not in _MANAGED_FILES:
+ return False
+ try:
+ text = abs_path.read_text(encoding="utf-8")
+ except (OSError, UnicodeDecodeError):
+ return False
+ return only_repowise_differs(rel_str, "", text)
+
+
def is_candidate_source_path(
rel_path: str,
repo_root: Path | None = None,
diff --git a/packages/core/src/repowise/core/owned_paths.py b/packages/core/src/repowise/core/owned_paths.py
index cef96c698..9d2babf1d 100644
--- a/packages/core/src/repowise/core/owned_paths.py
+++ b/packages/core/src/repowise/core/owned_paths.py
@@ -1,7 +1,9 @@
"""The paths repowise writes into a repository, and how to tell its edits from a user's.
One list for every reader that must not take repowise's own output for the
-user's change; change risk reads it through ``riskignore_patterns``. Two kinds:
+user's change; change risk reads it through ``riskignore_patterns`` and the
+traverser skips a file repowise wrote whole, so init never indexes its own
+output. Two kinds:
* :data:`OWNED_PATTERNS` are written whole by repowise, so any change there is
repowise's.
diff --git a/packages/core/src/repowise/core/pipeline/phases/ingestion.py b/packages/core/src/repowise/core/pipeline/phases/ingestion.py
index 969c2eebc..0024b0d19 100644
--- a/packages/core/src/repowise/core/pipeline/phases/ingestion.py
+++ b/packages/core/src/repowise/core/pipeline/phases/ingestion.py
@@ -134,6 +134,7 @@ _SKIP_REASONS: tuple[tuple[str, str], ...] = (
("skipped_submodule", "submodule dirs"),
("skipped_nested_repo", "nested git repos"),
("skipped_unknown_language", "unknown type"),
+ ("skipped_repowise_output", "written by repowise"),
)
_TOP_LANGUAGES_SHOWN = 6
diff --git a/tests/unit/cli/test_fast_reinit_keeps_docs.py b/tests/unit/cli/test_fast_reinit_keeps_docs.py
new file mode 100644
index 000000000..efb5b5e2f
--- /dev/null
+++ b/tests/unit/cli/test_fast_reinit_keeps_docs.py
@@ -0,0 +1,125 @@
+"""A fast re-init over an index with documentation keeps the pages and what state says about them."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from types import SimpleNamespace
+
+from repowise.cli.commands.init_cmd import _prepare
+from repowise.cli.commands.init_cmd.persistence import keep_prior_documentation
+from repowise.core.index_scope import resolve_index_scope, stamp_index_scope
+
+
+def _model_state() -> dict:
+ state = {
+ "last_sync_commit": "abc",
+ "docs_mode": "llm",
+ "docs_enabled": True,
+ "total_pages": 12,
+ "provider": "mock",
+ "model": "mock-model",
+ "run_mode": "standard",
+ "git_tier": "full",
+ }
+ stamp_index_scope(
+ state,
+ run_mode="standard",
+ content_provenance="model",
+ git_tier="full",
+ file_pages={"configured_cap": None, "eligible": 20, "generated": 10, "omitted": 10},
+ provider={"name": "mock", "model": "mock-model", "model_cost_possible": True},
+ search={"full_text": "available", "semantic": "unavailable"},
+ analysis={"unavailable": [], "skipped": []},
+ )
+ return state
+
+
+def _fast_stamp(prior: dict) -> dict:
+ """What the fast run stamps before the documentation is restored."""
+ state = json.loads(json.dumps(prior))
+ state.update(docs_mode="none", docs_enabled=False, total_pages=0, run_mode="fast")
+ state["git_tier"] = "essential"
+ stamp_index_scope(
+ state,
+ run_mode="fast",
+ content_provenance="none",
+ git_tier="essential",
+ file_pages={"generated": 0},
+ provider={"name": None, "model": None},
+ search={"full_text": "unavailable"},
+ analysis={"unavailable": [], "skipped": ["generation"]},
+ )
+ return state
+
+
+def test_fast_run_keeps_the_written_documentation() -> None:
+ prior = _model_state()
+ state = _fast_stamp(prior)
+
+ keep_prior_documentation(state, prior, "fast")
+
+ assert state["docs_mode"] == "llm"
+ assert state["total_pages"] == 12
+ assert (state["provider"], state["model"]) == ("mock", "mock-model")
+ scope = resolve_index_scope(state)
+ assert scope["content_provenance"] == "model"
+ assert scope["file_pages"]["generated"] == 10
+ assert scope["search"]["full_text"] == "available"
+ assert scope["analysis"]["skipped"] == []
+ # Fast re-indexed git at the essential tier, so that stays this run's.
+ assert scope["git_tier"] == "essential"
+ assert scope["run_mode"] == "fast"
+
+
+def test_a_state_older_than_index_scope_keeps_its_provenance() -> None:
+ prior = {"last_sync_commit": "abc", "docs_enabled": True, "total_pages": 3}
+ state = _fast_stamp(prior)
+
+ keep_prior_documentation(state, prior, "fast")
+
+ assert state["docs_mode"] == "llm"
+ assert resolve_index_scope(state)["content_provenance"] == "model"
+
+
+def test_standard_run_and_first_fast_run_are_untouched() -> None:
+ prior = _model_state()
+ standard = _fast_stamp(prior)
+ snapshot = json.loads(json.dumps(standard))
+ keep_prior_documentation(standard, prior, "standard")
+ assert standard == snapshot
+
+ first = _fast_stamp({})
+ snapshot = json.loads(json.dumps(first))
+ keep_prior_documentation(first, {}, "fast")
+ assert first == snapshot
+
+
+def _run(tmp_path: Path, **opts) -> SimpleNamespace:
+ (tmp_path / ".repowise").mkdir()
+ (tmp_path / ".repowise" / "state.json").write_text(json.dumps(_model_state()))
+ defaults = {"run_mode": "standard", "index_only": True, "force": False, "yes": False}
+ return SimpleNamespace(repo_path=tmp_path, opts=SimpleNamespace(**{**defaults, **opts}))
+
+
+def test_fast_reinit_does_not_warn_about_replacing_pages(tmp_path: Path, monkeypatch) -> None:
+ printed: list[str] = []
+ monkeypatch.setattr(_prepare.console, "print", lambda *a, **k: printed.append(str(a)))
+ monkeypatch.setattr(_prepare.sys.stdin, "isatty", lambda: False)
+ run = _run(tmp_path, run_mode="fast")
+
+ assert _prepare._confirm_wiki_overwrite(run) is True
+ assert not any("template" in line for line in printed)
+ assert any("Keeping the documentation" in line for line in printed)
+
+
+def test_template_reinit_still_refuses_without_confirmation(tmp_path: Path, monkeypatch) -> None:
+ import click
+ import pytest
+
+ monkeypatch.setattr(_prepare.console, "print", lambda *a, **k: None)
+ monkeypatch.setattr(_prepare.sys.stdin, "isatty", lambda: False)
+ run = _run(tmp_path)
+
+ with pytest.raises(click.ClickException):
+ _prepare._confirm_wiki_overwrite(run)
diff --git a/tests/unit/ingestion/test_traverser_repowise_output.py b/tests/unit/ingestion/test_traverser_repowise_output.py
new file mode 100644
index 000000000..9755ef415
--- /dev/null
+++ b/tests/unit/ingestion/test_traverser_repowise_output.py
@@ -0,0 +1,85 @@
+"""The traverser skips files repowise wrote whole, and keeps shared files a user wrote in."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from repowise.core.generation.editor_files.agents_md import AgentsMdGenerator
+from repowise.core.generation.editor_files.base import BaseEditorFileGenerator as Gen
+from repowise.core.generation.editor_files.claude_md import ClaudeMdGenerator
+from repowise.core.ingestion.traverser import FileTraverser
+
+
+def _block(generator: type[Gen]) -> str:
+ start = Gen.MARKER_START_FMT.format(tag=generator.marker_tag)
+ end = Gen.MARKER_END_FMT.format(tag=generator.marker_tag)
+ return f"{start}\n## Repowise\nindexed facts\n{end}"
+
+
+def _new_file(generator: type[Gen]) -> str:
+ """What the generator writes when the file does not exist yet."""
+ return f"{generator.user_placeholder}\n{_block(generator)}\n"
+
+
+def _write(root: Path, rel: str, text: str) -> None:
+ path = root / rel
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(text, encoding="utf-8")
+
+
+def _indexed(root: Path) -> tuple[set[str], FileTraverser]:
+ traverser = FileTraverser(root)
+ return {fi.path for fi in traverser.traverse()}, traverser
+
+
+def test_files_repowise_wrote_whole_are_skipped(tmp_path: Path) -> None:
+ _write(tmp_path, "app.py", "x = 1\n")
+ _write(tmp_path, ".claude/CLAUDE.md", _new_file(ClaudeMdGenerator))
+ _write(tmp_path, "AGENTS.md", _new_file(AgentsMdGenerator))
+ _write(
+ tmp_path,
+ ".mcp.json",
+ json.dumps({"mcpServers": {"repowise": {"command": "repowise", "args": ["mcp"]}}}),
+ )
+ _write(tmp_path, ".kiro/steering/repowise.md", "# Repowise\n")
+
+ paths, traverser = _indexed(tmp_path)
+
+ assert paths == {"app.py"}
+ assert traverser.stats.skipped_repowise_output == 4
+
+
+def test_a_users_own_content_keeps_the_file_indexed(tmp_path: Path) -> None:
+ _write(tmp_path, "app.py", "x = 1\n")
+ _write(
+ tmp_path,
+ ".claude/CLAUDE.md",
+ f"# My rules\n\nRun pytest.\n\n{_block(ClaudeMdGenerator)}\n",
+ )
+ _write(
+ tmp_path,
+ ".mcp.json",
+ json.dumps(
+ {
+ "mcpServers": {
+ "repowise": {"command": "repowise", "args": ["mcp"]},
+ "github": {"command": "gh-mcp"},
+ }
+ }
+ ),
+ )
+
+ paths, traverser = _indexed(tmp_path)
+
+ assert paths == {"app.py", ".claude/CLAUDE.md", ".mcp.json"}
+ assert traverser.stats.skipped_repowise_output == 0
+
+
+def test_only_the_root_path_is_repowise_output(tmp_path: Path) -> None:
+ """A nested ``AGENTS.md`` is not one repowise writes, whatever it holds."""
+ _write(tmp_path, "pkg/AGENTS.md", _new_file(AgentsMdGenerator))
+
+ paths, _ = _indexed(tmp_path)
+
+ assert paths == {"pkg/AGENTS.md"}