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
fix(coverage): flag severe path-mapping loss instead of treating it as success (#1746) (#1955)
Nehal kanak kuniyil thottathil80b291b8f8fa
diff --git a/packages/cli/src/repowise/cli/commands/coverage_cmd.py b/packages/cli/src/repowise/cli/commands/coverage_cmd.pyindex 49cb1f2cb..6fb72a816 100644--- a/packages/cli/src/repowise/cli/commands/coverage_cmd.py+++ b/packages/cli/src/repowise/cli/commands/coverage_cmd.py@@ -181,6 +181,7 @@ def coverage_add(# --- Per-file aggregate coverage (lcov / cobertura / clover / json).agg_matched = 0unmapped = 0+ mapping_partial = Falseif agg_paths:resolved, errors = build_coverage_map(repo_path,@@ -198,6 +199,7 @@ def coverage_add(# for the one run where every single one of them was.skipped = resolved.unmatched + resolved.ambiguousunmapped = len(skipped)+ mapping_partial = resolved.mapping_partialif resolved.files:await save_coverage_files(session,@@ -205,6 +207,7 @@ def coverage_add(resolved.files,source_format=resolved.source_format or "lcov",ingested_commit_sha=head_sha,+ mapping_partial=mapping_partial,)agg_matched = resolved.matchedconsole.print(@@ -217,6 +220,14 @@ def coverage_add(f"[yellow]{len(skipped)} report file(s) did not map to the "f"repo tree[/yellow] (e.g. {sample}).")+ if mapping_partial:+ console.print(+ "[red]More than half the report did not map to the repo "+ "tree.[/red] The stored coverage describes only a fragment "+ "of the repository — fix [cyan]coverage.strip_prefix[/cyan] "+ "or [cyan]coverage.path_prefix[/cyan] in "+ ".repowise/config.yaml and re-run."+ )# --- Per-test map, from any report that carries contexts.map_records: list = []@@ -273,6 +284,16 @@ def coverage_add(f"[red]--strict: {unmapped} report file(s) did not map to the repo tree.[/red]")return False+ if mapping_partial:+ console.print(+ "[red]Coverage ingest was partial: more than half the report did "+ "not map to the repo tree.[/red] The stored numbers describe only "+ "the mapped fragment, not the repository. Fix "+ "[cyan]coverage.strip_prefix[/cyan] / [cyan]coverage.path_prefix[/cyan] "+ "in .repowise/config.yaml and re-run — this run exits non-zero so "+ "scripts cannot mistake a fragment for complete coverage."+ )+ return Falseconsole.print("Run [cyan]repowise health[/cyan] to fold coverage into the defect ""scores, or [cyan]repowise coverage status[/cyan] to review it."@@ -371,10 +392,17 @@ def coverage_status(repo: str | None, fmt: str) -> None:line_pct = summary.get("line_coverage_pct")branch_pct = summary.get("branch_coverage_pct")lines_str = f"{line_pct:.1f}%" if line_pct is not None else "n/a"+ partial = summary.get("mapping_partial")+ partial_suffix = (+ " [red](partial: stored numbers cover a fragment of the repo "+ "— fix coverage.strip_prefix and re-ingest)[/red]"+ if partial+ else ""+ )console.print(f"[bold]Coverage[/bold] ({summary.get('source_format') or 'lcov'})\n"f" Files: {summary['file_count']}\n"- f" Lines: {lines_str}"+ f" Lines: {lines_str}{partial_suffix}")if branch_pct is not None:console.print(f" Branch: {branch_pct:.1f}%")diff --git a/packages/core/alembic/versions/0056_coverage_mapping_partial.py b/packages/core/alembic/versions/0056_coverage_mapping_partial.pynew file mode 100644index 000000000..17c4542cc--- /dev/null+++ b/packages/core/alembic/versions/0056_coverage_mapping_partial.py@@ -0,0 +1,40 @@+"""Add mapping_partial to coverage_files.++A coverage ingest that maps fewer than half its report files to the repo tree+is a fragment, not repository coverage: the aggregate computed over the stored+subset (covered/total over the mapped rows only) is then presented as the+repo's number, which is the false-confidence trap of issue #1746. The flag is+a property of the whole delete-then-insert ingest, so it lives on the table+(any row of the latest batch reports it) rather than on individual rows.++Local SQLite stores get the column from the model via ``init_db``'s additive+schema reconciler; this migration covers the managed Postgres ones.++Revision ID: 0056+Revises: 0055+Create Date: 2026-08-28+"""++from __future__ import annotations++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++# revision identifiers+revision: str = "0056"+down_revision: str | None = "0055"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None+++def upgrade() -> None:+ op.add_column(+ "coverage_files",+ sa.Column("mapping_partial", sa.Boolean(), nullable=False, server_default=sa.false()),+ )+++def downgrade() -> None:+ op.drop_column("coverage_files", "mapping_partial")diff --git a/packages/core/src/repowise/core/analysis/health/coverage/discovery.py b/packages/core/src/repowise/core/analysis/health/coverage/discovery.pyindex c4ae5e4d2..65e4b30a9 100644--- a/packages/core/src/repowise/core/analysis/health/coverage/discovery.py+++ b/packages/core/src/repowise/core/analysis/health/coverage/discovery.py@@ -129,6 +129,10 @@ class ResolvedCoverage:matched_suffix: int = 0unmatched: list[str] = field(default_factory=list)ambiguous: list[str] = field(default_factory=list)+ # True when more than half the report's files failed to map to the tree.+ # Set by :func:`resolve_reports`; consumers must flag the aggregate as+ # partial rather than reporting the mapped subset's numbers as repo-wide.+ mapping_partial: bool = False@propertydef matched(self) -> int:@@ -326,11 +330,12 @@ def resolve_reports(suffix_index = _build_suffix_index(repo_keys)result = ResolvedCoverage()by_key: dict[str, FileCoverage] = {}-+ report_file_count = 0for report in reports:if result.source_format is None and report.source_format not in (None, "unknown"):result.source_format = report.source_formatfor fc in report.files:+ report_file_count += 1norm = normalize_report_path(fc.file_path, strip_prefix=strip_prefix, path_prefix=path_prefix)@@ -357,6 +362,15 @@ def resolve_reports(else:by_key[key] = resolved_fc+ # Severe mapping loss is a property of the *report*, not of the matched+ # subset: a 200-file report that mapped 20 files is a fragment no matter+ # how coherent those 20 look. Majority-unmapped is the threshold the+ # coverage path already documents as the "treats loss as success" trap+ # (issue #1746), and it deliberately avoids a hard ratio on the matched+ # side so monorepos ingesting one package's report stay unflagged.+ if report_file_count:+ result.mapping_partial = result.matched * 2 < report_file_count+for key, fc in by_key.items():result.coverage_map[key] = {"line_coverage_pct": fc.line_coverage_pct,diff --git a/packages/core/src/repowise/core/analysis/health/models.py b/packages/core/src/repowise/core/analysis/health/models.pyindex dd588420a..ab4a61b4e 100644--- a/packages/core/src/repowise/core/analysis/health/models.py+++ b/packages/core/src/repowise/core/analysis/health/models.py@@ -123,6 +123,9 @@ class HealthReport:# to the ``coverage_files`` table. Empty when no coverage was ingested.coverage_files: list[Any] = field(default_factory=list)coverage_format: str | None = None+ # True when the ingested coverage report mapped fewer than half its files+ # to the repo tree (#1746); carried so the persister can stamp the rows.+ coverage_mapping_partial: bool = False# Incremental writers replace all dimensions only for ``authoritative_paths``.# ``performance_authoritative_paths`` may be wider: the bounded execution# closure whose performance rows/plans were recomputed for full parity.diff --git a/packages/core/src/repowise/core/persistence/_interfaces/_analysis.py b/packages/core/src/repowise/core/persistence/_interfaces/_analysis.pyindex a5fc49961..9fd4f8743 100644--- a/packages/core/src/repowise/core/persistence/_interfaces/_analysis.py+++ b/packages/core/src/repowise/core/persistence/_interfaces/_analysis.py@@ -238,6 +238,7 @@ class AnalysisIndexStore(ABC):*,source_format: str,ingested_commit_sha: str | None = None,+ mapping_partial: bool = False,) -> None: ...@abstractmethoddiff --git a/packages/core/src/repowise/core/persistence/crud/analysis/coverage.py b/packages/core/src/repowise/core/persistence/crud/analysis/coverage.pyindex 01878ddcf..c4febe316 100644--- a/packages/core/src/repowise/core/persistence/crud/analysis/coverage.py+++ b/packages/core/src/repowise/core/persistence/crud/analysis/coverage.py@@ -19,12 +19,15 @@ async def save_coverage_files(*,source_format: str,ingested_commit_sha: str | None = None,+ mapping_partial: bool = False,) -> None:"""Replace coverage rows for *repository_id* with *files*.Mirrors the delete-then-insert pattern used by the health writers.*files* is a list of ``FileCoverage`` dataclasses (or dicts with the- same shape).+ same shape). ``mapping_partial`` marks the whole ingest as a fragment+ (fewer than half the report's files mapped to the repo tree, #1746);+ it is a property of the ingest, not of any one row."""existing = await session.execute(select(CoverageFile).where(CoverageFile.repository_id == repository_id)@@ -57,6 +60,7 @@ async def save_coverage_files(repository_id=repository_id,source_format=source_format,ingested_commit_sha=ingested_commit_sha,+ mapping_partial=mapping_partial,**{k: vfor k, v in data.items()@@ -66,6 +70,7 @@ async def save_coverage_files("repository_id","source_format","ingested_commit_sha",+ "mapping_partial",)and hasattr(CoverageFile, k)},@@ -84,6 +89,7 @@ _COVERAGE_SCALAR_COLUMNS = (CoverageFile.line_coverage_pct,CoverageFile.branch_coverage_pct,CoverageFile.total_coverable_lines,+ CoverageFile.mapping_partial,CoverageFile.ingested_at,CoverageFile.ingested_commit_sha,)@@ -162,6 +168,7 @@ async def get_coverage_summary("line_coverage_pct": None,"branch_coverage_pct": None,"source_format": None,+ "mapping_partial": None,"ingested_at": None,"ingested_commit_sha": None,}@@ -183,6 +190,11 @@ async def get_coverage_summary(else:branch_pct = Nonelatest = max(rows, key=lambda r: r.ingested_at)+ # A partial ingest is a whole-table property: every row of the latest+ # delete-then-insert batch carries the same flag, so any row reports the+ # table's. Rows written before the flag existed read False (column+ # default), which is correct for complete legacy ingests.+ mapping_partial = bool(getattr(latest, "mapping_partial", False))return {"file_count": len(rows),"covered_lines": covered,@@ -190,6 +202,7 @@ async def get_coverage_summary("line_coverage_pct": round(line_pct, 2),"branch_coverage_pct": round(branch_pct, 2) if branch_pct is not None else None,"source_format": latest.source_format,+ "mapping_partial": mapping_partial,"ingested_at": latest.ingested_at,"ingested_commit_sha": latest.ingested_commit_sha,}diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.pyindex f28a8cb28..33003b4bb 100644--- a/packages/core/src/repowise/core/persistence/models.py+++ b/packages/core/src/repowise/core/persistence/models.py@@ -1650,6 +1650,11 @@ class CoverageFile(Base):branch_coverage_pct: Mapped[float | None] = mapped_column(Float, nullable=True)covered_lines_json: Mapped[str] = mapped_column(Text, nullable=False, default="[]")total_coverable_lines: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ # True when the ingest that wrote these rows mapped fewer than half of the+ # report's files to the repo tree (severe path-mapping loss). The rows are+ # still written — a partial report is better than none — but consumers+ # must not present the subset's aggregate as repository-wide coverage.+ mapping_partial: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)ingested_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=_now_utc)diff --git a/packages/core/src/repowise/core/persistence/stores/_sql_analysis.py b/packages/core/src/repowise/core/persistence/stores/_sql_analysis.pyindex 97b558093..c7c907188 100644--- a/packages/core/src/repowise/core/persistence/stores/_sql_analysis.py+++ b/packages/core/src/repowise/core/persistence/stores/_sql_analysis.py@@ -281,6 +281,7 @@ class _SqlAnalysisMixin(AnalysisIndexStore):*,source_format: str,ingested_commit_sha: str | None = None,+ mapping_partial: bool = False,) -> None:await crud.save_coverage_files(self._session,@@ -288,6 +289,7 @@ class _SqlAnalysisMixin(AnalysisIndexStore):files,source_format=source_format,ingested_commit_sha=ingested_commit_sha,+ mapping_partial=mapping_partial,)async def load_coverage_for_repo(diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.pyindex abff43aa6..36c2ff0c3 100644--- a/packages/core/src/repowise/core/pipeline/persist.py+++ b/packages/core/src/repowise/core/pipeline/persist.py@@ -1639,6 +1639,7 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:coverage_files,source_format=getattr(hr, "coverage_format", None) or "lcov",ingested_commit_sha=head_sha,+ mapping_partial=bool(getattr(hr, "coverage_mapping_partial", False)),)# Per-function blame rollup (FULL tier only; empty otherwise).fn_blame_rows = getattr(hr, "function_blame_rows", None)diff --git a/packages/core/src/repowise/core/pipeline/phases/analysis.py b/packages/core/src/repowise/core/pipeline/phases/analysis.pyindex fb2e548a9..ab16ebba8 100644--- a/packages/core/src/repowise/core/pipeline/phases/analysis.py+++ b/packages/core/src/repowise/core/pipeline/phases/analysis.py@@ -105,13 +105,13 @@ def _build_pipeline_coverage(explicit_paths: list[Path] | None,*,progress: ProgressCallback | None,-) -> tuple[dict[str, dict], list[Any], str | None]:+) -> tuple[dict[str, dict], list[Any], str | None, bool]:"""Discover/parse/resolve coverage reports for an indexing run.- Returns ``(coverage_map, resolved_files, source_format)``. Best-effort:- any failure logs and yields an empty map so health analysis proceeds- without coverage. Unmatched report files are surfaced via *progress* so- "coverage didn't show up" is never silent.+ Returns ``(coverage_map, resolved_files, source_format, mapping_partial)``.+ Best-effort: any failure logs and yields an empty map so health analysis+ proceeds without coverage. Unmatched report files are surfaced via+ *progress* so "coverage didn't show up" is never silent."""try:from repowise.core.analysis.health.coverage import (@@ -130,10 +130,10 @@ def _build_pipeline_coverage(elif cfg.auto_discover:report_paths = discover_artifacts(repo_path, globs=cfg.artifacts or None)else:- return {}, [], None+ return {}, [], None, Falseif not report_paths:- return {}, [], None+ return {}, [], None, Falserepo_keys = {pf.file_info.path for pf in parsed_files}resolved, errors = build_coverage_map(@@ -161,15 +161,26 @@ def _build_pipeline_coverage(f"(e.g. {sample}). Set coverage.strip_prefix in "f".repowise/config.yaml if paths are off.",)+ if resolved.mapping_partial:+ progress.on_message(+ "warning",+ " ↳ more than half the report did not map: the stored "+ "coverage is a fragment, not the whole repository.",+ )for path, err in errors:progress.on_message("warning", f" ↳ coverage {path.name}: {err}")- return resolved.coverage_map, resolved.files, resolved.source_format+ return (+ resolved.coverage_map,+ resolved.files,+ resolved.source_format,+ resolved.mapping_partial,+ )except Exception as exc:if progress:progress.on_message("warning", f"Coverage ingestion skipped: {exc}")logger.debug("pipeline_coverage_failed", error=str(exc))- return {}, [], None+ return {}, [], None, Falseasync def _run_health_analysis(@@ -214,8 +225,14 @@ async def _run_health_analysis(coverage_map: dict[str, dict] = {}coverage_files: list[Any] = []coverage_format: str | None = None+ coverage_mapping_partial = Falseif repo_path is not None:- coverage_map, coverage_files, coverage_format = _build_pipeline_coverage(+ (+ coverage_map,+ coverage_files,+ coverage_format,+ coverage_mapping_partial,+ ) = _build_pipeline_coverage(repo_path, parsed_files, coverage_report_paths, progress=progress)@@ -256,6 +273,7 @@ async def _run_health_analysis(if coverage_files:report.coverage_files = coverage_filesreport.coverage_format = coverage_format+ report.coverage_mapping_partial = coverage_mapping_partialif progress:findings_count = len(report.findings)diff --git a/packages/server/src/repowise/server/routers/code_health/coverage_routes.py b/packages/server/src/repowise/server/routers/code_health/coverage_routes.pyindex abc905637..4b36209bd 100644--- a/packages/server/src/repowise/server/routers/code_health/coverage_routes.py+++ b/packages/server/src/repowise/server/routers/code_health/coverage_routes.py@@ -206,6 +206,7 @@ def _empty_summary() -> dict[str, Any]:"line_coverage_pct": None,"branch_coverage_pct": None,"source_format": None,+ "mapping_partial": None,"ingested_at": None,"ingested_commit_sha": None,}diff --git a/tests/unit/health/test_coverage_discovery.py b/tests/unit/health/test_coverage_discovery.pyindex 42433f38c..0641375ca 100644--- a/tests/unit/health/test_coverage_discovery.py+++ b/tests/unit/health/test_coverage_discovery.py@@ -232,6 +232,59 @@ def test_build_coverage_map_end_to_end(tmp_path: Path) -> None:assert not errorsassert "src/a.ts" in resolved.coverage_mapassert resolved.coverage_map["src/a.ts"]["line_coverage_pct"] == 50.0+ assert resolved.mapping_partial is False+++# ---------------------------------------------------------------------------+# mapping_partial — severe path-mapping loss (issue #1746)+# ---------------------------------------------------------------------------+++def test_mapping_partial_false_when_majority_maps() -> None:+ keys = {"src/a.py", "src/b.py"}+ report = _report([_fc("src/a.py"), _fc("src/b.py"), _fc("/abs/other/c.py")])+ res = resolve_reports([report], keys)+ assert res.matched == 2+ assert res.mapping_partial is False+++def test_mapping_partial_true_when_majority_unmapped() -> None:+ """Issue #1746: a report that maps 1 of 5 files is a fragment, and the+ ingest must not present its aggregate as repository coverage."""+ keys = {"src/a.py"}+ report = _report(+ [_fc("src/a.py"), _fc("/abs/one/b.py"), _fc("/abs/two/c.py"),+ _fc("/abs/three/d.py"), _fc("/abs/four/e.py")]+ )+ res = resolve_reports([report], keys)+ assert res.matched == 1+ assert len(res.unmatched) == 4+ assert res.mapping_partial is True+++def test_mapping_partial_measured_on_report_files_not_matched_keys() -> None:+ """Merging the same key across reports must not shrink the denominator."""+ keys = {"src/a.py"}+ res = resolve_reports(+ [_report([_fc("src/a.py"), _fc("/abs/other/b.py")]),+ _report([_fc("src/a.py")])],+ keys,+ )+ # 3 report files, 2 matched (a.py twice, merged hit-wins) → not partial+ assert res.matched == 2+ assert res.mapping_partial is False+++def test_build_coverage_map_flags_partial(tmp_path: Path) -> None:+ lcov = "SF:/ci/build/src/a.ts\nDA:1,1\nend_of_record\nSF:/ci/other/b.ts\nDA:1,1\nend_of_record\nSF:/ci/other/c.ts\nDA:1,1\nend_of_record\n"+ report_path = tmp_path / "coverage" / "lcov.info"+ report_path.parent.mkdir()+ report_path.write_text(lcov)++ keys = {"src/a.ts"}+ resolved, errors = build_coverage_map(tmp_path, [report_path], keys)+ assert not errors+ assert resolved.mapping_partial is True# ---------------------------------------------------------------------------diff --git a/tests/unit/persistence/test_coverage_narrow_read.py b/tests/unit/persistence/test_coverage_narrow_read.pyindex ca6d323e5..1f01f7da9 100644--- a/tests/unit/persistence/test_coverage_narrow_read.py+++ b/tests/unit/persistence/test_coverage_narrow_read.py@@ -115,3 +115,31 @@ async def test_summary_weights_branch_coverage_over_rows_that_have_it(assert summary["covered_lines"] == 6assert summary["total_lines"] == 15assert summary["branch_coverage_pct"] == 10.0+++async def test_summary_defaults_mapping_partial_false_for_legacy_ingests(+ async_session, repo+) -> None:+ """Rows written before the flag existed must read as complete, not partial."""+ summary = await get_coverage_summary(async_session, repo.id)++ assert summary["mapping_partial"] is False+++async def test_summary_reports_mapping_partial_when_ingest_was_fragment(+ async_session, tmp_path+) -> None:+ """Issue #1746: a partial ingest stamps every row, and the summary surfaces+ it so consumers don't present the mapped subset as repository coverage."""+ r = await upsert_repository(async_session, name="partial", local_path=str(tmp_path))+ await save_coverage_files(+ async_session,+ r.id,+ _FILES,+ source_format="lcov",+ mapping_partial=True,+ )++ summary = await get_coverage_summary(async_session, r.id)+ assert summary["mapping_partial"] is True+ assert summary["file_count"] == 2diff --git a/tests/unit/pipeline/test_coverage_ingestion.py b/tests/unit/pipeline/test_coverage_ingestion.pyindex 5c9a0428a..248b075cc 100644--- a/tests/unit/pipeline/test_coverage_ingestion.py+++ b/tests/unit/pipeline/test_coverage_ingestion.py@@ -28,7 +28,7 @@ def test_autodiscovers_and_resolves_absolute_lcov(tmp_path: Path) -> None:(tmp_path / "coverage" / "lcov.info").write_text(lcov)parsed = [_parsed("rust/src/tts/voices.rs"), _parsed("rust/src/lib.rs")]- coverage_map, files, fmt = _build_pipeline_coverage(+ coverage_map, files, fmt, _partial = _build_pipeline_coverage(tmp_path, parsed, None, progress=None)@@ -44,7 +44,7 @@ def test_explicit_paths_take_priority(tmp_path: Path) -> None:report.write_text("SF:src/a.ts\nDA:1,1\nend_of_record\n")parsed = [_parsed("src/a.ts")]- coverage_map, _files, _fmt = _build_pipeline_coverage(+ coverage_map, _files, _fmt, _partial = _build_pipeline_coverage(tmp_path, parsed, [report], progress=None)assert "src/a.ts" in coverage_map@@ -52,12 +52,13 @@ def test_explicit_paths_take_priority(tmp_path: Path) -> None:def test_no_report_yields_empty_map(tmp_path: Path) -> None:parsed = [_parsed("src/a.ts")]- coverage_map, files, fmt = _build_pipeline_coverage(+ coverage_map, files, fmt, partial = _build_pipeline_coverage(tmp_path, parsed, None, progress=None)assert coverage_map == {}assert files == []assert fmt is None+ assert partial is Falsedef test_auto_discover_disabled_via_config(tmp_path: Path) -> None:@@ -69,7 +70,7 @@ def test_auto_discover_disabled_via_config(tmp_path: Path) -> None:)parsed = [_parsed("src/a.ts")]- coverage_map, _files, _fmt = _build_pipeline_coverage(+ coverage_map, _files, _fmt, _partial = _build_pipeline_coverage(tmp_path, parsed, None, progress=None)assert coverage_map == {}@@ -87,7 +88,7 @@ def test_strip_prefix_from_config(tmp_path: Path) -> None:)parsed = [_parsed("web/index.ts"), _parsed("api/index.ts")]- coverage_map, _files, _fmt = _build_pipeline_coverage(+ coverage_map, _files, _fmt, _partial = _build_pipeline_coverage(tmp_path, parsed, None, progress=None)assert "web/index.ts" in coverage_map