fix(runtime): complete cp314 migration and clean baseline trust UX

orenlab · orenlab · commit 1b3a9e926d8e · 2026-04-24T19:41:18.000+05:00
diff --git a/.github/actions/codeclone/README.md b/.github/actions/codeclone/README.md
@@ -73,7 +73,7 @@ jobs:
 
 | Input                   | Default                         | Purpose                                                                                                           |
 |-------------------------|---------------------------------|-------------------------------------------------------------------------------------------------------------------|
-| `python-version`        | `3.13`                          | Python version used to run the action                                                                             |
+| `python-version`        | `3.14`                          | Python version used to run the action                                                                             |
 | `package-version`       | `""`                            | CodeClone version from PyPI for remote installs; ignored when the action runs from the checked-out CodeClone repo |
 | `path`                  | `.`                             | Project root to analyze                                                                                           |
 | `json-path`             | `.cache/codeclone/report.json`  | JSON report output path                                                                                           |
diff --git a/.github/actions/codeclone/action.yml b/.github/actions/codeclone/action.yml
@@ -13,7 +13,7 @@ inputs:
   python-version:
     description: "Python version"
     required: false
-    default: "3.13"
+    default: "3.14"
 
   package-version:
     description: "CodeClone version from PyPI for remote installs (ignored when the action runs from the checked-out CodeClone repo)"
diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml
@@ -87,7 +87,7 @@ jobs:
         if: env.BENCH_ENABLED == '1' && runner.os == 'macOS'
         uses: actions/setup-python@v6.2.0
         with:
-          python-version: "3.13"
+          python-version: "3.14"
           allow-prereleases: true
 
       - name: Set up uv (macOS local benchmark)
diff --git a/.github/workflows/codeclone.yml b/.github/workflows/codeclone.yml
@@ -26,7 +26,7 @@ jobs:
       - name: Run CodeClone
         uses: ./.github/actions/codeclone
         with:
-          python-version: "3.13"
+          python-version: "3.14"
           fail-on-new: "true"
           fail-health: "60"
           sarif: "true"
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -24,7 +24,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6.2.0
         with:
-          python-version: "3.13"
+          python-version: "3.14"
           allow-prereleases: true
 
       - name: Set up uv
@@ -33,7 +33,7 @@ jobs:
           enable-cache: true
 
       - name: Install project dependencies
-        run: uv sync --dev
+        run: uv sync --extra dev
 
       - name: Configure GitHub Pages
         uses: actions/configure-pages@v5
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -34,7 +34,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6.2.0
         with:
-          python-version: "3.13"
+          python-version: "3.14"
           allow-prereleases: true
 
       - name: Set up uv
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -43,11 +43,11 @@ jobs:
         run: uv run pytest --cov=codeclone --cov-report=term-missing --cov-fail-under=99
 
       - name: Verify baseline exists
-        if: ${{ matrix.python-version == '3.13' }}
+        if: ${{ matrix.python-version == '3.14' }}
         run: test -f codeclone.baseline.json
 
       - name: Check for new clones vs baseline
-        if: ${{ matrix.python-version == '3.13' }}
+        if: ${{ matrix.python-version == '3.14' }}
         run: uv run codeclone . --ci
 
   lint:
@@ -59,7 +59,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6.2.0
         with:
-          python-version: "3.13"
+          python-version: "3.14"
 
       - name: Set up uv
         uses: astral-sh/setup-uv@v5
diff --git a/AGENTS.md b/AGENTS.md
@@ -162,7 +162,7 @@ versions from another document.
     },
     "schema_version": "2.1",
     "fingerprint_version": "1",
-    "python_tag": "cp313",
+    "python_tag": "cp314",
     "created_at": "2026-02-08T14:20:15Z",
     "payload_sha256": "…"
   },
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -49,7 +49,7 @@ When reporting issues related to clone detection, include:
 
 - minimal reproducible code snippets (preferred over screenshots);
 - the CodeClone version;
-- the Python version (`python_tag`, e.g. `cp313`);
+- the Python version (`python_tag`, e.g. `cp314`);
 - whether the issue is primarily:
     - AST-related,
     - CFG-related,
diff --git a/benchmarks/Dockerfile b/benchmarks/Dockerfile
@@ -1,6 +1,6 @@
 # syntax=docker/dockerfile:1.7
 
-FROM python:3.13.2-slim-bookworm
+FROM python:3.14.3-slim-bookworm
 
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
diff --git a/codeclone.baseline.json b/codeclone.baseline.json
@@ -6,9 +6,9 @@
     },
     "schema_version": "2.1",
     "fingerprint_version": "1",
-    "python_tag": "cp313",
-    "created_at": "2026-04-23T17:22:20Z",
-    "payload_sha256": "07a383c1d0974593c83ac30430aec9b99d89fe50f640a9b3b433658e0bd029e8",
+    "python_tag": "cp314",
+    "created_at": "2026-04-24T14:37:27Z",
+    "payload_sha256": "a2e5e3ac672ddbc7ba95c3a9608257727a01480ef343bc6a70c168fc9355e99a",
     "metrics_payload_sha256": "26ebd9e502bb4d98d97da593532395de140b2c64b03d85ab91e681f9025fedff"
   },
   "clones": {
diff --git a/codeclone/contracts/schemas.py b/codeclone/contracts/schemas.py
@@ -33,9 +33,9 @@ class ReportMeta(TypedDict):
     Canonical report metadata contract shared by HTML, JSON, and TXT reports.
 
     Key semantics:
-    - python_version: runtime major.minor string for human readability (e.g. "3.13")
+    - python_version: runtime major.minor string for human readability (e.g. "3.14")
     - python_tag: runtime compatibility tag used by baseline/cache contracts
-      (e.g. "cp313")
+      (e.g. "cp314")
     - baseline_*: values loaded from baseline metadata for audit/provenance
     - cache_*: cache status/provenance for run transparency
     """
diff --git a/codeclone/surfaces/cli/baseline_state.py b/codeclone/surfaces/cli/baseline_state.py
@@ -210,6 +210,7 @@ def resolve_metrics_baseline_state(
     args: _BaselineArgs,
     metrics_baseline_path: Path,
     metrics_baseline_exists: bool,
+    clone_baseline_state: CloneBaselineState,
     baseline_updated_path: Path | None,
     project_metrics: ProjectMetrics | None,
     console: _PrinterLike,
@@ -229,6 +230,7 @@ def resolve_metrics_baseline_state(
     _load_metrics_baseline_for_diff(
         args=args,
         metrics_baseline_exists=metrics_baseline_exists,
+        clone_baseline_state=clone_baseline_state,
         state=state,
         console=console,
         shared_baseline_payload=shared_baseline_payload,
@@ -282,10 +284,17 @@ def _load_metrics_baseline_for_diff(
     *,
     args: _BaselineArgs,
     metrics_baseline_exists: bool,
+    clone_baseline_state: CloneBaselineState,
     state: _MetricsBaselineRuntime,
     console: _PrinterLike,
     shared_baseline_payload: dict[str, object] | None = None,
 ) -> None:
+    suppress_invalid_message = bool(
+        shared_baseline_payload is not None
+        and not clone_baseline_state.loaded
+        and clone_baseline_state.status in BASELINE_UNTRUSTED_STATUSES
+    )
+
     if not metrics_baseline_exists:
         if _metrics_baseline_gate_requested(args) and not args.update_metrics_baseline:
             state.failure_code = ExitCode.CONTRACT_ERROR
@@ -308,7 +317,8 @@ def _load_metrics_baseline_for_diff(
     except BaselineValidationError as exc:
         state.status = coerce_metrics_baseline_status(exc.status)
         if not args.update_metrics_baseline:
-            console.print(ui.fmt_invalid_baseline(exc))
+            if not suppress_invalid_message:
+                console.print(ui.fmt_invalid_baseline(exc))
             if args.fail_on_new_metrics:
                 state.failure_code = ExitCode.CONTRACT_ERROR
         return
@@ -320,7 +330,8 @@ def _load_metrics_baseline_for_diff(
         state.baseline.verify_compatibility(runtime_python_tag=current_python_tag())
     except BaselineValidationError as exc:
         state.status = coerce_metrics_baseline_status(exc.status)
-        console.print(ui.fmt_invalid_baseline(exc))
+        if not suppress_invalid_message:
+            console.print(ui.fmt_invalid_baseline(exc))
         if args.fail_on_new_metrics:
             state.failure_code = ExitCode.CONTRACT_ERROR
     else:
@@ -471,6 +482,7 @@ def _resolve_metrics_baseline_state(
     args: CLIArgsLike,
     metrics_baseline_path: Path,
     metrics_baseline_exists: bool,
+    clone_baseline_state: CloneBaselineState,
     baseline_updated_path: Path | None,
     analysis: AnalysisResult,
     shared_baseline_payload: dict[str, object] | None = None,
@@ -479,6 +491,7 @@ def _resolve_metrics_baseline_state(
         args=args,
         metrics_baseline_path=metrics_baseline_path,
         metrics_baseline_exists=metrics_baseline_exists,
+        clone_baseline_state=clone_baseline_state,
         baseline_updated_path=baseline_updated_path,
         project_metrics=analysis.project_metrics,
         console=require_status_console(cli_state.get_console()),
diff --git a/codeclone/surfaces/cli/execution.py b/codeclone/surfaces/cli/execution.py
@@ -222,7 +222,11 @@ def enforce_gating(
         sys.exit(ExitCode.CONTRACT_ERROR)
 
     if baseline_failure_code is not None:
-        printer.print(ui.fmt_contract_error(ui.ERR_BASELINE_GATING_REQUIRES_TRUSTED))
+        printer.print(
+            ui.fmt_contract_error(
+                ui.fmt_baseline_gating_requires_trusted(ci=bool_attr(args, "ci"))
+            )
+        )
         sys.exit(baseline_failure_code)
 
     if metrics_baseline_failure_code is not None:
diff --git a/codeclone/surfaces/cli/workflow.py b/codeclone/surfaces/cli/workflow.py
@@ -389,6 +389,7 @@ def _main_impl() -> None:
         args=args,
         metrics_baseline_path=baseline_inputs.metrics_baseline_path,
         metrics_baseline_exists=baseline_inputs.metrics_baseline_exists,
+        clone_baseline_state=baseline_state,
         baseline_updated_path=baseline_state.updated_path,
         analysis=analysis_result,
         shared_baseline_payload=shared_baseline_payload,
diff --git a/codeclone/ui_messages/__init__.py b/codeclone/ui_messages/__init__.py
@@ -326,9 +326,13 @@
     "[dim]Comparison will proceed against an empty baseline.[/dim]\n"
     f"[dim]{ACTION_UPDATE_BASELINE}[/dim]"
 )
-ERR_BASELINE_GATING_REQUIRES_TRUSTED = (
+ERR_BASELINE_CI_REQUIRES_TRUSTED = (
     f"[error]CI requires a trusted baseline.[/error]\n{ACTION_UPDATE_BASELINE}"
 )
+ERR_BASELINE_GATING_REQUIRES_TRUSTED = (
+    "[error]Baseline-aware gates require a trusted baseline.[/error]\n"
+    f"{ACTION_UPDATE_BASELINE}"
+)
 SUCCESS_BASELINE_UPDATED = "✔ Baseline updated: {path}"
 
 FAIL_NEW_TITLE = "[error]FAILED: New code clones detected.[/error]"
@@ -439,6 +443,12 @@ def fmt_invalid_baseline(error: object) -> str:
     return ERR_INVALID_BASELINE.format(error=error)
 
 
+def fmt_baseline_gating_requires_trusted(*, ci: bool) -> str:
+    return (
+        ERR_BASELINE_CI_REQUIRES_TRUSTED if ci else ERR_BASELINE_GATING_REQUIRES_TRUSTED
+    )
+
+
 def fmt_cli_runtime_warning(message: object) -> str:
     source = _RICH_MARKUP_TAG_RE.sub("", str(message)).strip()
     paragraphs = [
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -274,7 +274,7 @@ baseline/options contract violations.
 ## Python Tag Consistency for Baseline Checks
 
 Due to inherent AST differences across interpreter builds, baseline compatibility
-is pinned to `python_tag` (for example `cp313`).
+is pinned to `python_tag` (for example `cp314`).
 
 This preserves deterministic and reproducible clone detection results while allowing
 patch updates within the same interpreter tag.
diff --git a/docs/book/02-terminology.md b/docs/book/02-terminology.md
@@ -16,7 +16,7 @@ Define terms exactly as used by code and tests.
 - **block_hash**: ordered sequence of normalized statement hashes in a fixed window
 - **segment_hash**: hash of an ordered segment window
 - **segment_sig**: hash of a sorted segment window used for candidate grouping
-- **python_tag**: runtime compatibility tag like `cp313`
+- **python_tag**: runtime compatibility tag like `cp314`
 - **schema_version**:
     - baseline schema in `meta.schema_version`
     - cache schema in top-level `v`
diff --git a/docs/book/appendix/b-schema-layouts.md b/docs/book/appendix/b-schema-layouts.md
@@ -12,7 +12,7 @@ Compact structural layouts for baseline/cache/report contracts in `2.0.0b6`.
     "generator": { "name": "codeclone", "version": "2.0.0b6" },
     "schema_version": "2.1",
     "fingerprint_version": "1",
-    "python_tag": "cp313",
+    "python_tag": "cp314",
     "created_at": "2026-03-11T00:00:00Z",
     "payload_sha256": "...",
     "metrics_payload_sha256": "...",
@@ -62,7 +62,7 @@ Notes:
   "meta": {
     "generator": { "name": "codeclone", "version": "2.0.0b6" },
     "schema_version": "1.2",
-    "python_tag": "cp313",
+    "python_tag": "cp314",
     "created_at": "2026-03-11T00:00:00Z",
     "payload_sha256": "...",
     "api_surface_payload_sha256": "..."
@@ -97,7 +97,7 @@ Notes:
 {
   "v": "2.5",
   "payload": {
-    "py": "cp313",
+    "py": "cp314",
     "fp": "1",
     "ap": {
       "min_loc": 10,
diff --git a/docs/cfg.md b/docs/cfg.md
@@ -186,7 +186,7 @@ This is critical for CI usage and baseline comparison.
 ## Python Tag Consistency for Baseline Checks
 
 Due to AST differences between interpreter versions, baseline compatibility is pinned to
-the same `python_tag` (for example `cp313`), not full patch version equality.
+the same `python_tag` (for example `cp314`), not full patch version equality.
 
 This keeps clone detection deterministic while allowing patch updates within the same tag.
 
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -6,10 +6,12 @@
 
 from __future__ import annotations
 
+import sys
 from collections.abc import Callable
 
 import pytest
 
+from codeclone.baseline.trust import current_python_tag
 from codeclone.contracts import CACHE_VERSION, REPORT_SCHEMA_VERSION
 
 ReportMetaFactory = Callable[..., dict[str, object]]
@@ -18,15 +20,17 @@
 @pytest.fixture
 def report_meta_factory() -> ReportMetaFactory:
     def _make(**overrides: object) -> dict[str, object]:
+        runtime_tag = current_python_tag()
+        runtime_version = f"{sys.version_info.major}.{sys.version_info.minor}"
         meta: dict[str, object] = {
             "report_schema_version": REPORT_SCHEMA_VERSION,
             "codeclone_version": "1.4.0",
-            "python_version": "3.13",
-            "python_tag": "cp313",
+            "python_version": runtime_version,
+            "python_tag": runtime_tag,
             "baseline_path": "/repo/codeclone.baseline.json",
             "baseline_fingerprint_version": "1",
             "baseline_schema_version": "1.0",
-            "baseline_python_tag": "cp313",
+            "baseline_python_tag": runtime_tag,
             "baseline_generator_name": "codeclone",
             "baseline_generator_version": "1.4.0",
             "baseline_payload_sha256": "a" * 64,
diff --git a/tests/fixtures/golden_project/golden_expected_ids.json b/tests/fixtures/golden_project/golden_expected_ids.json
@@ -1,6 +1,6 @@
 {
   "meta": {
-    "python_tag": "cp313"
+    "python_tag": "cp314"
   },
   "function_group_keys": [
     "efc8465229b381a3a50502d59d9539c0be3efe86|20-49"
diff --git a/tests/fixtures/golden_v2/clone_metrics_cycle/golden_expected_snapshot.json b/tests/fixtures/golden_v2/clone_metrics_cycle/golden_expected_snapshot.json
@@ -30,7 +30,7 @@
     ]
   },
   "meta": {
-    "python_tag": "cp313"
+    "python_tag": "cp314"
   },
   "metrics": {
     "cohesion_max": 2,
diff --git a/tests/fixtures/golden_v2/pyproject_defaults/golden_expected_cli_snapshot.json b/tests/fixtures/golden_v2/pyproject_defaults/golden_expected_cli_snapshot.json
@@ -1,6 +1,6 @@
 {
   "meta": {
-    "python_tag": "cp313"
+    "python_tag": "cp314"
   },
   "report_schema_version": "2.9",
   "project_name": "pyproject_defaults",
diff --git a/tests/fixtures/golden_v2/test_only_usage/golden_expected_snapshot.json b/tests/fixtures/golden_v2/test_only_usage/golden_expected_snapshot.json
@@ -17,7 +17,7 @@
     "segment_keys": []
   },
   "meta": {
-    "python_tag": "cp313"
+    "python_tag": "cp314"
   },
   "metrics": {
     "cohesion_max": 0,
diff --git a/tests/test_cli_inprocess.py b/tests/test_cli_inprocess.py
diff --git a/tests/test_html_report.py b/tests/test_html_report.py
diff --git a/tests/test_html_report_helpers.py b/tests/test_html_report_helpers.py
diff --git a/tests/test_report.py b/tests/test_report.py
diff --git a/tests/test_report_contract_coverage.py b/tests/test_report_contract_coverage.py
