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.

docs(examples): add health-coverage walkthrough (#1020)

Felix-Ayush13d8e9de5c7f
diff --git a/docs/layers/CODE_HEALTH.md b/docs/layers/CODE_HEALTH.md
index 451fe8f7f..5b6d2522d 100644
--- a/docs/layers/CODE_HEALTH.md
+++ b/docs/layers/CODE_HEALTH.md
@@ -35,6 +35,9 @@ repowise health # KPIs + 20 worst-scoring files + top findings
repowise update # re-score only changed files on each subsequent run
```
+Copy-paste walkthrough (health + coverage + impacted-tests):
+[examples/health-coverage/](../../examples/health-coverage/).
+
Open `http://localhost:7777/repos/<id>/health` for the dashboard once the
local server is running (`repowise serve`).
diff --git a/docs/layers/TEST_INTELLIGENCE.md b/docs/layers/TEST_INTELLIGENCE.md
index 3dfd9f381..d1975c50d 100644
--- a/docs/layers/TEST_INTELLIGENCE.md
+++ b/docs/layers/TEST_INTELLIGENCE.md
@@ -25,6 +25,8 @@ repowise impacted-tests main..HEAD # the tests guarding this branch
repowise impacted-tests main..HEAD --format list | xargs pytest
```
+Longer walkthrough: [examples/health-coverage/](../../examples/health-coverage/).
+
```
repowise coverage status
diff --git a/examples/README.md b/examples/README.md
index c00eb5a1c..ee2fc0c32 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -8,6 +8,7 @@ self-contained README under `examples/<name>/`.
| Example | What it shows |
|---------|----------------|
| [codex/](codex/) | Codex CLI setup: `repowise init --codex`, smoke checks, local plugin install |
+| [health-coverage/](health-coverage/) | Code health, coverage ingest, and impacted-tests (no LLM key) |
## Conventions
@@ -22,3 +23,5 @@ self-contained README under `examples/<name>/`.
- [CLI reference](../docs/reference/CLI_REFERENCE.md)
- [Codex integration](../docs/agent/CODEX.md)
- [OpenCode integration](../docs/agent/OPENCODE.md)
+- [Code health](../docs/layers/CODE_HEALTH.md)
+- [Test intelligence](../docs/layers/TEST_INTELLIGENCE.md)
diff --git a/examples/health-coverage/README.md b/examples/health-coverage/README.md
new file mode 100644
index 000000000..c84388417
--- /dev/null
+++ b/examples/health-coverage/README.md
@@ -0,0 +1,80 @@
+# Health + Coverage Example
+
+Walk through code-health scoring, coverage ingestion, and impacted-tests
+using real CLI commands. No LLM key required for these steps.
+
+## Prerequisites
+
+1. A git repository with Python (or another supported language) sources.
+2. `repowise` on `PATH` (`uv tool install repowise` or from this repo:
+ `uv sync --all-packages`).
+3. Index the repo once (index-only is enough — health needs no wiki LLM):
+
+```bash
+cd /path/to/your-repo
+repowise init --index-only --yes
+```
+
+## 1. Read code health
+
+```bash
+repowise health # KPIs + lowest-scoring files
+repowise health --refactoring-targets # ranked by impact / effort
+repowise health --trend # recent snapshots + declining alerts
+repowise health --format json | head # machine-readable
+```
+
+Point at one file or a module prefix when you already know the area:
+
+```bash
+repowise health --file path/to/file.py
+repowise health --module packages/server
+```
+
+## 2. Ingest coverage
+
+Produce a coverage report with your usual test runner, then ingest it:
+
+```bash
+# Examples of reports Repowise accepts:
+# coverage.lcov / lcov.info (LCOV)
+# coverage.xml (Cobertura / Clover)
+# .coverage (coverage.py — also builds the per-test map)
+
+repowise coverage add # auto-discover common report paths
+repowise coverage add coverage.lcov
+repowise coverage add .coverage # per-file coverage + per-test map
+repowise coverage status
+```
+
+After ingestion, `repowise health` folds coverage into untested-hotspot
+markers automatically — no extra flag.
+
+## 3. Run only the tests a change exercises
+
+With a per-test map (from a coverage.py `.coverage` with contexts, or an
+equivalent report), map a diff to the tests that touch those lines:
+
+```bash
+repowise impacted-tests # staged changes (default)
+repowise impacted-tests main..HEAD
+repowise impacted-tests main..HEAD --format list | xargs pytest
+```
+
+If no map is ingested, the command tells you to run `repowise coverage add`
+on a report that includes per-test contexts — it does not invent an empty
+"no tests needed" result.
+
+## Smoke checklist
+
+| Step | Expected |
+|------|----------|
+| `repowise health` | Table/KPIs without an API key |
+| `repowise coverage add` on a real report | `coverage status` shows ingested data |
+| `repowise impacted-tests main..HEAD` | Test ids or an explicit "ingest coverage" prompt |
+
+## Related docs
+
+- [Code health](../../docs/layers/CODE_HEALTH.md)
+- [Test intelligence](../../docs/layers/TEST_INTELLIGENCE.md)
+- [CLI: health / coverage / impacted-tests](../../docs/reference/CLI_REFERENCE.md)