feat: add coverage join and golden-fixture clone exclusions

- join external Cobertura coverage.xml into current-run metrics using stdlib XML parsing
- surface coverage join facts consistently in CLI, reports, MCP, SARIF, and HTML
- distinguish measured coverage hotspots from coverage scope gaps in canonical findings
- add project-level golden_fixture_paths policy and carry excluded clone groups as suppressed report facts
- surface suppressed golden fixtures in Clones UI/CLI without affecting health or gates
- fix cached segment projection branch behavior and benchmark/cache regressions
- preserve cached public API parameter order and keep warm/cold API diffs stable
- bump canonical report schema and refresh docs, MCP contracts, and regression tests

Author: orenlab

CHANGELOG.md

@@ -2,56 +2,43 @@
 
 ## [2.0.0b5]
 
+Expands the canonical contract with adoption, API-surface, and coverage-join layers; clarifies run interpretation
+across MCP/HTML/clients; tightens MCP launcher/runtime behavior.
+
 ### Contracts, metrics, and review surfaces
 
-- Bump canonical report schema to `2.5` for `metrics.families.coverage_adoption`
-  and `metrics.families.api_surface`.
-- Bump clone baseline schema to `2.1` and standalone metrics-baseline schema to
-  `1.2` for compact `api_surface` wire payloads (`local_name` on disk,
-  reconstructed full qualnames in runtime) while keeping read-compatibility for
-  earlier `2.0` / `1.1` baseline files in the current b5 line.
-- Add shared public/private visibility classification for public-symbol-aware
-  metrics, without changing clone/fingerprint semantics.
-- Add canonical type/docstring adoption coverage:
-  parameter coverage, return coverage, public docstring coverage, and explicit
-  `Any` counts.
-- Add opt-in public API surface inventory and baseline diff:
-  public symbol snapshots, added symbols, and breaking changes against a
-  trusted metrics baseline.
-- Add new gates:
-  `--min-typing-coverage`, `--min-docstring-coverage`,
-  `--fail-on-typing-regression`, `--fail-on-docstring-regression`,
-  `--fail-on-api-break`.
-- Surface adoption and API metrics compactly in MCP summaries/detail, the HTML
-  Overview tab, and canonical report payloads without adding a new HTML tab.
-- Extend the normal CLI `Metrics` block with adoption coverage and public API
-  facts, while keeping the quiet compact metrics line unchanged.
-- Make unified clone baselines preserve embedded metrics and optional
-  `api_surface` payloads safely across saves.
-
-### MCP, HTML, and docs
-
-- Surface the effective runtime analysis profile (`min_loc`, `min_stmt`, block, and segment thresholds) in canonical
-  report metadata, MCP summary/triage projections, and the HTML Executive Summary subtitle.
-- Clarify MCP interpretation with compact `health_scope`, `focus`, and `new_by_source_kind` fields in summary/triage
-  projections.
-- Make baseline mismatch handling more explicit in MCP and the VS Code client by surfacing baseline/runtime python tags
-  and whether comparison is proceeding without a valid baseline.
-- Make the Claude Desktop bundle and Codex plugin prefer workspace-local launchers before `PATH`, with Poetry environment fallback for
-  python-tag-safe MCP startup.
-- Add `workspace_root` user-config field to the Claude Desktop bundle: setting it to the project directory forces the
-  launcher to prefer `.venv` inside that path even when Claude Desktop starts with a different working directory
-  (fixes python-tag mismatch caused by system-wide interpreter fallback).
-- Validate `git_diff_ref` inputs as safe single revision expressions in both
-  CLI and MCP before invoking `git diff`.
-- Replace the segment-group raw digest `repr()` payload with canonical JSON
-  bytes for cross-version-safe determinism.
-- Align the tests workflow coverage gate with the canonical `fail_under = 99`
-  policy and refresh the remaining `actions/checkout` pin in `codeclone.yml`.
-- Refresh branch metadata and client docs for the `2.0.0b5` line.
-- Update the README repository health badge to `87 (B)`.
-
-## [2.0.0b4]
+- Report schema `2.8`: add `coverage_adoption`, `api_surface`, `coverage_join`, and optional
+  `clones.suppressed.*` (for `golden_fixture_paths`); separate coverage hotspots vs scope gaps.
+- Baselines: clone `2.1`, metrics `1.2`; compact `api_surface` payload (`local_name` on disk, qualnames at runtime);
+  read-compatible with `2.0` / `1.1`.
+- Add public/private visibility classification for public-symbol metrics (no clone/fingerprint changes).
+- Add annotation/docstring adoption coverage: parameter, return, public docstrings, explicit `Any`.
+- Add opt-in API surface inventory + baseline diff (snapshots, additions, breaking changes).
+- Add coverage join (`--coverage`): per-function facts + findings for below-threshold or missing-in-scope functions;
+  current-run only (not baseline truth, no fingerprint impact).
+- Add `golden_fixture_paths`: exclude matching clone groups from health/gates while keeping suppressed facts.
+- Add gates: `--min-typing-coverage`, `--min-docstring-coverage`, `--fail-on-typing-regression`,
+  `--fail-on-docstring-regression`, `--fail-on-api-break`, `--fail-on-untested-hotspots`, `--coverage-min`.
+- Surface adoption/API/coverage-join in MCP, CLI Metrics, report payloads, and HTML (Overview + Quality subtab).
+- Preserve embedded metrics and optional `api_surface` in unified baselines.
+- Cache `2.4`: drop stale API-surface entries; preserve parameter order; align warm/cold API diffs.
+
+### MCP, HTML, and client interpretation
+
+- Surface effective analysis profile in report meta, MCP summary/triage, and HTML subtitle.
+- Add `health_scope`, `focus`, `new_by_source_kind` to MCP summary/triage.
+- Make baseline mismatch explicit (python tags + no-valid-baseline signal).
+- Prefer workspace-local launchers over `PATH` (Poetry fallback).
+- Add `workspace_root` to force project `.venv` selection.
+
+### Safety and maintenance
+
+- Validate `git_diff_ref` as safe single-revision expressions.
+- Replace segment digest `repr()` with canonical JSON bytes (determinism).
+- Align CI coverage gate (`fail_under = 99`) and refresh `actions/checkout` pin.
+- Refresh branch metadata/docs for `2.0.0b5`; update README badge to `89 (B)`.
+
+## [2.0.0b4] - 2026-04-05
 
 ### MCP server
 

README.md

@@ -16,7 +16,7 @@
   <a href="https://github.com/orenlab/codeclone/actions/workflows/tests.yml"><img src="https://github.com/orenlab/codeclone/actions/workflows/tests.yml/badge.svg?branch=main&style=flat-square" alt="Tests"></a>
   <a href="https://github.com/orenlab/codeclone/actions/workflows/benchmark.yml"><img src="https://github.com/orenlab/codeclone/actions/workflows/benchmark.yml/badge.svg?style=flat-square" alt="Benchmark"></a>
   <a href="https://pypi.org/project/codeclone/"><img src="https://img.shields.io/pypi/pyversions/codeclone.svg?style=flat-square" alt="Python"></a>
-  <a href="https://github.com/orenlab/codeclone"><img src="https://img.shields.io/badge/codeclone-87%20(B)-green" alt="codeclone 87 (B)"></a>
+  <a href="https://github.com/orenlab/codeclone"><img src="https://img.shields.io/badge/codeclone-87%20(B)-green" alt="codeclone 89 (B)"></a>
   <a href="#license"><img src="https://img.shields.io/badge/license-MPL--2.0-brightgreen?style=flat-square" alt="License"></a>
 </p>
 
@@ -43,8 +43,8 @@ Live sample report:
 - **Clone detection** — function (CFG fingerprint), block (statement windows), and segment (report-only) clones
 - **Structural findings** — duplicated branch families, clone guard/exit divergence and clone-cohort drift (report-only)
 - **Quality metrics** — cyclomatic complexity, coupling (`CBO`), cohesion (`LCOM4`), dependency cycles, dead code,
-  health score, type/docstring adoption coverage, public API surface diff, and report-only `Overloaded Modules`
-  profiling
+  health score, type/docstring adoption coverage, current-run Cobertura coverage join, public API surface diff, and
+  report-only `Overloaded Modules` profiling
 - **Baseline governance** — separates accepted **legacy** debt from **new regressions** and lets CI fail **only** on
   what changed
 - **Reports** — interactive HTML, deterministic JSON/TXT plus Markdown and SARIF projections from one canonical report
@@ -148,11 +148,17 @@ codeclone . --min-typing-coverage 80 --min-docstring-coverage 60
 codeclone . --fail-on-typing-regression --fail-on-docstring-regression
 codeclone . --api-surface --update-metrics-baseline
 codeclone . --fail-on-api-break
+
+# Current-run Cobertura hotspot gate
+codeclone . --coverage coverage.xml --fail-on-untested-hotspots --coverage-min 50
 ```
 
 In normal full-mode CLI output, CodeClone now surfaces adoption coverage
 (`params`, `returns`, `docstrings`, `Any`) in the main `Metrics` block, and it
-adds a `Public API` line when `--api-surface` facts are collected.
+adds a `Public API` line when `--api-surface` facts are collected. Passing
+`--coverage FILE` adds a `Coverage` line from external Cobertura XML, surfaces
+joined details under HTML `Quality -> Coverage Join` and MCP/report
+`coverage_join`, and does not update the clone baseline.
 
 ### Pre-commit
 
@@ -208,6 +214,7 @@ CodeClone can load project-level configuration from `pyproject.toml`:
 min_loc = 10
 min_stmt = 6
 baseline = "codeclone.baseline.json"
+golden_fixture_paths = ["tests/fixtures/golden_*"]
 skip_metrics = false
 quiet = false
 html_out = ".cache/codeclone/report.html"
@@ -288,11 +295,11 @@ class Middleware:  # codeclone: ignore[dead-code]
 Dynamic/runtime false positives are resolved via explicit inline suppressions, not via broad heuristics.
 
 <details>
-<summary>Canonical JSON report shape (v2.5)</summary>
+<summary>Canonical JSON report shape (v2.8)</summary>
 
 ```json
 {
-  "report_schema_version": "2.5",
+  "report_schema_version": "2.8",
   "meta": {
     "codeclone_version": "2.0.0b5",
     "project_name": "...",
@@ -362,11 +369,13 @@ Dynamic/runtime false positives are resolved via explicit inline suppressions, n
     "summary": {
       "...": "...",
       "coverage_adoption": { "...": "..." },
+      "coverage_join": { "...": "..." },
       "api_surface": { "...": "..." }
     },
     "families": {
       "...": "...",
       "coverage_adoption": { "...": "..." },
+      "coverage_join": { "...": "..." },
       "api_surface": { "...": "..." }
     }
   },

benchmarks/__init__.py

@@ -0,0 +1,5 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Den Rozhnovskiy

benchmarks/run_benchmark.py

@@ -176,6 +176,45 @@ def _run_cli_once(
     )
 
 
+def _validate_inventory_sample(
+    *,
+    scenario: Scenario,
+    measurement: RunMeasurement,
+) -> None:
+    if measurement.files_found <= 0:
+        raise RuntimeError(
+            f"scenario {scenario.name} produced an empty inventory sample; "
+            "benchmark target is invalid"
+        )
+    if measurement.files_skipped > 0:
+        raise RuntimeError(
+            f"scenario {scenario.name} skipped {measurement.files_skipped} files; "
+            "benchmark run is invalid"
+        )
+    if scenario.mode == "cold":
+        if measurement.files_cached != 0:
+            raise RuntimeError(
+                f"cold scenario {scenario.name} unexpectedly used cache: "
+                f"cached={measurement.files_cached}"
+            )
+        if measurement.files_analyzed <= 0:
+            raise RuntimeError(
+                f"cold scenario {scenario.name} analyzed no files: "
+                f"found={measurement.files_found} analyzed={measurement.files_analyzed}"
+            )
+        return
+    if measurement.files_cached <= 0:
+        raise RuntimeError(
+            f"warm scenario {scenario.name} did not use cache: "
+            f"cached={measurement.files_cached}"
+        )
+    if measurement.files_analyzed != 0:
+        raise RuntimeError(
+            f"warm scenario {scenario.name} analyzed files unexpectedly: "
+            f"analyzed={measurement.files_analyzed}"
+        )
+
+
 def _scenario_result(
     *,
     scenario: Scenario,
@@ -230,6 +269,7 @@ def _scenario_result(
             report_path=scenario_dir / f"run-report-{idx}.json",
             extra_args=scenario.extra_args,
         )
+        _validate_inventory_sample(scenario=scenario, measurement=measurement)
         measurements.append(measurement)
 
     digests = sorted({m.digest for m in measurements})