feat(baseline): tamper-evident baseline contract

Author: orenlab

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## [1.3.0] - 2026-02-05
+## [1.3.0] - 2026-02-08
 
 ### Overview
 
@@ -63,6 +63,14 @@ the HTML report UI, and introduces baseline versioning.
 
 - Baselines are now **versioned** and include a schema version.
 - Mismatched baseline versions **fail fast** and require regeneration.
+- Baseline loading is now strict: invalid schema/types or oversized baseline files
+  fail fast to preserve CI integrity.
+- Added baseline tamper-evident integrity for v1.3+ files (`generator`, `payload_sha256`)
+  while keeping legacy baseline behavior as explicit regeneration-required fail-fast.
+- Added configurable size guards (`--max-baseline-size-mb`, `--max-cache-size-mb`):
+  oversized baseline fails fast, oversized cache is ignored with warning.
+- Behavioral hardening (CLI): baseline validation is now an explicit contract
+  (legacy/version/schema/python/integrity/size states) with deterministic fail-fast behavior.
 
 **Breaking (CI):** baseline version mismatch now fails hard; CI requires baseline regeneration on upgrade.
 
@@ -104,12 +112,20 @@ codeclone . --update-baseline
 - **Segment reporting**  
   Added a dedicated “Segment clones” section and summary metric in HTML/TXT/JSON outputs.
 
+- **Escaping and snippet resilience**  
+  Hardened HTML escaping for text and attribute contexts, and added a safe fallback when
+  source snippets are unavailable during report rendering.
+
 ### Cache & Internals
 
 - Extended cache schema to store segment fingerprints (cache version bump).
 - Default cache location moved to `<root>/.cache/codeclone/cache.json` (project‑local).
 - Added a legacy cache warning for `~/.cache/codeclone/cache.json` with guidance to
   delete it and add `.cache/` to `.gitignore`.
+- Strengthened cache integrity handling with constant-time signature checks and explicit
+  warnings for oversized cache files.
+- Added deterministic deep-schema cache entry validation (`stat/units/blocks/segments`);
+  invalid cache entries are ignored instead of affecting analysis results.
 
 ### Packaging
 
@@ -124,6 +140,8 @@ codeclone . --update-baseline
 ### Testing & Security
 
 - Expanded security tests (HTML escaping and safety checks).
+- Added regression tests for deterministic report ordering across HTML/TXT/JSON,
+  baseline/cache integrity edge cases, and symlink traversal/loop safety.
 
 ---
 

README.md

@@ -144,6 +144,9 @@ All report formats include provenance metadata for auditability:
 `codeclone_version`, `python_version`, `baseline_path`, `baseline_version`,
 `baseline_schema_version`, `baseline_python_version`, `baseline_loaded`,
 `baseline_status` (and cache metadata when available).
+`baseline_status` values: `ok`, `missing`, `legacy`, `invalid`,
+`mismatch_version`, `mismatch_schema`, `mismatch_python`,
+`generator_mismatch`, `integrity_missing`, `integrity_failed`, `too_large`.
 
 Generate an HTML report:
 
@@ -171,6 +174,9 @@ Commit the generated baseline file to the repository.
 
 Baselines are **versioned**. If CodeClone is upgraded, regenerate the baseline to keep
 CI deterministic and explainable.
+Baseline format in 1.3+ is tamper-evident (`generator`, `payload_sha256`) and validated
+before baseline comparison.
+Invalid or oversized baseline files fail fast in CI mode and must be regenerated.
 
 ### 2. Use in CI
 
@@ -207,6 +213,11 @@ You can override this path with `--cache-path` (`--cache-dir` is a legacy alias)
 If you used an older version of CodeClone, delete the legacy cache file at
 `~/.cache/codeclone/cache.json` and add `.cache/` to `.gitignore`.
 
+Cache integrity checks are strict: signature mismatch or oversized cache files are ignored
+with an explicit warning, then rebuilt from source.
+Cache entries are validated against expected structure/types; invalid entries are ignored
+deterministically.
+
 ### Python Version Consistency for Baseline Checks
 
 Due to inherent differences in Python’s AST between interpreter versions, baseline
@@ -294,7 +305,9 @@ See full design and semantics:
 | `--processes`                 | Number of worker processes                                       | `4`                                  |
 | `--cache-path FILE`           | Cache file path                                                  | `<root>/.cache/codeclone/cache.json` |
 | `--cache-dir FILE`            | Legacy alias for `--cache-path`                                  | -                                    |
+| `--max-cache-size-mb MB`      | Max cache size before ignore + warning                           | `50`                                 |
 | `--baseline FILE`             | Baseline file path                                               | `codeclone.baseline.json`            |
+| `--max-baseline-size-mb MB`   | Max baseline size before fail-fast                               | `5`                                  |
 | `--update-baseline`           | Regenerate baseline from current results                         | `False`                              |
 | `--fail-on-new`               | Fail if new function/block clone groups appear vs baseline       | `False`                              |
 | `--fail-threshold MAX_CLONES` | Fail if total clone groups (`function + block`) exceed threshold | `-1` (disabled)                      |

SECURITY.md

@@ -36,9 +36,11 @@ ongoing security review.
 
 Additional safeguards:
 
-- HTML report content is escaped to prevent script injection.
+- HTML report content is escaped in both text and attribute contexts to prevent script injection.
 - Reports are static and do not execute analyzed code.
-- Cache files are HMAC-signed; signature mismatches are ignored.
+- Scanner traversal is root-confined and prevents symlink-based path escape.
+- Baseline files are schema/type validated with size limits; invalid baselines fail fast.
+- Cache files are HMAC-signed (constant-time comparison), size-limited, and ignored on mismatch.
 - Cache secrets are stored next to the cache (`.cache_secret`) and must not be committed.
 
 ---

codeclone.baseline.json

@@ -1,7 +1,12 @@
 {
-  "functions": [],
+  "functions": [
+    "15f730bde91427ef6cc7878fd98d8f9d2ca3b57e|20-49"
+  ],
   "blocks": [],
   "python_version": "3.13",
   "baseline_version": "1.3.0",
-  "schema_version": 1
+  "schema_version": 1,
+  "generator": "codeclone",
+  "payload_sha256": "ab5bbbe4c098b6aae44202f69c7f26398d4d85ae759ca096418d6fc054571cf1",
+  "created_at": "2026-02-08T09:06:10+00:00"
 }

codeclone/_cli_args.py

@@ -0,0 +1,161 @@
+"""
+CodeClone — AST and CFG-based code clone detector for Python
+focused on architectural duplication.
+
+Copyright (c) 2026 Den Rozhnovskiy
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import cast
+
+from . import ui_messages as ui
+
+
+class _HelpFormatter(argparse.ArgumentDefaultsHelpFormatter):
+    def _get_help_string(self, action: argparse.Action) -> str:
+        if action.dest == "cache_path":
+            return action.help or ""
+        return cast(str, super()._get_help_string(action))
+
+
+def build_parser(version: str) -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="codeclone",
+        description="AST and CFG-based code clone detector for Python.",
+        formatter_class=_HelpFormatter,
+    )
+    ap.add_argument(
+        "--version",
+        action="version",
+        version=ui.version_output(version),
+        help=ui.HELP_VERSION,
+    )
+
+    core_group = ap.add_argument_group("Target")
+    core_group.add_argument(
+        "root",
+        nargs="?",
+        default=".",
+        help=ui.HELP_ROOT,
+    )
+
+    tune_group = ap.add_argument_group("Analysis Tuning")
+    tune_group.add_argument(
+        "--min-loc",
+        type=int,
+        default=15,
+        help=ui.HELP_MIN_LOC,
+    )
+    tune_group.add_argument(
+        "--min-stmt",
+        type=int,
+        default=6,
+        help=ui.HELP_MIN_STMT,
+    )
+    tune_group.add_argument(
+        "--processes",
+        type=int,
+        default=4,
+        help=ui.HELP_PROCESSES,
+    )
+    tune_group.add_argument(
+        "--cache-path",
+        dest="cache_path",
+        metavar="FILE",
+        default=None,
+        help=ui.HELP_CACHE_PATH,
+    )
+    tune_group.add_argument(
+        "--cache-dir",
+        dest="cache_path",
+        metavar="FILE",
+        default=None,
+        help=ui.HELP_CACHE_DIR_LEGACY,
+    )
+    tune_group.add_argument(
+        "--max-cache-size-mb",
+        type=int,
+        default=50,
+        metavar="MB",
+        help=ui.HELP_MAX_CACHE_SIZE_MB,
+    )
+
+    ci_group = ap.add_argument_group("Baseline & CI/CD")
+    ci_group.add_argument(
+        "--baseline",
+        default="codeclone.baseline.json",
+        help=ui.HELP_BASELINE,
+    )
+    ci_group.add_argument(
+        "--max-baseline-size-mb",
+        type=int,
+        default=5,
+        metavar="MB",
+        help=ui.HELP_MAX_BASELINE_SIZE_MB,
+    )
+    ci_group.add_argument(
+        "--update-baseline",
+        action="store_true",
+        help=ui.HELP_UPDATE_BASELINE,
+    )
+    ci_group.add_argument(
+        "--fail-on-new",
+        action="store_true",
+        help=ui.HELP_FAIL_ON_NEW,
+    )
+    ci_group.add_argument(
+        "--fail-threshold",
+        type=int,
+        default=-1,
+        metavar="MAX_CLONES",
+        help=ui.HELP_FAIL_THRESHOLD,
+    )
+    ci_group.add_argument(
+        "--ci",
+        action="store_true",
+        help=ui.HELP_CI,
+    )
+
+    out_group = ap.add_argument_group("Reporting")
+    out_group.add_argument(
+        "--html",
+        dest="html_out",
+        metavar="FILE",
+        help=ui.HELP_HTML,
+    )
+    out_group.add_argument(
+        "--json",
+        dest="json_out",
+        metavar="FILE",
+        help=ui.HELP_JSON,
+    )
+    out_group.add_argument(
+        "--text",
+        dest="text_out",
+        metavar="FILE",
+        help=ui.HELP_TEXT,
+    )
+    out_group.add_argument(
+        "--no-progress",
+        action="store_true",
+        help=ui.HELP_NO_PROGRESS,
+    )
+    out_group.add_argument(
+        "--no-color",
+        action="store_true",
+        help=ui.HELP_NO_COLOR,
+    )
+    out_group.add_argument(
+        "--quiet",
+        action="store_true",
+        help=ui.HELP_QUIET,
+    )
+    out_group.add_argument(
+        "--verbose",
+        action="store_true",
+        help=ui.HELP_VERBOSE,
+    )
+    return ap

codeclone/_cli_meta.py

@@ -0,0 +1,43 @@
+"""
+CodeClone — AST and CFG-based code clone detector for Python
+focused on architectural duplication.
+
+Copyright (c) 2026 Den Rozhnovskiy
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+from .baseline import Baseline
+
+
+def _current_python_version() -> str:
+    return f"{sys.version_info.major}.{sys.version_info.minor}"
+
+
+def _build_report_meta(
+    *,
+    codeclone_version: str,
+    baseline_path: Path,
+    baseline: Baseline,
+    baseline_loaded: bool,
+    baseline_status: str,
+    cache_path: Path,
+    cache_used: bool,
+) -> dict[str, Any]:
+    return {
+        "codeclone_version": codeclone_version,
+        "python_version": _current_python_version(),
+        "baseline_path": str(baseline_path),
+        "baseline_version": baseline.baseline_version,
+        "baseline_schema_version": baseline.schema_version,
+        "baseline_python_version": baseline.python_version,
+        "baseline_loaded": baseline_loaded,
+        "baseline_status": baseline_status,
+        "cache_path": str(cache_path),
+        "cache_used": cache_used,
+    }

codeclone/_cli_paths.py

@@ -0,0 +1,36 @@
+"""
+CodeClone — AST and CFG-based code clone detector for Python
+focused on architectural duplication.
+
+Copyright (c) 2026 Den Rozhnovskiy
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+from rich.console import Console
+
+
+def expand_path(p: str) -> Path:
+    return Path(p).expanduser().resolve()
+
+
+def _validate_output_path(
+    path: str,
+    *,
+    expected_suffix: str,
+    label: str,
+    console: Console,
+    invalid_message: Callable[..., str],
+) -> Path:
+    out = Path(path).expanduser()
+    if out.suffix.lower() != expected_suffix:
+        console.print(
+            invalid_message(label=label, path=out, expected_suffix=expected_suffix)
+        )
+        sys.exit(2)
+    return out.resolve()