feat(core): ship clone_guard_exit_divergence + clone_cohort_drift, optimize cache/report pipeline, harden deterministic contracts, and align docs/tests for 2.0.0b1

Author: orenlab

CHANGELOG.md

@@ -2,83 +2,79 @@
 
 ## [2.0.0b1]
 
-CodeClone 2.0 is a major upgrade that expands the project from a structural clone detector into a broader *
-*baseline-aware code-health and CI governance tool** for Python.
+CodeClone 2.0 is a major upgrade that evolves the project from a structural clone detector into a **baseline-aware**
+code-health and CI governance tool for Python.
 
-This beta introduces:
+This beta focuses on the new architecture, expanded code-health analysis, contract stability, and performance validation
+ahead of the final `2.0.0` release.
 
-- a new stage-based architecture
-- unified clone + metrics baseline flow
-- report schema `2.1`, cache schema `2.1`, and richer report provenance
-- expanded code-health analysis (complexity, coupling, cohesion, dependencies, dead code, health)
-- improved HTML and CLI reporting surfaces
-- substantial performance work for faster cold and warm runs
-
-Compatibility remains a first-class concern in this release:
-
-- baseline schema is bumped to `2.0`
-- `fingerprint_version` remains `1`
-- backward compatibility for legacy clone-only baselines is preserved
-
-This is a beta release intended to validate the new architecture, reporting surface, and performance profile before the
-final `2.0.0` release.
-
-### Fixes (feat/2.0.0)
+### Overview
 
-- Fixed scanner root-exclude short-circuit: only an explicitly excluded root
-  directory is skipped; excluded segments in parent path no longer suppress
-  valid scans (prevents silent zero-file analysis for roots like `build/project`).
-- Optimized HTML snippet rendering path:
-  - `_FileCache` now caches full file lines once per file and serves
-    line-range slices without repeated full-file scans.
-  - Pygments imports are cached per importer identity to avoid repeated
-    dynamic import overhead in hot snippet loops while preserving testability.
-- Optimized block explainability AST stats:
-  - added per-file statement index and range lookup via `bisect`,
-    replacing repeated full `ast.walk()` scans per range.
-- Added scanner regression coverage for roots under excluded parent directories.
-- No baseline/cache/report schema contract changes; detector identity semantics
-  and golden compatibility preserved.
+- New stage-based pipeline architecture with unified clone + metrics baseline flow.
+- Expanded code-health analysis: complexity, coupling, cohesion, dependencies, dead code, and health.
+- Improved HTML and CLI reporting surfaces.
+- Significant performance work for faster cold and warm runs.
+- Baseline schema `2.0`, report schema `2.1`, cache schema `2.2`; `fingerprint_version` remains `1` and legacy
+  clone-only baselines stay compatible.
 
 ### Architecture
 
-- Refactored CLI orchestration into a stage-based pipeline (`codeclone/pipeline.py`) to isolate discovery, processing,
-  analysis, report writing, and gating.
+- Refactored CLI orchestration into a stage-based pipeline (`codeclone/pipeline.py`) that isolates discovery,
+  processing, analysis, report writing, and gating.
 - Introduced explicit domain layers:
     - `codeclone/models.py` — typed core models
     - `codeclone/metrics/` — complexity, coupling, cohesion, dependencies, dead code, and health
-    - `codeclone/report/` — merge, explain, serialize, and suggestions
+    - `codeclone/report/` — merge, explain, serialize, suggestions
     - `codeclone/grouping.py` — clone grouping domain
-- Removed temporary legacy `_report_*` shim modules after migrating runtime and tests to `codeclone.report.*`.
+- Removed legacy `_report_*` shims after migrating runtime and tests to `codeclone.report.*`.
 
 ### Baseline, Cache, and Report Contracts
 
 - Bumped baseline schema to `2.0` (`BASELINE_SCHEMA_VERSION`) while preserving compatibility checks for legacy `1.0`
   clone-only payloads.
-- Added unified baseline flow with optional top-level `metrics` stored in the same baseline file as clone keys.
+- Added a unified baseline flow with optional top-level `metrics` stored alongside clone keys in the same baseline file.
 - Tracked embedded metrics snapshot integrity via `meta.metrics_payload_sha256`.
 - Preserved embedded metrics payload and hash when updating clone baseline content.
-- Bumped cache schema to `2.1`.
-- Bumped report schema to `2.1`.
-- Consolidated report contract around canonical sections:
-  `meta`, `inventory`, `findings`, `metrics`, with `derived` and `integrity`
-  as explicit companion layers.
-- Structural findings now deduplicate repeated occurrences and use explicit
-  `file_path` item layout instead of a sentinel `file_i=-1`.
-- Tightened `duplicated_branches` reporting to suppress trivial single-statement
-  branch boilerplate without structural mass.
+- Bumped cache schema to `2.2` and report schema to `2.1`.
+- Extended cache metrics payload with canonical symbol-usage references:
+    - `referenced_qualnames` in runtime entries
+    - compact wire key `rq` in cache payload
+- Added additive cache payload key `sr` (segment report projection) to reuse merged
+  segment suppression output on warm runs without cache schema/version bump.
+- Consolidated the report contract around canonical sections:
+  `meta`, `inventory`, `findings`, `metrics`, with `derived` and `integrity` as companion layers.
+- Structural findings now deduplicate repeated occurrences and use an explicit `file_path` item layout instead of a
+  sentinel `file_i = -1`.
+- Tightened `duplicated_branches` reporting to suppress trivial single-statement boilerplate without structural mass.
+
+### Contract Stabilization Updates
+
+- Added report-only structural finding families for clone cohort analysis:
+    - `clone_guard_exit_divergence`
+    - `clone_cohort_drift`
+- Added deterministic per-function stable structure facts in extraction/cache payloads and reused them for cohort
+  structural findings without extra scans.
+- Extended cache wire `u` row with stable structure columns while preserving deterministic decode defaults for legacy
+  rows.
+- Expanded `tests/fixtures/golden_v2` contracts:
+    - analysis snapshots now lock `stable_structure` and `cohort_structural_findings`
+    - CLI snapshots now lock structural group id/kind projections
+- Strengthened branch/invariant coverage for structural/report layers; coverage gate remains `>=99%`.
+- Synchronized contract docs with implemented code paths
+  (`README`, architecture, cache/report schema appendices, testing book).
 
 ### Configuration and CLI UX
 
-- Added project config loading from `pyproject.toml` under `[tool.codeclone]` with strict key and type validation.
+- Added project configuration loading from `pyproject.toml` under `[tool.codeclone]` with strict key and type
+  validation.
 - Made precedence explicit: `CLI (explicit flags) > pyproject.toml > parser/runtime defaults`.
 - Added a Python 3.10-compatible TOML loading path (`tomli` fallback when `tomllib` is unavailable).
-- Added optional-value report flags with deterministic defaults when passed without a path:
-    - `--html` -> `.cache/codeclone/report.html`
-    - `--json` -> `.cache/codeclone/report.json`
-    - `--md` -> `.cache/codeclone/report.md`
-    - `--sarif` -> `.cache/codeclone/report.sarif`
-    - `--text` -> `.cache/codeclone/report.txt`
+- Added optional-value report flags with deterministic default paths when passed without a value:
+    - `--html` → `.cache/codeclone/report.html`
+    - `--json` → `.cache/codeclone/report.json`
+    - `--md` → `.cache/codeclone/report.md`
+    - `--sarif` → `.cache/codeclone/report.sarif`
+    - `--text` → `.cache/codeclone/report.txt`
 - Added optional-value path flags for default-path intent:
     - `--baseline`
     - `--metrics-baseline`
@@ -87,41 +83,44 @@ final `2.0.0` release.
 - Replaced confusing argparse-generated double-negation aliases with explicit flag pairs:
     - `--no-progress` / `--progress`
     - `--no-color` / `--color`
-- Clarified CLI runtime footer wording: `Pipeline done in X.XXs`.
-  Reported time is pipeline time, not full process wall-clock including launcher or interpreter startup.
-- Refreshed the terminal UI for both normal and `--ci` modes:
+- Clarified the CLI runtime footer wording: `Pipeline done in X.XXs` (pipeline time only, not full process wall-clock).
+- Refreshed the terminal UI for normal and `--ci` modes:
     - clearer run header with scan-root context
     - structured analysis summary and quality-metrics panels
     - explicit cache, clone, and baseline counters
-    - report path and pipeline-time footer integrated into the summary surface
-- Fixed `pyproject.toml` override handling for `metrics_baseline`: a configured non-default metrics baseline path is now
-  respected even when `--metrics-baseline` is not passed explicitly.
-
-### Documentation
-
-- Updated the root `README.md` to reflect CodeClone 2.0 as a structural clone detector, baseline-aware governance tool,
-  and code-health gate.
-- Added a dedicated `pyproject.toml` configuration section (`[tool.codeclone]`) to the README.
-- Documented default-path behavior for bare report flags (`--html`, `--json`, `--text`).
-- Moved the long JSON report shape example under a collapsible `<details>` block for readability.
-- Added conservative performance guidance in the README with local run numbers and a 100k LOC extrapolation.
-- Updated contract docs in `docs/book/*` to reference `codeclone/report/*` directly instead of legacy shim paths.
-- Documented CLI timing semantics in `docs/book/09-cli.md`.
+    - report path and pipeline-time footer integrated into the summary
+- Fixed `pyproject.toml` override handling for `metrics_baseline`: a configured non-default path is now respected even
+  when `--metrics-baseline` is not passed explicitly.
 
 ### Report Provenance and UI
 
-- Added scan identity fields to report metadata:
+- Added scan identity fields to report meta
     - `project_name`
     - `scan_root`
 - Rendered `Project` and `Scan root` in the HTML provenance panel.
 - Added `Project name` and `Scan root` to TXT report metadata.
 - Propagated the same fields into JSON report `meta` via the shared report metadata builder.
-- Fixed baseline provenance after `--update-baseline`: report metadata now reflects the freshly saved clone baseline
-  hash (`baseline_payload_sha256`) and verification state in the same run.
+- Fixed baseline provenance after `--update-baseline`: report metadata now reflects the freshly saved baseline hash
+  (`baseline_payload_sha256`) and verification state in the same run.
 - Simplified dependency SVG rendering internals by removing unreachable guard branches while preserving deterministic
   output.
 - Made suggestions table headers consistently render glossary help badges through a single deterministic template path.
 
+### Detection Quality
+
+- Made the dead-code detector more conservative for non-actionable runtime patterns:
+    - skips test paths and test entrypoint names
+    - skips dunder methods
+    - skips dynamic visitor methods (`visit_*`) and setup/teardown hooks
+    - skips `Protocol` methods and stub-like callables (`@overload`, `@abstractmethod`)
+- Reduced false positives without changing clone detection semantics.
+- Dead-code liveness now ignores references originating from test files, including cached test-file references, so
+  production symbols used only in tests are still reported as dead-code candidates.
+- Dead-code liveness now uses exact canonical qualname references (including import-alias and module-alias usage)
+  before fallback local-name checks, reducing false positives on re-export and alias wiring.
+- Refactored `scanner.iter_py_files` into deterministic helpers without semantic changes, reducing method complexity and
+  keeping metrics-gate parity with the baseline.
+
 ### Performance
 
 - Added adaptive multiprocessing thresholds so small batches stay sequential instead of paying process-pool overhead.
@@ -136,23 +135,25 @@ final `2.0.0` release.
 - Improved warm-run responsiveness substantially while preserving deterministic behavior and output contracts.
 - Deferred HTML renderer import in CLI so non-HTML runs do not pay template/render startup cost.
 - Disabled transient status spinner contexts when `--no-progress` is active to reduce terminal I/O overhead.
-- Added canonical cache-entry fast-path for already validated runtime entries while preserving fallback validation for
-  raw
-  or externally mutated payloads.
+- Added a canonical cache-entry fast path for already validated runtime entries while preserving fallback validation for
+  raw or externally mutated payloads.
 - Reused a shared parsed baseline payload when clone and metrics baselines point to the same file to avoid duplicate
   JSON reads/parses in one run.
 
-### Detection Quality
+### Fixes
 
-- Made the dead-code detector more conservative for non-actionable runtime patterns:
-    - skips test paths and test entrypoint names
-    - skips dunder methods
-    - skips dynamic visitor methods (`visit_*`) and setup/teardown hooks
-- Reduced false positives without changing clone detection semantics.
-- Dead-code liveness now ignores references originating from test files, including cached test-file references, so
-  production symbols used only in tests are still reported as dead-code candidates.
-- Refactored `scanner.iter_py_files` into deterministic helpers without semantic changes, reducing method complexity to
-  keep metrics-gate parity with baseline.
+- Fixed scanner root-exclude short-circuit: only an explicitly excluded root directory is skipped; excluded segments in
+  a parent path no longer suppress valid scans, preventing silent zero-file analysis for roots like `build/project`.
+- Optimized HTML snippet rendering path:
+    - `_FileCache` now caches full file lines once per file and serves line-range slices without repeated full-file
+      scans
+    - Pygments imports are cached per importer identity to avoid repeated dynamic import overhead while preserving
+      testability
+- Optimized block explainability AST stats:
+    - added per-file statement index and range lookup via `bisect`, replacing repeated full `ast.walk()` scans per range
+- Added scanner regression coverage for roots under excluded parent directories.
+- No baseline/cache/report schema contract changes in this branch; detector identity semantics and golden compatibility
+  are preserved.
 
 ### Tests and Tooling
 

README.md

@@ -25,6 +25,7 @@ all with baseline-aware governance that separates **known** technical debt from
 ## Features
 
 - **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
 - **Baseline governance** — known debt stays accepted; CI blocks only new clones and metric regressions
@@ -147,6 +148,11 @@ Contract errors (`2`) take precedence over gating failures (`3`).
 | Text     | `--text`  | `.cache/codeclone/report.txt`   |
 
 All report formats are rendered from one canonical JSON report document.
+Structural findings include:
+
+- `duplicated_branches`
+- `clone_guard_exit_divergence`
+- `clone_cohort_drift`
 
 <details>
 <summary>JSON report shape (v2.1)</summary>
@@ -259,7 +265,7 @@ Architecture: [`docs/architecture.md`](docs/architecture.md) · CFG semantics: [
 | Docker benchmark contract  | [`docs/book/18-benchmarking.md`](docs/book/18-benchmarking.md)                           |
 | Determinism                | [`docs/book/12-determinism.md`](docs/book/12-determinism.md)                             |
 
-## * Benchmarking
+##  * Benchmarking
 
 <details>
 <summary>Reproducible Docker Benchmark</summary>