Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(health): ingest normalized-JSON coverage and surface coverage metrics (#309)
Raghav Chamadiyae276f8149fba
diff --git a/docs/CODE_HEALTH.md b/docs/CODE_HEALTH.mdindex 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 upon 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.mdindex 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.pyindex 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.mdindex 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 formatwhen `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 testdiff --git a/packages/core/src/repowise/core/analysis/health/coverage/__init__.py b/packages/core/src/repowise/core/analysis/health/coverage/__init__.pyindex 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_coberturafrom .detector import detect_format, is_test_file, paired_test_file, parsefrom .lcov import parse_lcovfrom .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.pyindex 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_cloverfrom .cobertura import parse_coberturafrom .lcov import parse_lcovfrom .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 Noneif 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.pynew file mode 100644index 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.pyindex 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 jsonfrom pathlib import Pathimport 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 Noneassert detect_format("") is None