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(health): ingest normalized-JSON coverage and surface coverage metrics (#309)

Raghav Chamadiyae276f8149fba
diff --git a/docs/CODE_HEALTH.md b/docs/CODE_HEALTH.md
index e14f59050..279ec848b 100644
--- a/docs/CODE_HEALTH.md
+++ b/docs/CODE_HEALTH.md
@@ -207,6 +207,16 @@ repowise health \
--coverage frontend/lcov.info
```
+Formats are auto-detected: **LCOV**, **Cobertura** XML, **Clover** XML, and a
+**normalized JSON** (`repowise-coverage-v1`) keyed by repo-relative path — the
+last lets you feed coverage from any runner once it's mapped to one shape:
+
+```json
+{ "format": "repowise-coverage-v1",
+ "files": { "src/foo.py": { "line_coverage_pct": 87.5,
+ "total_coverable_lines": 40 } } }
+```
+
Coverage data feeds into `untested_hotspot` and `coverage_gap`, and shows up
on the `/repos/<id>/health/coverage` dashboard.
@@ -290,7 +300,7 @@ Health: 7.4 (avg) · 6.2 (hotspots) · 2.1 (worst: payments/processor.ts)
| Code health score (1–10) | ✅ 23 biomarkers | ✅ 25–30 | ❌ | ❌ |
| Brain Method detection | ✅ | ✅ | ❌ | ❌ |
| Low cohesion (LCOM4) / god class | ✅ | ✅ | ❌ | ❌ |
-| Test coverage intelligence | ✅ LCOV/Cobertura/Clover | ❌ | ❌ | ❌ |
+| Test coverage intelligence | ✅ LCOV/Cobertura/Clover/JSON | ❌ | ❌ | ❌ |
| Untested hotspot detection | ✅ coverage × hotspot | ❌ | ❌ | ❌ |
| DRY violation detection | ✅ native (no npm) | ✅ | ❌ | ❌ |
| Health trend tracking | ✅ | ✅ | ❌ | ❌ |
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index 21ac0b145..205c274d4 100644
--- a/docs/architecture/code-health.md
+++ b/docs/architecture/code-health.md
@@ -79,7 +79,8 @@ analysis/health/
│ ├── detector.py # format auto-detect + test-file heuristic
│ ├── lcov.py # LCOV parser (stdlib only)
│ ├── cobertura.py # Cobertura XML parser
-│ └── clover.py # Clover XML parser
+│ ├── clover.py # Clover XML parser
+│ └── repowise_json.py # normalized repowise-coverage-v1 JSON parser
│
├── duplication/ # native Rabin-Karp clone detection
│ ├── README.md
@@ -188,7 +189,7 @@ tests/unit/health/ # 99+ tests
├── test_organizational_biomarkers.py
├── test_dry_violation.py
├── test_duplication.py # tokenizer, hash, detector
-├── test_coverage_parsers.py # LCOV/Cobertura/Clover
+├── test_coverage_parsers.py # LCOV/Cobertura/Clover/JSON
├── test_scoring.py # category caps, clamping
├── test_scoring_snapshot.py # stability snapshot — locks caps + deductions
├── test_health_config.py # .repowise/health-rules.json
@@ -738,7 +739,7 @@ Other perf notes:
| `tests/unit/health/test_complexity_walker.py` | Per-language CCN, nesting, cognitive assertions on handcrafted fixtures |
| `tests/unit/health/test_<biomarker>.py` | Each biomarker — positive in two languages + one negative |
| `tests/unit/health/test_duplication.py` | Tokenizer normalization, rolling-hash determinism, co-change weighting |
-| `tests/unit/health/test_coverage_parsers.py` | LCOV / Cobertura / Clover happy paths + edge cases |
+| `tests/unit/health/test_coverage_parsers.py` | LCOV / Cobertura / Clover / repowise-JSON happy paths + edge cases |
| `tests/unit/health/test_scoring.py` | Deduction caps, clamping, KPI math |
| `tests/unit/health/test_scoring_snapshot.py` | **Stability guard** — caps, severity table, biomarker→category mapping, two known fixture scores |
| `tests/unit/health/test_trends.py` | Declining + predicted alerts, ordering |
diff --git a/packages/cli/src/repowise/cli/commands/health_cmd.py b/packages/cli/src/repowise/cli/commands/health_cmd.py
index ed9c978eb..d0be19e40 100644
--- a/packages/cli/src/repowise/cli/commands/health_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/health_cmd.py
@@ -275,6 +275,9 @@ def health_command(
"max_nesting": m.max_nesting,
"nloc": m.nloc,
"has_test_file": m.has_test_file,
+ "line_coverage_pct": m.line_coverage_pct,
+ "branch_coverage_pct": m.branch_coverage_pct,
+ "duplication_pct": m.duplication_pct,
}
for m in metrics_sorted
],
diff --git a/packages/core/src/repowise/core/analysis/health/coverage/README.md b/packages/core/src/repowise/core/analysis/health/coverage/README.md
index 03c63077b..baa462581 100644
--- a/packages/core/src/repowise/core/analysis/health/coverage/README.md
+++ b/packages/core/src/repowise/core/analysis/health/coverage/README.md
@@ -14,9 +14,36 @@ from repowise.core.analysis.health.coverage import (
- `parse(text, format=None)` → `CoverageReport`. Auto-detects format
when `format` is ``None``; pass an explicit ``"lcov" | "cobertura" |
- "clover"`` to override.
-- `parse_lcov(text)`, `parse_cobertura(text)`, `parse_clover(text)` —
- format-specific entry points (used by tests / programmatic callers).
+ "clover" | "repowise-json"`` to override.
+- `parse_lcov(text)`, `parse_cobertura(text)`, `parse_clover(text)`,
+ `parse_repowise_json(text)` — format-specific entry points (used by
+ tests / programmatic callers).
+
+### Repowise normalized JSON (`repowise-coverage-v1`)
+
+A small, explicit JSON shape so coverage from *any* runner can be
+normalized once (keyed by repo-relative POSIX path) and fed to
+`repowise health --coverage`:
+
+```json
+{
+ "format": "repowise-coverage-v1",
+ "commit_sha": "abc123",
+ "files": {
+ "src/foo.py": {
+ "line_coverage_pct": 87.5,
+ "branch_coverage_pct": 70.0,
+ "covered_lines": [1, 2, 5],
+ "total_coverable_lines": 40
+ }
+ }
+}
+```
+
+`files` may also be a list of the same objects, each with its own
+`file_path`. Tolerant: any two of `(line_coverage_pct, covered_lines,
+total_coverable_lines)` pin a file down; an entry that anchors none is
+skipped (absent ≠ zero).
- `detect_format(text)` — returns the sniffed format or ``None``.
- `is_test_file(path, source=None)` — path + optional content heuristic.
- `paired_test_file(path, all_paths)` — find the conventional test
diff --git a/packages/core/src/repowise/core/analysis/health/coverage/__init__.py b/packages/core/src/repowise/core/analysis/health/coverage/__init__.py
index 137b08532..69ffcc5ed 100644
--- a/packages/core/src/repowise/core/analysis/health/coverage/__init__.py
+++ b/packages/core/src/repowise/core/analysis/health/coverage/__init__.py
@@ -7,6 +7,7 @@ from .cobertura import parse_cobertura
from .detector import detect_format, is_test_file, paired_test_file, parse
from .lcov import parse_lcov
from .model import CoverageReport, FileCoverage
+from .repowise_json import parse_repowise_json
__all__ = [
"CoverageReport",
@@ -18,4 +19,5 @@ __all__ = [
"parse_clover",
"parse_cobertura",
"parse_lcov",
+ "parse_repowise_json",
]
diff --git a/packages/core/src/repowise/core/analysis/health/coverage/detector.py b/packages/core/src/repowise/core/analysis/health/coverage/detector.py
index 824c3b577..4f05f1ea5 100644
--- a/packages/core/src/repowise/core/analysis/health/coverage/detector.py
+++ b/packages/core/src/repowise/core/analysis/health/coverage/detector.py
@@ -25,6 +25,7 @@ from .clover import parse_clover
from .cobertura import parse_cobertura
from .lcov import parse_lcov
from .model import CoverageReport
+from .repowise_json import parse_repowise_json
# Test-file globs / suffixes — checked against POSIX-normalized paths.
_TEST_PATH_FRAGMENTS = (
@@ -74,6 +75,12 @@ def detect_format(text: str) -> str | None:
sample = text.lstrip()[:2048]
if not sample:
return None
+ if sample.startswith("{"):
+ # Repowise normalized JSON — tagged by ``format`` or recognizable by its
+ # per-file coverage keys. Checked before LCOV/XML since none start with ``{``.
+ if "repowise-coverage" in sample or "line_coverage_pct" in sample:
+ return "repowise-json"
+ return None
if sample.startswith(("TN:", "SF:")) or _LCOV_LINE_RE.match(sample):
return "lcov"
if sample.startswith("<?xml") or sample.startswith("<"):
@@ -96,6 +103,8 @@ def parse(text: str, *, format: str | None = None) -> CoverageReport:
return parse_cobertura(text)
if fmt == "clover":
return parse_clover(text)
+ if fmt in ("repowise-json", "json"):
+ return parse_repowise_json(text)
return CoverageReport(source_format="unknown")
diff --git a/packages/core/src/repowise/core/analysis/health/coverage/repowise_json.py b/packages/core/src/repowise/core/analysis/health/coverage/repowise_json.py
new file mode 100644
index 000000000..ef4a2e320
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/coverage/repowise_json.py
@@ -0,0 +1,115 @@
+"""Repowise normalized-JSON coverage parser.
+
+A small, explicit JSON schema so coverage produced by *any* runner
+(``pytest-cov``, ``c8``/``nyc``, ``cargo-llvm-cov``, ``go test
+-coverprofile``, JaCoCo, coverlet, or a Codecov/Coveralls scrape) can be
+normalized once to a single shape and fed to ``repowise health
+--coverage``. Keyed by **repo-relative POSIX path**.
+
+Schema (``format: "repowise-coverage-v1"``)::
+
+ {
+ "format": "repowise-coverage-v1",
+ "commit_sha": "abc123", # optional
+ "files": {
+ "src/foo.py": {
+ "line_coverage_pct": 87.5, # 0..100; derivable from covered/total
+ "branch_coverage_pct": 70.0, # optional, may be null
+ "covered_lines": [1, 2, 5], # optional explicit hit set
+ "total_coverable_lines": 40 # optional; derivable from pct+covered
+ },
+ ...
+ }
+ }
+
+``files`` may also be a **list** of the same per-file objects, each
+carrying its own ``file_path``/``path`` — both shapes parse identically.
+
+Tolerant by design: a file entry needs only enough to pin down a line
+percentage. When ``line_coverage_pct`` is absent it is derived from
+``covered_lines`` / ``total_coverable_lines``; when ``total_coverable_lines``
+is absent it is derived from the percentage and the covered set. An entry
+that pins down neither is skipped (absent, *not* zero — see Phase-7 §5).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .model import CoverageReport, FileCoverage
+
+_FORMAT_TAG = "repowise-coverage-v1"
+
+
+def parse_repowise_json(text: str) -> CoverageReport:
+ try:
+ data = json.loads(text)
+ except (ValueError, TypeError):
+ return CoverageReport(source_format="unknown")
+ if not isinstance(data, dict):
+ return CoverageReport(source_format="unknown")
+
+ raw_files = data.get("files")
+ entries: list[tuple[str | None, dict[str, Any]]] = []
+ if isinstance(raw_files, dict):
+ entries = [(str(k), v) for k, v in raw_files.items() if isinstance(v, dict)]
+ elif isinstance(raw_files, list):
+ entries = [(None, v) for v in raw_files if isinstance(v, dict)]
+
+ files: list[FileCoverage] = []
+ for key, entry in entries:
+ fc = _parse_entry(key, entry)
+ if fc is not None:
+ files.append(fc)
+
+ return CoverageReport(
+ source_format="repowise-json",
+ files=files,
+ commit_sha=data.get("commit_sha") or None,
+ )
+
+
+def _parse_entry(key: str | None, entry: dict[str, Any]) -> FileCoverage | None:
+ path = key or entry.get("file_path") or entry.get("path")
+ if not path:
+ return None
+ path = Path(str(path).replace("\\", "/")).as_posix()
+
+ covered = entry.get("covered_lines")
+ covered_lines = sorted({int(x) for x in covered}) if isinstance(covered, (list, tuple)) else []
+
+ total = entry.get("total_coverable_lines")
+ total = int(total) if isinstance(total, (int, float)) and total >= 0 else None
+
+ pct = entry.get("line_coverage_pct")
+ pct = float(pct) if isinstance(pct, (int, float)) else None
+
+ # Reconcile the three (pct, covered, total) so any two pin the file down.
+ if pct is None:
+ if total and total > 0:
+ pct = len(covered_lines) / total * 100.0
+ elif covered_lines:
+ # Have hits but no total/pct — treat the hit set as the universe
+ # (fully covered). Rare; keeps a file that only reports hits visible.
+ total = len(covered_lines)
+ pct = 100.0
+ else:
+ return None # nothing to anchor a percentage → skip (absent != 0)
+ if total is None:
+ if covered_lines and pct > 0:
+ total = round(len(covered_lines) * 100.0 / pct)
+ else:
+ total = len(covered_lines)
+
+ branch = entry.get("branch_coverage_pct")
+ branch_pct = float(branch) if isinstance(branch, (int, float)) else None
+
+ return FileCoverage(
+ file_path=path,
+ line_coverage_pct=round(max(0.0, min(100.0, pct)), 2),
+ branch_coverage_pct=round(branch_pct, 2) if branch_pct is not None else None,
+ covered_lines=covered_lines,
+ total_coverable_lines=int(total or 0),
+ )
diff --git a/tests/unit/health/test_coverage_parsers.py b/tests/unit/health/test_coverage_parsers.py
index 6303a45a4..b886c3806 100644
--- a/tests/unit/health/test_coverage_parsers.py
+++ b/tests/unit/health/test_coverage_parsers.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import json
from pathlib import Path
import pytest
@@ -14,6 +15,7 @@ from repowise.core.analysis.health.coverage import (
parse_clover,
parse_cobertura,
parse_lcov,
+ parse_repowise_json,
)
FIXTURES = Path(__file__).resolve().parents[2] / "fixtures" / "coverage"
@@ -80,6 +82,70 @@ def test_clover_parses_cond_lines() -> None:
assert z.branch_coverage_pct is None
+def test_repowise_json_dict_form() -> None:
+ text = json.dumps(
+ {
+ "format": "repowise-coverage-v1",
+ "commit_sha": "deadbeef",
+ "files": {
+ "src/foo.py": {
+ "line_coverage_pct": 75.0,
+ "branch_coverage_pct": 50.0,
+ "covered_lines": [1, 3, 4],
+ "total_coverable_lines": 4,
+ },
+ "src/bar.py": {"line_coverage_pct": 100.0},
+ },
+ }
+ )
+ report = parse_repowise_json(text)
+ assert report.source_format == "repowise-json"
+ assert report.commit_sha == "deadbeef"
+ paths = {f.file_path: f for f in report.files}
+ assert set(paths) == {"src/foo.py", "src/bar.py"}
+ foo = paths["src/foo.py"]
+ assert foo.line_coverage_pct == 75.0
+ assert foo.branch_coverage_pct == 50.0
+ assert foo.covered_lines == [1, 3, 4]
+ assert foo.total_coverable_lines == 4
+ assert paths["src/bar.py"].branch_coverage_pct is None
+
+
+def test_repowise_json_list_form_and_path_normalization() -> None:
+ text = json.dumps(
+ {
+ "files": [
+ {"file_path": "src\\win\\a.py", "line_coverage_pct": 40.0},
+ {"path": "src/b.py", "covered_lines": [1, 2], "total_coverable_lines": 8},
+ ]
+ }
+ )
+ report = parse_repowise_json(text)
+ paths = {f.file_path: f for f in report.files}
+ assert "src/win/a.py" in paths # backslashes normalized to POSIX
+ b = paths["src/b.py"]
+ assert b.line_coverage_pct == 25.0 # derived from 2/8
+ assert b.total_coverable_lines == 8
+
+
+def test_repowise_json_derives_total_from_pct_and_covered() -> None:
+ text = json.dumps({"files": {"x.py": {"line_coverage_pct": 50.0, "covered_lines": [1, 2, 3]}}})
+ fc = parse_repowise_json(text).files[0]
+ assert fc.total_coverable_lines == 6 # 3 covered at 50% => 6 coverable
+
+
+def test_repowise_json_skips_unanchored_entries() -> None:
+ # An entry with no pct, no covered lines, no total cannot anchor coverage —
+ # it is absent, not zero, so it must be dropped.
+ text = json.dumps({"files": {"x.py": {"branch_coverage_pct": 10.0}, "y.py": {}}})
+ assert parse_repowise_json(text).files == []
+
+
+def test_repowise_json_bad_input_is_empty() -> None:
+ assert parse_repowise_json("not json").files == []
+ assert parse_repowise_json("[1,2,3]").files == []
+
+
@pytest.mark.parametrize(
"name, expected",
[
@@ -92,6 +158,19 @@ def test_detect_format(name: str, expected: str) -> None:
assert detect_format(_read(name)) == expected
+def test_detect_and_dispatch_repowise_json() -> None:
+ text = json.dumps(
+ {"format": "repowise-coverage-v1", "files": {"a.py": {"line_coverage_pct": 1.0}}}
+ )
+ assert detect_format(text) == "repowise-json"
+ # recognizable by key even without the format tag
+ text2 = json.dumps({"files": {"a.py": {"line_coverage_pct": 1.0}}})
+ assert detect_format(text2) == "repowise-json"
+ assert parse(text).source_format == "repowise-json"
+ # JSON that isn't a coverage report sniffs to None
+ assert detect_format(json.dumps({"hello": "world"})) is None
+
+
def test_detect_format_unknown() -> None:
assert detect_format("hello world") is None
assert detect_format("") is None