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(doctor): give every check a stable id, a level and a known fix (#4675)

Raghav Chamadiyafdc0e34ddd87
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index 569e52d06..030adf60b 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -2056,6 +2056,11 @@ repowise doctor --workspace --repair
| `--workspace` / `-w`, `--no-workspace` | Workspace table (dir exists, git repo, state.json ↔ config drift) then per-repo checks / single repo. | auto-detect |
| `--format` | `table` or `json`. | `table` |
+- **`--format json`** prints `{"ok": bool, "checks": [...]}`. Each check carries a stable `id` (kebab case, such as
+ `post-commit-hook` or `mcp-responds`), a display `name`, a `level` (`ok`, `warn` or `fail`), `ok` (false only for
+ `fail`), a `detail` and a `fix`: the exact command that resolves it, or `null`. Match on `id`; names can change.
+ A `warn` never changes the exit code. With `--workspace`, ids repeat once per repo and `name` starts with the
+ repo's alias.
- **Vector store** fails when `.repowise/lancedb` won't open, naming the error. An open store with no indexable pages
reports all missing; `--repair` won't re-embed it with a paid embedder, it prints the count and points to `repowise
reindex`.
diff --git a/packages/cli/src/repowise/cli/commands/doctor_cmd/__init__.py b/packages/cli/src/repowise/cli/commands/doctor_cmd/__init__.py
index 3aa06a0af..dcf58c935 100644
--- a/packages/cli/src/repowise/cli/commands/doctor_cmd/__init__.py
+++ b/packages/cli/src/repowise/cli/commands/doctor_cmd/__init__.py
@@ -4,7 +4,7 @@ Split out of a single ~1k-line module into cohesive parts:
* :mod:`._types` — the ``DoctorCheck`` NamedTuple + tiny formatting helpers
* :mod:`.advisories` — advisory-only signals (CLAUDE.md stamp, CLI version)
-* :mod:`.repo_checks` — the per-repo check battery + ``--repair``
+* :mod:`.repo_checks` — the per-repo check battery (``collect_repo_checks``) + ``--repair``
* :mod:`.workspace_checks` — workspace-level validation + MCP detection
* :mod:`.command` — the Click command + single/workspace orchestration
@@ -26,7 +26,7 @@ from .advisories import (
_print_cli_version_status,
)
from .command import doctor_command
-from .repo_checks import _decision_vector_ids, _distill_checks
+from .repo_checks import _decision_vector_ids, _distill_checks, collect_repo_checks
from .workspace_checks import _check_mcp_registered, _run_workspace_checks
__all__ = [
@@ -40,6 +40,7 @@ __all__ = [
"_print_cli_version_status",
"_run_workspace_checks",
"advisories",
+ "collect_repo_checks",
"command",
"console",
"doctor_command",
diff --git a/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/core.py b/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/core.py
index 7041d4684..29c7e042d 100644
--- a/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/core.py
+++ b/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/core.py
@@ -33,7 +33,13 @@ async def _page_count(session: object, repo_id: str) -> int:
def _repowise_dir_check(repowise_dir: _DoctorPath) -> DoctorCheck:
"""Exists and writable, probed with a real file: os.access lies on Windows."""
if not repowise_dir.exists():
- return _check(".repowise/ directory", False, f"{repowise_dir} (run 'repowise init')")
+ return _check(
+ ".repowise/ directory",
+ False,
+ f"{repowise_dir} (run 'repowise init')",
+ check_id="repowise-dir",
+ fix="repowise init",
+ )
probe = repowise_dir / ".doctor-write-probe"
try:
probe.write_text("", encoding="utf-8")
@@ -43,29 +49,39 @@ def _repowise_dir_check(repowise_dir: _DoctorPath) -> DoctorCheck:
".repowise/ directory",
False,
f"{repowise_dir} is not writable ({exc.strerror or exc}); fix its permissions",
+ check_id="repowise-dir",
)
- return _check(".repowise/ directory", True, str(repowise_dir))
+ return _check(".repowise/ directory", True, str(repowise_dir), check_id="repowise-dir")
def _autosync_hook_check(repo_path: _DoctorPath) -> DoctorCheck:
"""Report the post-commit hook through hooks.status, which asks git for the
- real hooks directory, so worktrees and core.hooksPath read correctly."""
+ real hooks directory, so worktrees and core.hooksPath read correctly.
+
+ Never a fail: init installs it by default and ``--no-hook`` opts out, so
+ a missing hook is a warn naming the command that turns auto-sync on."""
+ name, check_id = "Post-commit hook", "post-commit-hook"
try:
from repowise.cli.hooks import status as _hook_status
state = _hook_status(repo_path)
except Exception as exc:
- return _check("Post-commit hook", True, f"could not read hook state ({exc})")
+ detail = f"could not read hook state ({exc})"
+ return _check(name, True, detail, check_id=check_id, warn=True)
if state.startswith("installed"):
- return _check("Post-commit hook", True, state)
+ return _check(name, True, state, check_id=check_id)
if state == "not installed":
return _check(
- "Post-commit hook",
+ name,
True,
"not installed; the index updates only when you run 'repowise update' "
"('repowise hook install' turns auto-sync on)",
+ check_id=check_id,
+ warn=True,
+ fix="repowise hook install",
)
- return _check("Post-commit hook", True, state)
+ # "not a git repository" is already the git row's fail; "unreadable" is not.
+ return _check(name, True, state, check_id=check_id, warn=state == "unreadable")
def _attribution_notes_check(repo_path: _DoctorPath) -> DoctorCheck | None:
@@ -75,7 +91,7 @@ def _attribution_notes_check(repo_path: _DoctorPath) -> DoctorCheck | None:
refspec and an explicit push, and survive a rebase only via
``notes.rewriteRef``; without them coverage is silently low elsewhere.
"""
- name = "Attribution notes"
+ name, check_id = "Attribution notes", "attribution-notes"
try:
from repowise.core.attribution import load_attribution_settings
@@ -85,22 +101,28 @@ def _attribution_notes_check(repo_path: _DoctorPath) -> DoctorCheck | None:
status = refspec_status(_DoctorPath(repo_path))
except OSError as exc:
- return _check(name, True, f"could not read git config ({exc})")
+ detail = f"could not read git config ({exc})"
+ return _check(name, True, detail, check_id=check_id, warn=True)
if not status["remote"]:
- return _check(name, True, "no origin remote, so notes stay on this machine")
+ return _check(
+ name, True, "no origin remote, so notes stay on this machine", check_id=check_id
+ )
push = (
"push refspec set"
if status["push"]
else f"share them with 'git push origin {NOTES_REF}'"
)
- problems = []
+ commands = []
if not status["fetch"]:
- problems.append(f"run 'git config --add remote.origin.fetch \"{FETCH_REFSPEC}\"'")
+ commands.append(f'git config --add remote.origin.fetch "{FETCH_REFSPEC}"')
if not status["rewrite_ref"]:
- problems.append(f"run 'git config --add notes.rewriteRef {NOTES_REF}'")
- if problems:
- return _check(name, False, "; ".join([*problems, push]))
- return _check(name, True, f"fetch refspec and notes.rewriteRef set; {push}")
+ commands.append(f"git config --add notes.rewriteRef {NOTES_REF}")
+ if commands:
+ problems = [f"run '{c}'" for c in commands]
+ # One command is the fix; two are listed in the detail instead.
+ fix = commands[0] if len(commands) == 1 else None
+ return _check(name, False, "; ".join([*problems, push]), check_id=check_id, fix=fix)
+ return _check(name, True, f"fetch refspec and notes.rewriteRef set; {push}", check_id=check_id)
def _events_config_check(repo_path: _DoctorPath) -> DoctorCheck | None:
@@ -110,10 +132,14 @@ def _events_config_check(repo_path: _DoctorPath) -> DoctorCheck | None:
errors = load_event_settings(repo_path).errors
except Exception as exc:
- return _check("Events config", True, f"could not read it ({exc})")
+ return _check(
+ "Events config", True, f"could not read it ({exc})", check_id="events-config", warn=True
+ )
if not errors:
return None
- return _check("Events config", False, "; ".join(errors) + " (defaults used)")
+ return _check(
+ "Events config", False, "; ".join(errors) + " (defaults used)", check_id="events-config"
+ )
def _env_repo_covers(repo_path: _DoctorPath) -> bool:
@@ -148,9 +174,9 @@ def _git_check(repo_path: _DoctorPath) -> DoctorCheck:
except (InvalidGitRepositoryError, NoSuchPathError):
if not _env_repo_covers(repo_path):
raise
- return _check("Git repository", True, str(repo_path))
+ return _check("Git repository", True, str(repo_path), check_id="git-repository")
except Exception:
- return _check("Git repository", False, "Not a git repo")
+ return _check("Git repository", False, "Not a git repo", check_id="git-repository")
def _hook_rows(repo_path: _DoctorPath) -> list[DoctorCheck]:
@@ -180,13 +206,15 @@ def _database_rows(ctx: CheckContext) -> list[DoctorCheck]:
"""Sets ``ctx.db_ok`` and ``ctx.page_count`` for the later groups."""
probed = (ctx.repowise_dir / "wiki.db").exists() or db_configured()
if not probed:
- return [_check("Database", False, "wiki.db not found")]
+ return [
+ _check("Database", False, "wiki.db not found", check_id="database", fix="repowise init")
+ ]
try:
ctx.page_count = run_async(_count_pages(ctx.repo_path))
ctx.db_ok = True
except Exception as e:
- return [_check("Database", False, str(e))]
- return [_check("Database", True, f"{ctx.page_count} pages")]
+ return [_check("Database", False, str(e), check_id="database")]
+ return [_check("Database", True, f"{ctx.page_count} pages", check_id="database")]
def _state_row(ctx: CheckContext) -> DoctorCheck:
@@ -198,6 +226,7 @@ def _state_row(ctx: CheckContext) -> DoctorCheck:
f"last_sync: {(ctx.state.get('last_sync_commit') or '—')[:8]}"
if ctx.state_ok
else "Not found or empty",
+ check_id="state-json",
)
@@ -205,21 +234,29 @@ def _store_format_row(repo_path: _DoctorPath) -> DoctorCheck:
"""Does this store predate a capability the current build offers?
A REINDEX_RECOMMENDED migration never auto-runs, so doctor is where an
- un-upgraded store learns a re-index is available. Reported OK, not FAIL:
+ un-upgraded store learns a re-index is available. Reported WARN, not FAIL:
the store works degraded, it is not broken, and failing every pre-upgrade
store's doctor run would cry wolf. The row carries the exact command so it
is actionable even after the once-per-store update nag was suppressed.
"""
+ name, check_id = "Store format", "store-format"
try:
from repowise.cli.upgrade import assess_store
verdict = assess_store(repo_path)
if verdict.reindex_recommended and verdict.reindex_command:
notice = verdict.user_notice or "A re-index adds new capabilities."
- return _check("Store format", True, f"{notice} Run: {verdict.reindex_command}")
- return _check("Store format", True, "Current")
+ return _check(
+ name,
+ True,
+ f"{notice} Run: {verdict.reindex_command}",
+ check_id=check_id,
+ warn=True,
+ fix=verdict.reindex_command,
+ )
+ return _check(name, True, "Current", check_id=check_id)
except Exception as e:
- return _check("Store format", True, f"Could not check: {e}")
+ return _check(name, True, f"Could not check: {e}", check_id=check_id, warn=True)
def _runtime_grammar_rows(repo_path: _DoctorPath) -> list[DoctorCheck]:
@@ -257,13 +294,16 @@ def _runtime_grammar_rows(repo_path: _DoctorPath) -> list[DoctorCheck]:
for tag, count in sorted(counts.items()):
spec = REGISTRY.get(tag)
name = f"{spec.display_name if spec else tag} grammar"
+ check_id = f"grammar-{tag.lower().replace('_', '-')}"
try:
cached, cache_dir = runtime_grammar_cache(tag)
except Exception as exc:
- rows.append(_check(name, False, f"could not read the grammar cache ({exc})"))
+ rows.append(
+ _check(name, False, f"could not read the grammar cache ({exc})", check_id=check_id)
+ )
continue
if cached:
- rows.append(_check(name, True, f"cached in {cache_dir}"))
+ rows.append(_check(name, True, f"cached in {cache_dir}", check_id=check_id))
else:
rows.append(
_check(
@@ -272,6 +312,7 @@ def _runtime_grammar_rows(repo_path: _DoctorPath) -> list[DoctorCheck]:
f"not downloaded; {count:,} files would index without symbols. "
"Re-run 'repowise init' with network access, or stage a cache with "
"'repowise grammars fetch <dir>' and set REPOWISE_GRAMMAR_DIR to it",
+ check_id=check_id,
)
)
return rows
diff --git a/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/integrations.py b/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/integrations.py
index a4806d4f2..4374f4edd 100644
--- a/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/integrations.py
+++ b/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/integrations.py
@@ -60,18 +60,26 @@ def _agent_target_checks(
try:
targets = all_targets()
except Exception as exc: # pragma: no cover - a broken registry is a crash elsewhere
- return [_check("Agent integrations", True, f"Could not check: {exc}")], False
+ row = _check(
+ "Agent integrations",
+ True,
+ f"Could not check: {exc}",
+ check_id="agent-integrations",
+ warn=True,
+ )
+ return [row], False
for target in targets:
- name = f"Agent: {target.id}"
+ name, check_id = f"Agent: {target.id}", f"agent-{target.id}"
try:
report = target.doctor(repo_path=repo_path)
except Exception as exc:
- checks.append(_check(name, True, f"Could not check: {exc}"))
+ detail = f"Could not check: {exc}"
+ checks.append(_check(name, True, detail, check_id=check_id, warn=True))
continue
if report.status.value in ("ok", "not-installed"):
detail = report.issues[0] if report.issues else "wired up"
- checks.append(_check(name, True, detail))
+ checks.append(_check(name, True, detail, check_id=check_id))
continue
# Only conditions the repair pass can actually resolve drive it. A
# plugin the CLI cannot rewrite, or a fix that is a different command,
@@ -81,7 +89,17 @@ def _agent_target_checks(
detail = "; ".join(report.issues)
if report.fix_command:
detail += f" (run: {report.fix_command})"
- checks.append(_check(name, report.status.value != "broken", detail))
+ # Stale is a warn and broken a fail; only broken changes the exit code.
+ checks.append(
+ _check(
+ name,
+ report.status.value != "broken",
+ detail,
+ check_id=check_id,
+ warn=True,
+ fix=report.fix_command or None,
+ )
+ )
return checks, needs_refresh
@@ -102,8 +120,8 @@ def _registered_mcp_entry() -> dict | None:
return _stored_repowise_entry(_claude_code_settings_path())
-def _unregistered_detail() -> str:
- """Why there is no entry: absent, or present but unreadable.
+def _unregistered_detail() -> tuple[str, bool]:
+ """``(detail, unreadable)``: why there is no entry, absent or present but unreadable.
Those have different fixes, and collapsing them tells a user with a
hand-broken settings.json to run ``init``, which will fail on the same
@@ -119,8 +137,8 @@ def _unregistered_detail() -> str:
try:
load_existing_config(settings_path)
except Exception:
- return f"could not parse {settings_path}"
- return "not registered (repowise init registers it)"
+ return f"could not parse {settings_path}", True
+ return "not registered (repowise init registers it)", False
@_functools.cache
@@ -138,19 +156,26 @@ def _mcp_responds_check() -> DoctorCheck:
checks once per entry. Without the cache a ten-repo workspace would launch
the same server ten times and pay the startup cost for each.
"""
- from ..mcp_smoke import CHECK_NAME, mcp_smoke_check
+ from ..mcp_smoke import CHECK_ID, CHECK_NAME, mcp_smoke_check
try:
entry = _registered_mcp_entry()
if entry is None:
- return _check(CHECK_NAME, True, "not registered - nothing to launch")
+ return _check(
+ CHECK_NAME, True, "not registered - nothing to launch", check_id=CHECK_ID
+ )
command = entry.get("command")
args = entry.get("args")
if not isinstance(command, str) or not isinstance(args, list):
- return _check(CHECK_NAME, True, "registration is hand-shaped - not launching it")
+ return _check(
+ CHECK_NAME,
+ True,
+ "registration is hand-shaped - not launching it",
+ check_id=CHECK_ID,
+ )
return mcp_smoke_check(command, [str(a) for a in args], entry.get("env"))
except Exception as exc: # a doctor check must never be the crash
- return _check(CHECK_NAME, True, f"Could not check: {exc}")
+ return _check(CHECK_NAME, True, f"Could not check: {exc}", check_id=CHECK_ID, warn=True)
def _claude_registration_check(
@@ -173,11 +198,14 @@ def _claude_registration_check(
This is a *static* check. Whether the server actually starts is
``_mcp_responds_check``.
"""
- name = "Claude Code MCP entry"
+ name, check_id = "Claude Code MCP entry", "claude-code-mcp-entry"
try:
entry = _registered_mcp_entry()
if entry is None:
- return _check(name, True, _unregistered_detail()), False
+ # An unparseable settings file is worth a look; no entry at all is
+ # a choice (another agent, or none).
+ detail, unreadable = _unregistered_detail()
+ return _check(name, True, detail, check_id=check_id, warn=unreadable), False
problems: list[str] = []
command = entry.get("command")
@@ -193,16 +221,18 @@ def _claude_registration_check(
if target is not None and not _DoctorPath(target).is_dir():
problems.append(f"registered path missing: {target}")
if problems:
- return _check(name, False, "; ".join(problems) + " (rerun with --repair)"), True
+ detail = "; ".join(problems) + " (rerun with --repair)"
+ row = _check(name, False, detail, check_id=check_id, fix="repowise doctor --repair")
+ return row, True
if target is not None and repo_path is not None and not _registers_repo(target, repo_path):
+ add = "repowise agents add --target=claude-code --scope=project"
detail = (
- f"serves {target}; this repo is not registered (run `repowise agents add "
- "--target=claude-code --scope=project` for a project entry)"
+ f"serves {target}; this repo is not registered (run `{add}` for a project entry)"
)
- return _check(name, True, detail), False
- return _check(name, True, target or "registered"), False
+ return _check(name, True, detail, check_id=check_id, warn=True, fix=add), False
+ return _check(name, True, target or "registered", check_id=check_id), False
except Exception as exc:
- return _check(name, True, f"Could not check: {exc}"), False
+ return _check(name, True, f"Could not check: {exc}", check_id=check_id, warn=True), False
def _registers_repo(target: str, repo_path: _DoctorPath) -> bool:
@@ -299,11 +329,15 @@ def _distill_config_row(repo_path: _DoctorPath) -> tuple[DoctorCheck, object]:
problems = validate_distill_config(distill_cfg)
if problems:
- return _check("Distill config", False, "; ".join(problems)), distill_cfg
+ row = _check("Distill config", False, "; ".join(problems), check_id="distill-config")
+ return row, distill_cfg
detail = "valid" if distill_cfg else "defaults (no block)"
- return _check("Distill config", True, detail), distill_cfg
+ return _check("Distill config", True, detail, check_id="distill-config"), distill_cfg
except Exception as exc:
- return _check("Distill config", True, f"Could not check: {exc}"), distill_cfg
+ row = _check(
+ "Distill config", True, f"Could not check: {exc}", check_id="distill-config", warn=True
+ )
+ return row, distill_cfg
def _omission_store_row(repo_path: _DoctorPath, distill_cfg: object) -> DoctorCheck:
@@ -315,7 +349,7 @@ def _omission_store_row(repo_path: _DoctorPath, distill_cfg: object) -> DoctorCh
_ttl_days, max_mb = omission_store_settings(distill_cfg)
db_path = repo_path / ".repowise" / "omissions" / "omissions.db"
if not db_path.is_file():
- return _check("Omission store", True, "not created yet")
+ return _check("Omission store", True, "not created yet", check_id="omission-store")
size_bytes = db_path.stat().st_size
wal = db_path.with_name(db_path.name + "-wal")
if wal.is_file():
@@ -325,9 +359,11 @@ def _omission_store_row(repo_path: _DoctorPath, distill_cfg: object) -> DoctorCh
detail = f"{size_mb:.1f} MB (cap {max_mb:g} MB)"
if not ok:
detail += " — over cap; pruning happens on the next distill write"
- return _check("Omission store", ok, detail)
+ return _check("Omission store", ok, detail, check_id="omission-store")
except Exception as exc:
- return _check("Omission store", True, f"Could not check: {exc}")
+ return _check(
+ "Omission store", True, f"Could not check: {exc}", check_id="omission-store", warn=True
+ )
def _rewrite_hook_surfaces() -> list[tuple[str, object]]:
@@ -346,11 +382,13 @@ def _rewrite_hook_surfaces() -> list[tuple[str, object]]:
return surfaces
-def _installed_rewrite_hooks(surfaces: list[tuple[str, object]]) -> list[str]:
+def _installed_rewrite_hooks(surfaces: list[tuple[str, object]]) -> tuple[list[str], bool]:
+ """``(names, any_unmatched)`` for the surfaces with the hook installed."""
# Registered and live are different questions: an entry whose matcher
# predates a tool rename is registered and fires on some or none of the
# agent's shell tools. Say which, rather than calling all three "installed".
installed_names = []
+ any_unmatched = False
for name, adapter in surfaces:
status = adapter.rewrite_hook_status() # type: ignore[attr-defined]
if not status.installed:
@@ -358,26 +396,32 @@ def _installed_rewrite_hooks(surfaces: list[tuple[str, object]]) -> list[str]:
if not status.unmatched:
installed_names.append(name)
else:
+ any_unmatched = True
misses = ", ".join(status.unmatched)
installed_names.append(f"{name} (matcher misses {misses})")
- return installed_names
+ return installed_names, any_unmatched
def _rewrite_hook_row(distill_cfg: object) -> DoctorCheck:
- """Advisory: the rewrite hook is strictly opt-in."""
+ """Advisory: the rewrite hook is strictly opt-in. A matcher that misses a
+ shell tool is a warn: installed but not firing there."""
+ name, check_id = "Distill rewrite hook", "distill-rewrite-hook"
try:
- installed_names = _installed_rewrite_hooks(_rewrite_hook_surfaces())
+ installed_names, any_unmatched = _installed_rewrite_hooks(_rewrite_hook_surfaces())
if installed_names:
commands_cfg = distill_cfg.get("commands") if isinstance(distill_cfg, dict) else None
opted_out = isinstance(commands_cfg, dict) and commands_cfg.get("enabled") is False
detail = ", ".join(installed_names)
detail += " (this repo opted out)" if opted_out else ""
detail = f"installed: {detail}"
+ if any_unmatched:
+ fix = "repowise hook rewrite install"
+ return _check(name, True, detail, check_id=check_id, warn=True, fix=fix)
else:
detail = "not installed (opt-in: repowise hook rewrite install)"
- return _check("Distill rewrite hook", True, detail)
+ return _check(name, True, detail, check_id=check_id)
except Exception as exc:
- return _check("Distill rewrite hook", True, f"Could not check: {exc}")
+ return _check(name, True, f"Could not check: {exc}", check_id=check_id, warn=True)
def _distill_checks(repo_path: _DoctorPath) -> list[DoctorCheck]:
diff --git a/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/providers.py b/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/providers.py
index fbec6c558..f69c2c713 100644
--- a/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/providers.py
+++ b/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/providers.py
@@ -76,17 +76,18 @@ def _provider_checks(repo_path: _DoctorPath) -> list[DoctorCheck]:
"Providers",
bool(providers),
f"Implementations loaded: {', '.join(providers)}",
+ check_id="providers",
)
)
except Exception as exc:
- checks.append(_check("Providers", False, str(exc)))
+ checks.append(_check("Providers", False, str(exc), check_id="providers"))
from repowise.cli.helpers import validate_provider_config
config_warnings = validate_provider_config(repo_path=repo_path)
config_ok = not config_warnings
config_detail = "No misconfigured provider keys" if config_ok else "; ".join(config_warnings)
- checks.append(_check("Provider config", config_ok, config_detail))
+ checks.append(_check("Provider config", config_ok, config_detail, check_id="provider-config"))
from repowise.core.providers.llm.registry import provider_available_for_repo
@@ -98,33 +99,41 @@ def _provider_checks(repo_path: _DoctorPath) -> list[DoctorCheck]:
)
# Keyless operation is supported, so this is informational rather than a
# failing health check. The detail tells users what init will actually do.
- checks.append(_check("LLM provider", True, llm_detail))
+ checks.append(_check("LLM provider", True, llm_detail, check_id="llm-provider"))
return checks
def _hosted_account_check() -> DoctorCheck:
"""Informational: signed out is not a failure."""
+ name, check_id = "Hosted account", "hosted-account"
try:
from repowise.cli.platform import auth, credentials
creds = credentials.load()
if creds is None:
return _check(
- "Hosted account",
+ name,
True,
"Not signed in (optional: repowise login). "
"Publish this repo free: repowise publish",
+ check_id=check_id,
)
if creds.get("stale"):
- return _check("Hosted account", False, "Session expired or revoked; run repowise login")
+ return _check(
+ name,
+ False,
+ "Session expired or revoked; run repowise login",
+ check_id=check_id,
+ fix="repowise login",
+ )
account = auth.fetch_account()
cached = (account or creds.get("account") or {}) or {}
who = cached.get("github_username") or cached.get("email") or "unknown"
tier = cached.get("tier") or "free"
suffix = "" if account else " (offline, using cached identity)"
- return _check("Hosted account", True, f"{who} ({tier}){suffix}")
+ return _check(name, True, f"{who} ({tier}){suffix}", check_id=check_id)
except Exception as e:
- return _check("Hosted account", False, str(e))
+ return _check(name, False, str(e), check_id=check_id)
async def _read_stale_counts(repo_path: _DoctorPath) -> dict[str, int]:
@@ -143,14 +152,15 @@ async def _read_stale_counts(repo_path: _DoctorPath) -> dict[str, int]:
def _stale_pages_row(ctx: CheckContext) -> DoctorCheck:
"""Sets ``ctx.stale_counts`` and ``ctx.stale_count`` for ``--repair``."""
+ name, check_id = "Stale pages", "stale-pages"
try:
ctx.stale_counts = run_async(_read_stale_counts(ctx.repo_path))
ctx.stale_count = sum(ctx.stale_counts.values())
if ctx.stale_count:
- return _check("Stale pages", False, _stale_page_guidance(ctx.stale_counts))
- return _check("Stale pages", True, "0 stale")
+ return _check(name, False, _stale_page_guidance(ctx.stale_counts), check_id=check_id)
+ return _check(name, True, "0 stale", check_id=check_id)
except Exception:
- return _check("Stale pages", True, "Could not check")
+ return _check(name, True, "Could not check", check_id=check_id, warn=True)
def provider_checks(ctx: CheckContext) -> list[DoctorCheck]:
diff --git a/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/stores.py b/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/stores.py
index 7fb4816ab..3b780b9f4 100644
--- a/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/stores.py
+++ b/packages/cli/src/repowise/cli/commands/doctor_cmd/_checks/stores.py
@@ -12,6 +12,8 @@ from repowise.core.exclusion import build_exclude_spec, is_excluded
from .._types import DoctorCheck, _check
from .context import CheckContext, StoreDrift, open_store
+_REPAIR = "repowise doctor --repair"
+
async def _decision_vector_ids(session, repository_id: str) -> set[str]:
"""Vector-store ids for this repo's decision records.
@@ -233,6 +235,7 @@ def _consistency_rows(ctx: CheckContext) -> list[DoctorCheck]:
False,
f"cannot open .repowise/lancedb ({vector_store_error}); semantic "
"search is off until it opens, then run `repowise reindex`",
+ check_id="vector-store",
)
)
vec_ok, vec_detail = _drift_detail(drift.missing_from_vector, drift.orphaned_vector)
@@ -241,15 +244,39 @@ def _consistency_rows(ctx: CheckContext) -> list[DoctorCheck]:
# Name the command: `--resume` exists only on `init`.
if stub_count:
vec_detail += f" · {stub_count} stub(s) awaiting `repowise init --resume`"
- rows.append(_check("SQL ↔ Vector Store", vec_ok, vec_detail))
+ # --repair declines to re-embed a whole empty store; reindex does that.
+ vec_fix = "repowise reindex" if drift.vector_store_empty else _REPAIR
+ rows.append(
+ _check(
+ "SQL ↔ Vector Store",
+ vec_ok,
+ vec_detail,
+ check_id="vector-store-sync",
+ fix=None if vec_ok else vec_fix,
+ )
+ )
fts_ok, fts_detail = _drift_detail(drift.missing_from_fts, drift.orphaned_fts)
- rows.append(_check("SQL ↔ FTS Index", fts_ok, fts_detail))
+ rows.append(
+ _check(
+ "SQL ↔ FTS Index",
+ fts_ok,
+ fts_detail,
+ check_id="fts-index-sync",
+ fix=None if fts_ok else _REPAIR,
+ )
+ )
except Exception as exc:
- # Name the failure. "Could not check" is reported as OK, so a
- # reconciliation that raises on every run would look exactly like one
- # that had nothing to reconcile.
+ # Name the failure. "Could not check" is a warn, not a fail, so without
+ # the exception a reconciliation that raises on every run would read
+ # like one that had nothing to reconcile.
rows.append(
- _check("Store consistency", True, f"Could not check: {type(exc).__name__}: {exc}")
+ _check(
+ "Store consistency",
+ True,
+ f"Could not check: {type(exc).__name__}: {exc}",
+ check_id="store-consistency",
+ warn=True,
+ )
)
return rows
@@ -331,12 +358,23 @@ def _coordinator_row(ctx: CheckContext) -> DoctorCheck:
str(vector_count) if vector_count != -1 and vector_count is not None else "unknown"
)
detail = f"SQL={sql_pages}, Vector={vec_display}, Drift={drift_pct}"
- row = _check("Coordinator drift", drift is None or drift < 0.05, detail)
+ row = _check(
+ "Coordinator drift",
+ drift is None or drift < 0.05,
+ detail,
+ check_id="coordinator-drift",
+ )
ctx.coord_drift_color = drift_color
ctx.coord_drift_pct = drift_pct
return row
except Exception as exc:
- return _check("Coordinator drift", True, f"Could not check: {exc}")
+ return _check(
+ "Coordinator drift",
+ True,
+ f"Could not check: {exc}",
+ check_id="coordinator-drift",
+ warn=True,
+ )
def store_checks(ctx: CheckContext) -> list[DoctorCheck]:
diff --git a/packages/cli/src/repowise/cli/commands/doctor_cmd/_render.py b/packages/cli/src/repowise/cli/commands/doctor_cmd/_render.py
index 0487d7a5d..ab55cbdf1 100644
--- a/packages/cli/src/repowise/cli/commands/doctor_cmd/_render.py
+++ b/packages/cli/src/repowise/cli/commands/doctor_cmd/_render.py
@@ -5,6 +5,7 @@ from __future__ import annotations
from rich.table import Table
from repowise.cli.helpers import console
+from repowise.cli.ui.brand import WARN
from ._checks.context import CheckContext
from ._types import DoctorCheck, _status_markup
@@ -13,7 +14,7 @@ from .advisories import _advise_claude_md_stamp
def render_checks(ctx: CheckContext, checks: list[DoctorCheck], all_ok: bool) -> None:
# The "Coordinator drift" row's detail gets its drift percentage colored
- # here, since that highlight is orthogonal to the row's own OK/FAIL status.
+ # here, since that highlight is orthogonal to the row's own status.
table = Table(title=f"repowise Doctor — {ctx.repo_path.name}")
table.add_column("Check", style="cyan")
table.add_column("Status")
@@ -23,7 +24,7 @@ def render_checks(ctx: CheckContext, checks: list[DoctorCheck], all_ok: bool) ->
detail = c.detail
if c.name == "Coordinator drift":
detail = detail.replace(f"Drift={pct}", f"Drift=[{color}]{pct}[/{color}]")
- table.add_row(c.name, _status_markup(c.ok), detail)
+ table.add_row(c.name, _status_markup(c.level), detail)
console.print(table)
# CLAUDE.md freshness stamp: advisory, never fails the run. If editor-file
@@ -31,7 +32,13 @@ def render_checks(ctx: CheckContext, checks: list[DoctorCheck], all_ok: bool) ->
# reading the stale "Last indexed" line distrust the tools.
_advise_claude_md_stamp(ctx.repo_path, ctx.state)
- if all_ok:
+ warnings = sum(c.level == "warn" for c in checks)
+ if all_ok and warnings:
+ console.print(
+ f"[bold green]All checks passed[/bold green], "
+ f"[{WARN}]{warnings} warning(s) worth a look.[/{WARN}]"
+ )
+ elif all_ok:
console.print("[bold green]All checks passed![/bold green]")
else:
console.print("[bold yellow]Some checks failed.[/bold yellow]")
diff --git a/packages/cli/src/repowise/cli/commands/doctor_cmd/_types.py b/packages/cli/src/repowise/cli/commands/doctor_cmd/_types.py
index 3dec67f87..3ab0d9561 100644
--- a/packages/cli/src/repowise/cli/commands/doctor_cmd/_types.py
+++ b/packages/cli/src/repowise/cli/commands/doctor_cmd/_types.py
@@ -1,19 +1,53 @@
-"""Shared value types and tiny formatting helpers for ``repowise doctor``."""
+"""The doctor row type, its ok/warn/fail level, and the level's table markup."""
from __future__ import annotations
-from typing import NamedTuple
+from typing import Literal, NamedTuple
+from repowise.cli.ui.brand import ERR, OK, WARN
+from repowise.cli.ui.glyphs import glyph
-class DoctorCheck(NamedTuple):
- name: str
- ok: bool
- detail: str = ""
+Level = Literal["ok", "warn", "fail"]
-def _check(name: str, ok: bool, detail: str = "") -> DoctorCheck:
- return DoctorCheck(name, ok, detail)
+class DoctorCheck(NamedTuple):
+ """One doctor row.
+ ``id`` is the stable machine key (lowercase kebab); ``name`` is display
+ text and may change. ``ok`` is False only when ``level`` is ``fail``, so
+ a ``warn`` row never fails the run. ``fix`` is the exact command that
+ resolves the row, when one is known. Build rows with :func:`_check`.
+ """
-def _status_markup(ok: bool) -> str:
- return "[green]OK[/green]" if ok else "[red]FAIL[/red]"
+ name: str
+ ok: bool
+ detail: str = ""
+ id: str = ""
+ level: Level = "ok"
+ fix: str | None = None
+
+
+def _check(
+ name: str,
+ ok: bool,
+ detail: str = "",
+ *,
+ check_id: str,
+ warn: bool = False,
+ fix: str | None = None,
+) -> DoctorCheck:
+ """A row; *warn* marks a passing row the user should still look at."""
+ level: Level = "fail" if not ok else ("warn" if warn else "ok")
+ return DoctorCheck(name, ok, detail, check_id, level, fix)
+
+
+_LEVEL_MARKUP = {
+ "ok": (OK, "ok", "OK"),
+ "warn": (WARN, "warn", "WARN"),
+ "fail": (ERR, "fail", "FAIL"),
+}
+
+
+def _status_markup(level: Level) -> str:
+ style, glyph_name, label = _LEVEL_MARKUP[level]
+ return f"[{style}]{glyph(glyph_name)} {label}[/{style}]"
diff --git a/packages/cli/src/repowise/cli/commands/doctor_cmd/command.py b/packages/cli/src/repowise/cli/commands/doctor_cmd/command.py
index ec3b6d31a..0f71893b8 100644
--- a/packages/cli/src/repowise/cli/commands/doctor_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/doctor_cmd/command.py
@@ -119,7 +119,8 @@ def doctor_command(
)
ok, checks = _run_repo_checks(abs_path, repair, fmt=fmt)
overall_ok = overall_ok and ok
- all_checks.extend(DoctorCheck(f"{entry.alias}: {c.name}", c.ok, c.detail) for c in checks)
+ # The alias goes on the display name only; ids stay the check's own.
+ all_checks.extend(c._replace(name=f"{entry.alias}: {c.name}") for c in checks)
if fmt != "table":
all_ok = overall_ok and not ws_issues and not not_indexed
diff --git a/packages/cli/src/repowise/cli/commands/doctor_cmd/mcp_smoke.py b/packages/cli/src/repowise/cli/commands/doctor_cmd/mcp_smoke.py
index 662c90723..e47449df9 100644
--- a/packages/cli/src/repowise/cli/commands/doctor_cmd/mcp_smoke.py
+++ b/packages/cli/src/repowise/cli/commands/doctor_cmd/mcp_smoke.py
@@ -66,6 +66,7 @@ _EXIT_GRACE_S = 5.0
_STDERR_DRAIN_GRACE_S = 2.0
CHECK_NAME = "MCP server responds"
+CHECK_ID = "mcp-responds"
def _read_response(stdout, request_id: int, deadline: float) -> dict | None:
@@ -193,7 +194,7 @@ def mcp_smoke_check(command: str, args: list[str], env: dict | None = None) -> D
env=child_env,
)
except OSError as exc:
- return _check(CHECK_NAME, False, f"could not launch {command}: {exc}")
+ return _check(CHECK_NAME, False, f"could not launch {command}: {exc}", check_id=CHECK_ID)
stderr_ring, stderr_reader = _drain_stderr(proc)
try:
@@ -203,11 +204,15 @@ def mcp_smoke_check(command: str, args: list[str], env: dict | None = None) -> D
if response is not None and "result" in response:
server = response["result"].get("serverInfo") or {}
return _check(
- CHECK_NAME, True, f"{server.get('name', 'repowise')} initialised in {elapsed_ms}ms"
+ CHECK_NAME,
+ True,
+ f"{server.get('name', 'repowise')} initialised in {elapsed_ms}ms",
+ check_id=CHECK_ID,
)
if response is not None:
error = response.get("error") or {}
- return _check(CHECK_NAME, False, f"initialize failed: {error.get('message', response)}")
+ detail = f"initialize failed: {error.get('message', response)}"
+ return _check(CHECK_NAME, False, detail, check_id=CHECK_ID)
# No response. Whether the process is gone (the crash-loop case) or up
# and mute changes the remedy, so the detail says which.
@@ -220,6 +225,7 @@ def mcp_smoke_check(command: str, args: list[str], env: dict | None = None) -> D
CHECK_NAME,
False,
f"no initialize response within {int(_SMOKE_TIMEOUT_S)}s (still running)",
+ check_id=CHECK_ID,
)
detail = f"server exited with code {exit_code}"
# The child has exited; give the reader a moment to drain the pipe's
@@ -228,6 +234,6 @@ def mcp_smoke_check(command: str, args: list[str], env: dict | None = None) -> D
stderr = _stderr_tail(stderr_ring)
if stderr:
detail += f": {stderr}"
- return _check(CHECK_NAME, False, detail)
+ return _check(CHECK_NAME, False, detail, check_id=CHECK_ID)
finally:
_shutdown(proc)
diff --git a/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py b/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py
index 703c9a798..211174475 100644
--- a/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py
+++ b/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py
@@ -70,10 +70,29 @@ __all__ = [
"_stale_page_counts",
"_stale_page_guidance",
"_unregistered_detail",
+ "collect_repo_checks",
"console",
]
+def _collect(repo_path: _DoctorPath) -> tuple[CheckContext, list[DoctorCheck]]:
+ ctx = CheckContext(repo_path=repo_path, repowise_dir=get_repowise_dir(repo_path))
+ checks: list[DoctorCheck] = []
+ for group in (core_checks, provider_checks, store_checks, integration_checks):
+ checks.extend(group(ctx))
+ return ctx, checks
+
+
+def collect_repo_checks(repo_path: _DoctorPath) -> list[DoctorCheck]:
+ """Every per-repo check for *repo_path*, in table order, without printing.
+
+ Read-only: nothing is repaired. Each row carries a stable ``id``, a
+ ``level`` and, when known, the ``fix`` command; ``repowise doctor
+ --format json`` serialises exactly these rows.
+ """
+ return _collect(repo_path)[1]
+
+
def _run_repo_checks(
repo_path: _DoctorPath, repair: bool, *, fmt: str = "table"
) -> tuple[bool, list[DoctorCheck]]:
@@ -85,10 +104,7 @@ def _run_repo_checks(
is also skipped; callers must not pass ``repair=True`` with a
non-table format).
"""
- ctx = CheckContext(repo_path=repo_path, repowise_dir=get_repowise_dir(repo_path))
- checks: list[DoctorCheck] = []
- for group in (core_checks, provider_checks, store_checks, integration_checks):
- checks.extend(group(ctx))
+ ctx, checks = _collect(repo_path)
all_ok = all(c.ok for c in checks)
if fmt != "table":
diff --git a/tests/unit/cli/test_doctor_check_ids.py b/tests/unit/cli/test_doctor_check_ids.py
new file mode 100644
index 000000000..52a0f5e3f
--- /dev/null
+++ b/tests/unit/cli/test_doctor_check_ids.py
@@ -0,0 +1,230 @@
+"""Doctor check ids, levels and fixes.
+
+A server and a web Setup page key on ``id``, so the set of ids is pinned here:
+renaming a display name must not move an id, and a changed id is a breaking
+change someone has to make on purpose.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import re
+import subprocess
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from repowise.cli.commands import doctor_cmd
+from repowise.cli.commands.doctor_cmd import collect_repo_checks, doctor_command, repo_checks
+from repowise.cli.commands.doctor_cmd._checks import integrations, providers
+from repowise.cli.commands.doctor_cmd._types import _check
+
+# "*" stands for a per-target or per-language suffix.
+PINNED_IDS = {
+ "agent-*",
+ "agent-integrations",
+ "attribution-notes",
+ "claude-code-mcp-entry",
+ "coordinator-drift",
+ "database",
+ "distill-config",
+ "distill-rewrite-hook",
+ "events-config",
+ "fts-index-sync",
+ "git-repository",
+ "grammar-*",
+ "hosted-account",
+ "llm-provider",
+ "mcp-responds",
+ "omission-store",
+ "post-commit-hook",
+ "provider-config",
+ "providers",
+ "repowise-dir",
+ "stale-pages",
+ "state-json",
+ "store-consistency",
+ "store-format",
+ "vector-store",
+ "vector-store-sync",
+}
+
+_KEBAB = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+_ID_NAMES = {"check_id", "CHECK_ID"}
+_PACKAGE = Path(doctor_cmd.__file__).parent
+
+
+def _id_value(node: ast.expr) -> str | None:
+ if isinstance(node, ast.Constant) and isinstance(node.value, str):
+ return node.value
+ if isinstance(node, ast.JoinedStr):
+ head = node.values[0]
+ assert isinstance(head, ast.Constant), "an f-string id must start with a literal"
+ return f"{head.value}*"
+ return None
+
+
+def _bound_pairs(target: ast.expr, value: ast.expr) -> list[tuple[ast.expr, ast.expr]]:
+ if isinstance(target, ast.Tuple) and isinstance(value, ast.Tuple):
+ return list(zip(target.elts, value.elts, strict=True))
+ return [(target, value)]
+
+
+def _node_ids(node: ast.AST) -> list[str | None]:
+ if isinstance(node, ast.keyword) and node.arg == "check_id":
+ return [_id_value(node.value)]
+ if not isinstance(node, ast.Assign):
+ return []
+ pairs = [pair for target in node.targets for pair in _bound_pairs(target, node.value)]
+ return [
+ _id_value(value)
+ for name, value in pairs
+ if isinstance(name, ast.Name) and name.id in _ID_NAMES
+ ]
+
+
+def _ids_in(tree: ast.AST) -> set[str]:
+ """Every literal id: ``check_id=`` arguments and ``check_id``/``CHECK_ID`` assignments.
+
+ A keyword passing a variable through yields None here; the assignment
+ that bound it is what carries the literal.
+ """
+ return {i for node in ast.walk(tree) for i in _node_ids(node) if i}
+
+
+def _source_trees() -> list[ast.AST]:
+ return [ast.parse(p.read_text(encoding="utf-8")) for p in sorted(_PACKAGE.rglob("*.py"))]
+
+
+def test_check_ids_are_pinned() -> None:
+ ids: set[str] = set()
+ for tree in _source_trees():
+ ids |= _ids_in(tree)
+ assert ids == PINNED_IDS
+
+
+def test_check_ids_are_kebab_case() -> None:
+ for check_id in PINNED_IDS:
+ assert _KEBAB.match(check_id.removesuffix("-*")), check_id
+
+
+def test_every_check_call_names_an_id() -> None:
+ for tree in _source_trees():
+ for node in ast.walk(tree):
+ if (
+ isinstance(node, ast.Call)
+ and isinstance(node.func, ast.Name)
+ and node.func.id == "_check"
+ ):
+ assert any(k.arg == "check_id" for k in node.keywords), ast.unparse(node)
+
+
+def test_agent_row_ids_are_kebab_case() -> None:
+ from repowise.cli.agent_targets.registry import all_targets
+
+ for target in all_targets():
+ assert _KEBAB.match(f"agent-{target.id}"), target.id
+
+
+def _git_repo(path: Path) -> Path:
+ subprocess.run(["git", "init", "-q"], cwd=path, check=True)
+ return path
+
+
+def no_mcp_launch(monkeypatch):
+ """Keep the run off the machine's real MCP registration and hosted account."""
+ integrations._mcp_responds_check.cache_clear()
+ monkeypatch.setattr(integrations, "_registered_mcp_entry", lambda: None)
+ monkeypatch.setattr(
+ providers,
+ "_hosted_account_check",
+ lambda: _check("Hosted account", True, "", check_id="hosted-account"),
+ )
+ yield
+ integrations._mcp_responds_check.cache_clear()
+
+
+def test_collected_rows_have_unique_ids_and_consistent_levels(
+ tmp_path: Path, no_mcp_launch
+) -> None:
+ checks = collect_repo_checks(_git_repo(tmp_path))
+ ids = [c.id for c in checks]
+ assert len(ids) == len(set(ids))
+ for c in checks:
+ assert _KEBAB.match(c.id), c
+ assert c.level in ("ok", "warn", "fail")
+ assert c.ok is (c.level != "fail")
+
+
+def test_missing_post_commit_hook_is_a_warn_with_the_install_command(tmp_path: Path) -> None:
+ row = repo_checks._autosync_hook_check(_git_repo(tmp_path))
+ assert (row.id, row.level, row.ok) == ("post-commit-hook", "warn", True)
+ assert row.fix == "repowise hook install"
+
+
+def test_installed_post_commit_hook_is_ok(tmp_path: Path) -> None:
+ from repowise.cli import hooks
+
+ repo = _git_repo(tmp_path)
+ hooks.install(repo)
+ row = repo_checks._autosync_hook_check(repo)
+ assert (row.level, row.fix) == ("ok", None)
+
+
+def test_missing_repowise_dir_is_a_fail_with_the_init_command(tmp_path: Path) -> None:
+ row = repo_checks._repowise_dir_check(tmp_path / ".repowise")
+ assert (row.id, row.level, row.ok) == ("repowise-dir", "fail", False)
+ assert row.fix == "repowise init"
+
+
+def test_registration_serving_another_repo_is_a_warn(tmp_path: Path, monkeypatch) -> None:
+ other = tmp_path / "other"
+ other.mkdir()
+ entry = {"command": "repowise", "args": ["mcp", str(other), "--transport", "stdio"]}
+ monkeypatch.setattr(integrations, "_registered_mcp_entry", lambda: entry)
+ monkeypatch.setattr(integrations, "_registers_repo", lambda _t, _r: False)
+ row, wedged = integrations._claude_registration_check(tmp_path)
+ assert (row.id, row.level, wedged) == ("claude-code-mcp-entry", "warn", False)
+ assert row.fix == "repowise agents add --target=claude-code --scope=project"
+
+
+ ("settings", "level"), [("{not json", "warn"), (None, "ok")], ids=["unparseable", "absent"]
+)
+def test_unregistered_entry_warns_only_when_settings_cannot_be_parsed(
+ tmp_path: Path, monkeypatch, settings: str | None, level: str
+) -> None:
+ from repowise.cli.editor_integrations import claude_config
+
+ settings_path = tmp_path / "settings.json"
+ if settings is not None:
+ settings_path.write_text(settings, encoding="utf-8")
+ monkeypatch.setattr(claude_config, "_claude_code_settings_path", lambda: settings_path)
+ monkeypatch.setattr(integrations, "_registered_mcp_entry", lambda: None)
+ row, wedged = integrations._claude_registration_check(tmp_path)
+ assert (row.id, row.level, row.ok, wedged) == ("claude-code-mcp-entry", level, True, False)
+
+
+def test_json_rows_carry_id_level_and_fix(tmp_path: Path, no_mcp_launch) -> None:
+ result = CliRunner().invoke(
+ doctor_command, [str(_git_repo(tmp_path)), "--no-workspace", "--format", "json"]
+ )
+ payload = json.loads(result.output[result.output.index("{") :])
+ assert set(payload) == {"ok", "checks"}
+ for c in payload["checks"]:
+ assert set(c) == {"id", "name", "ok", "level", "detail", "fix"}
+ by_id = {c["id"]: c for c in payload["checks"]}
+ assert by_id["repowise-dir"]["level"] == "fail"
+ assert by_id["repowise-dir"]["fix"] == "repowise init"
+ assert by_id["post-commit-hook"]["level"] == "warn"
+ assert by_id["git-repository"] == {
+ "id": "git-repository",
+ "name": "Git repository",
+ "ok": True,
+ "level": "ok",
+ "detail": str(tmp_path),
+ "fix": None,
+ }
diff --git a/tests/unit/cli/test_doctor_check_order.py b/tests/unit/cli/test_doctor_check_order.py
index c7f126a92..44b377fa4 100644
--- a/tests/unit/cli/test_doctor_check_order.py
+++ b/tests/unit/cli/test_doctor_check_order.py
@@ -101,21 +101,36 @@ async def _build(
def env(monkeypatch) -> dict:
"""Stub machine-dependent rows and record console output in order."""
st: dict = {"printed": [], "wedged": False, "refresh": False}
- monkeypatch.setattr(core, "_autosync_hook_check", lambda _p: _check("<hook>", True, ""))
+ monkeypatch.setattr(
+ core, "_autosync_hook_check", lambda _p: _check("<hook>", True, "", check_id="hook")
+ )
monkeypatch.setattr(core, "_attribution_notes_check", lambda _p: None)
monkeypatch.setattr(core, "_events_config_check", lambda _p: None)
- monkeypatch.setattr(providers, "_provider_checks", lambda _p: [_check("<provider>", True, "")])
- monkeypatch.setattr(integrations, "_distill_checks", lambda _p: [_check("<distill>", True, "")])
+ monkeypatch.setattr(
+ providers,
+ "_provider_checks",
+ lambda _p: [_check("<provider>", True, "", check_id="provider")],
+ )
+ monkeypatch.setattr(
+ integrations,
+ "_distill_checks",
+ lambda _p: [_check("<distill>", True, "", check_id="distill")],
+ )
monkeypatch.setattr(
integrations,
"_claude_registration_check",
- lambda _p: (_check("<registration>", not st["wedged"], ""), st["wedged"]),
+ lambda _p: (
+ _check("<registration>", not st["wedged"], "", check_id="registration"),
+ st["wedged"],
+ ),
+ )
+ monkeypatch.setattr(
+ integrations, "_mcp_responds_check", lambda: _check("<mcp>", True, "", check_id="mcp")
)
- monkeypatch.setattr(integrations, "_mcp_responds_check", lambda: _check("<mcp>", True, ""))
monkeypatch.setattr(
integrations,
"_agent_target_checks",
- lambda _p: ([_check("<agent>", not st["refresh"], "")], st["refresh"]),
+ lambda _p: ([_check("<agent>", not st["refresh"], "", check_id="agent")], st["refresh"]),
)
monkeypatch.setattr(_render, "_advise_claude_md_stamp", lambda *_a: st["printed"].append("<stamp>"))
monkeypatch.setattr("repowise.cli.platform.credentials.load", lambda: None)
@@ -174,10 +189,10 @@ def test_healthy_store_rows_and_order(env, tmp_path) -> None:
def test_optional_rows_slot_in_after_the_hook(env, monkeypatch, tmp_path) -> None:
monkeypatch.setattr(
- core, "_attribution_notes_check", lambda _p: _check("<notes>", True, "")
+ core, "_attribution_notes_check", lambda _p: _check("<notes>", True, "", check_id="notes")
)
monkeypatch.setattr(
- core, "_events_config_check", lambda _p: _check("<events>", False, "")
+ core, "_events_config_check", lambda _p: _check("<events>", False, "", check_id="events")
)
repo = asyncio.run(_build(tmp_path))
names = [r[0] for r in _rows(repo)]
@@ -296,7 +311,13 @@ def test_table_healthy_prints_table_stamp_then_pass(env, tmp_path) -> None:
repo = asyncio.run(_build(tmp_path))
ok, _ = repo_checks._run_repo_checks(repo, repair=False)
assert ok is True
- assert _texts(env) == ["<table>", "<stamp>", "[bold green]All checks passed![/bold green]"]
+ # The fixture's store predates a capability, so the store-format row warns;
+ # a warn still passes and is counted on the summary line.
+ texts = _texts(env)
+ assert texts[:2] == ["<table>", "<stamp>"]
+ assert texts[2].startswith("[bold green]All checks passed[/bold green]")
+ assert "1 warning(s)" in texts[2]
+ assert len(texts) == 3
def test_repair_with_nothing_to_do(env, tmp_path) -> None:
diff --git a/tests/unit/cli/test_doctor_json.py b/tests/unit/cli/test_doctor_json.py
index b76ad9c27..d354b27eb 100644
--- a/tests/unit/cli/test_doctor_json.py
+++ b/tests/unit/cli/test_doctor_json.py
@@ -18,14 +18,14 @@ def _git_init(p: Path) -> None:
class TestCheckCarriesOk:
def test_check_returns_named_tuple_with_ok(self) -> None:
- c = _check("Some check", True, "all good")
+ c = _check("Some check", True, "all good", check_id="some-check")
assert isinstance(c, DoctorCheck)
assert c.name == "Some check"
assert c.ok is True
assert c.detail == "all good"
def test_check_failure(self) -> None:
- c = _check("Some check", False, "broken")
+ c = _check("Some check", False, "broken", check_id="some-check")
assert c.ok is False
diff --git a/tests/unit/cli/test_doctor_store_format.py b/tests/unit/cli/test_doctor_store_format.py
index 6b03031ac..dbb64821e 100644
--- a/tests/unit/cli/test_doctor_store_format.py
+++ b/tests/unit/cli/test_doctor_store_format.py
@@ -2,8 +2,8 @@
An un-upgraded store learns from ``doctor`` that a re-index is available, since
the once-per-store update nag may already have been shown and suppressed. The
-row is always OK (a pre-upgrade store works degraded, it is not broken) and
-carries the exact command.
+row never fails (a pre-upgrade store works degraded, it is not broken): it is a
+warn carrying the exact command.
"""
from __future__ import annotations
@@ -48,8 +48,10 @@ def _store_format_row(tmp_path: Path) -> dict:
def test_doctor_flags_reindex_for_old_store(tmp_path: Path) -> None:
row = _store_format_row(_repo_with_store(tmp_path, 1))
- # Reported OK (degraded, not broken) with an actionable command.
+ # A warn (degraded, not broken) with an actionable command.
assert row["ok"] is True
+ assert row["level"] == "warn"
+ assert row["fix"] == "repowise init --force"
assert "repowise init --force" in row["detail"]
# Plain text only: no Rich markup leaking through the JSON surface.
assert "[" not in row["detail"] or "]" not in row["detail"]
@@ -58,4 +60,5 @@ def test_doctor_flags_reindex_for_old_store(tmp_path: Path) -> None:
def test_doctor_reports_current_store_as_current(tmp_path: Path) -> None:
row = _store_format_row(_repo_with_store(tmp_path, STORE_FORMAT_VERSION))
assert row["ok"] is True
+ assert row["level"] == "ok"
assert row["detail"] == "Current"