feat(metrics): add adoption and public API baselines with compact schema-aware storage

Author: orenlab

CHANGELOG.md

@@ -2,9 +2,35 @@
 
 ## [2.0.0b5]
 
+### 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
 
-- Bump canonical report schema to `2.4` for `meta.analysis_profile`.
 - 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

README.md

@@ -43,7 +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, and report-only `Overloaded Modules` profiling
+  health score, type/docstring adoption coverage, 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
@@ -141,8 +142,18 @@ codeclone . --fail-cycles --fail-dead-code
 
 # Regression detection vs baseline
 codeclone . --fail-on-new-metrics
+
+# Adoption and API governance
+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
 ```
 
+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.
+
 ### Pre-commit
 
 ```yaml
@@ -277,11 +288,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.4)</summary>
+<summary>Canonical JSON report shape (v2.5)</summary>
 
 ```json
 {
-  "report_schema_version": "2.4",
+  "report_schema_version": "2.5",
   "meta": {
     "codeclone_version": "2.0.0b5",
     "project_name": "...",
@@ -348,8 +359,16 @@ Dynamic/runtime false positives are resolved via explicit inline suppressions, n
     }
   },
   "metrics": {
-    "summary": {},
-    "families": {}
+    "summary": {
+      "...": "...",
+      "coverage_adoption": { "...": "..." },
+      "api_surface": { "...": "..." }
+    },
+    "families": {
+      "...": "...",
+      "coverage_adoption": { "...": "..." },
+      "api_surface": { "...": "..." }
+    }
   },
   "derived": {
     "suggestions": [],