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): skip coverage markers on re-export-only files (#4110)

Raghav Chamadiyaea50dd0f9add
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index 0918e2579..e44905407 100644
--- a/docs/architecture/code-health.md
+++ b/docs/architecture/code-health.md
@@ -399,6 +399,8 @@ is **silent when no coverage report was ingested** (`line_coverage_pct is None`)
absent coverage is never imputed as uncovered. It lives in its own capped
category (`test_coverage_gradient`, −2.0) so the additive continuous signal
neither squeezes nor is squeezed by the binary gates, and it skips test files.
+It and `coverage_gap` also skip a file that holds only a docstring, imports and
+export lists (`__all__`): a package `__init__.py` or an `index.ts` barrel.
Calibrated offline against the defect corpus, it recovers **+0.043 corpus AUC
[95% CI +0.023, +0.061]** on the covered subset (≈65% of the continuous-feature
ceiling), Popt-neutral, and is exactly zero on repos without ingested coverage:
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/base.py b/packages/core/src/repowise/core/analysis/health/biomarkers/base.py
index cc88816c6..4c39dd289 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/base.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/base.py
@@ -70,6 +70,8 @@ class FileContext:
branch_coverage_pct: float | None = None
covered_lines: set[int] = field(default_factory=set)
total_coverable_lines: int = 0
+ # Only a docstring, imports and export lists: no code for coverage to measure.
+ reexport_only: bool = False
# Duplication signals (populated when the engine ran the
# duplication detector for this analyze() call). ``clones`` is the
# list of clone pairs this file participates in; ``duplication_pct``
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/coverage_gap.py b/packages/core/src/repowise/core/analysis/health/biomarkers/coverage_gap.py
index 426b7bef9..22751aad9 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/coverage_gap.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/coverage_gap.py
@@ -31,7 +31,7 @@ class CoverageGapDetector:
return []
if ctx.total_coverable_lines <= 0:
return []
- if ctx.is_test_material:
+ if ctx.is_test_material or ctx.reexport_only:
return []
cov = ctx.line_coverage_pct
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/coverage_gradient.py b/packages/core/src/repowise/core/analysis/health/biomarkers/coverage_gradient.py
index 5db6467b4..af3ae93ed 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/coverage_gradient.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/coverage_gradient.py
@@ -58,7 +58,7 @@ class CoverageGradientDetector:
if cov is None:
# No coverage data -> silent. Absent is not the same as uncovered.
return []
- if ctx.is_test_material:
+ if ctx.is_test_material or ctx.reexport_only:
return []
uncovered_fraction = max(0.0, (100.0 - float(cov)) / 100.0)
diff --git a/packages/core/src/repowise/core/analysis/health/file_evaluator.py b/packages/core/src/repowise/core/analysis/health/file_evaluator.py
index 6d2200eea..22c461052 100644
--- a/packages/core/src/repowise/core/analysis/health/file_evaluator.py
+++ b/packages/core/src/repowise/core/analysis/health/file_evaluator.py
@@ -21,6 +21,7 @@ from .finding_identity import SYMBOL_INDEX_KEY, SYMBOL_KEY, SYMBOL_LINE_KEY
from .function_blame_rollup import blame_commit_entries, commit_spans
from .history_refresh import BLAME_MARKERS, as_biomarker_result
from .models import HealthFileMetricData, HealthFindingData, Severity
+from .reexport_only import is_reexport_only
from .refactoring import RefactoringContext, RefactoringSuggestion, detect_refactorings
from .scoring import attach_impacts, file_score_fields, remap_severities, score_file
from .source_reader import SourceReader
@@ -286,6 +287,8 @@ class FileEvaluator:
branch_coverage_pct=cov.get("branch_coverage_pct") if cov else None,
covered_lines=set(cov.get("covered_lines") or ()) if cov else set(),
total_coverable_lines=int(cov.get("total_coverable_lines", 0)) if cov else 0,
+ reexport_only=bool(cov)
+ and is_reexport_only(pf, bool(fcx.functions), analyzer.read_source),
clones=list(clones),
duplication_pct=dup_pct,
clone_sources=clone_sources,
diff --git a/packages/core/src/repowise/core/analysis/health/reexport_only.py b/packages/core/src/repowise/core/analysis/health/reexport_only.py
new file mode 100644
index 000000000..c1d956e07
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/reexport_only.py
@@ -0,0 +1,41 @@
+"""Whether a file holds nothing but a docstring, imports and export lists."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from .source_reader import SourceReader
+
+_EXPORT_LIST = "__all__"
+_BLOCK_COMMENT = re.compile(r"/\*.*?\*/", re.DOTALL)
+#: Bare docstring quotes left once its text is cut, or the directive no extractor reports.
+_INERT_LINE = re.compile(r"""^([rRbBuU]?(\"\"\"|'''|"|')+|from __future__ import [\w ,()]+)$""")
+
+
+def _is_inert(line: str) -> bool:
+ text = line.strip().strip(";").strip()
+ return not text or text.startswith(("#", "//")) or bool(_INERT_LINE.match(text))
+
+
+def is_reexport_only(pf: Any, has_functions: bool, read_source: SourceReader) -> bool:
+ """True when every code line of the file is the docstring, an import or ``__all__``.
+
+ Each known statement is cut from the text; anything left that is not blank, a
+ comment or bare docstring quotes is code (a call, a second statement after ``;``).
+ """
+ if has_functions or any(s.name != _EXPORT_LIST for s in pf.symbols):
+ return False
+ source = read_source(pf.file_info.abs_path)
+ if source is None:
+ return False
+ lines = source.decode("utf-8", errors="replace").replace("\r\n", "\n").split("\n")
+ for sym in pf.symbols:
+ lines[sym.start_line - 1 : sym.end_line] = [""] * (sym.end_line - sym.start_line + 1)
+ text = "\n".join(lines)
+ if pf.file_info.language != "python":
+ text = _BLOCK_COMMENT.sub("", text)
+ for cut in [imp.raw_statement for imp in pf.imports] + [pf.docstring or ""]:
+ if cut:
+ text = text.replace(cut.replace("\r\n", "\n"), "", 1)
+ return all(_is_inert(line) for line in text.split("\n"))
diff --git a/tests/unit/health/test_reexport_coverage_gate.py b/tests/unit/health/test_reexport_coverage_gate.py
new file mode 100644
index 000000000..a362bbc68
--- /dev/null
+++ b/tests/unit/health/test_reexport_coverage_gate.py
@@ -0,0 +1,61 @@
+"""Coverage markers skip files that hold nothing but a docstring, imports and export lists."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from repowise.core.analysis.health import HealthAnalyzer
+from repowise.core.ingestion import ASTParser, FileTraverser, GraphBuilder
+
+_FILES = {
+ "pkg/__init__.py": '"""A package docstring and nothing else."""\n',
+ "pkg/api/__init__.py": (
+ "from __future__ import annotations\n\n"
+ 'from pkg.a import walk\nfrom pkg.b import scan\n\n__all__ = ["walk", "scan"]\n'
+ ),
+ "pkg/a.py": "def walk(paths):\n return [p for p in paths if p]\n",
+ "pkg/b.py": "def scan(paths):\n return list(paths)\n",
+ "pkg/consts.py": "LIMIT = 10\nNAMES = ('a', 'b')\n",
+ "pkg/script.py": '"""Run."""\nimport sys\n\nsys.path.insert(0, "lib")\n',
+ "pkg/run.py": '"""Doc\nmore."""\nprint("go")\n',
+ "pkg/env.py": 'import os; os.environ["A"] = "1"\n',
+ "pkg/sub/__init__.py": '"""Several\nlines of\npackage docs.\n"""\n\nfrom pkg.a import walk # noqa: F401\n',
+ "web/index.ts": "export * from './util';\nexport { helper } from './helper';\n",
+ "web/util.ts": "export function util(x: number): number {\n return x + 1;\n}\n",
+}
+_UNCOVERED = {"line_coverage_pct": 0.0, "total_coverable_lines": 60, "covered_lines": []}
+
+
+def _coverage_markers(root: Path) -> dict[str, set[str]]:
+ for rel, text in _FILES.items():
+ (root / rel).parent.mkdir(parents=True, exist_ok=True)
+ (root / rel).write_text(text, encoding="utf-8")
+ parser, gb, parsed = ASTParser(), GraphBuilder(), []
+ for fi in sorted(FileTraverser(root).traverse(), key=lambda f: f.path):
+ pf = parser.parse_file(fi, Path(fi.abs_path).read_bytes())
+ gb.add_file(pf)
+ parsed.append(pf)
+ gb.build()
+ coverage = {rel: dict(_UNCOVERED) for rel in _FILES}
+ report = HealthAnalyzer(gb.graph(), parsed_files=parsed, coverage_map=coverage).analyze()
+ out: dict[str, set[str]] = {rel: set() for rel in _FILES}
+ for f in report.findings:
+ if f.biomarker_type in {"coverage_gradient", "coverage_gap"}:
+ out[f.file_path].add(f.biomarker_type)
+ return out
+
+
+def test_reexport_and_docstring_only_files_carry_no_coverage_finding(tmp_path: Path) -> None:
+ markers = _coverage_markers(tmp_path)
+
+ assert markers["pkg/__init__.py"] == set()
+ assert markers["pkg/api/__init__.py"] == set()
+ assert markers["pkg/sub/__init__.py"] == set()
+ assert markers["web/index.ts"] == set()
+
+
+def test_files_that_declare_code_keep_their_coverage_findings(tmp_path: Path) -> None:
+ markers = _coverage_markers(tmp_path)
+
+ for rel in ("pkg/a.py", "pkg/consts.py", "pkg/script.py", "pkg/run.py", "pkg/env.py", "web/util.ts"):
+ assert markers[rel] == {"coverage_gradient", "coverage_gap"}, rel