feat(core): UI improvements, updating report schemas; adding new formats (md, sarif); multiple hot path optimizations and other improvements

Author: orenlab

CHANGELOG.md

@@ -9,7 +9,7 @@ This beta introduces:
 
 - a new stage-based architecture
 - unified clone + metrics baseline flow
-- report schema `2.0`, cache schema `2.0`, and richer report provenance
+- 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
@@ -41,8 +41,15 @@ final `2.0.0` release.
 - Added unified baseline flow with optional top-level `metrics` stored in the same baseline file as clone keys.
 - 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.0`.
-- Bumped report schema to `2.0`.
+- 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.
 
 ### Configuration and CLI UX
 
@@ -52,6 +59,8 @@ final `2.0.0` release.
 - 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 path flags for default-path intent:
     - `--baseline`
@@ -110,7 +119,8 @@ 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
+- Added 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.
@@ -137,7 +147,7 @@ final `2.0.0` release.
   `pre-commit run --all-files` passes with the CI gate enabled.
 - Added targeted branch and invariant tests for `baseline`, `cache`, `cli`, `html_report`, `extractor`,
   `pipeline.process`, and metrics modules.
-- Full suite now reaches `100%` coverage.
+- Coverage gate is enforced at `>=99%` with contract-focused branch/invariant tests.
 
 ### Stability Notes
 

README.md

@@ -27,7 +27,7 @@ all with baseline-aware governance that separates **known** technical debt from
 - **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
-- **Reports** — interactive HTML, deterministic JSON (schema v2.0), plain text — all with NEW/KNOWN split
+- **Reports** — interactive HTML, deterministic JSON/TXT plus Markdown and SARIF projections from one canonical report
 - **CI-first** — deterministic output, stable ordering, exit code contract, pre-commit support
 - **Fast** — incremental caching, parallel processing, warm-run optimization
 
@@ -38,6 +38,7 @@ pip install codeclone        # or: uv tool install codeclone
 
 codeclone .                  # analyze current directory
 codeclone . --html           # generate HTML report
+codeclone . --json --md --sarif --text   # generate machine-readable reports
 codeclone . --ci             # CI mode (--fail-on-new --no-color --quiet)
 ```
 
@@ -103,6 +104,9 @@ skip_metrics = false
 quiet = true
 html_out = ".cache/codeclone/report.html"
 json_out = ".cache/codeclone/report.json"
+md_out = ".cache/codeclone/report.md"
+sarif_out = ".cache/codeclone/report.sarif"
+text_out = ".cache/codeclone/report.txt"
 ```
 
 Precedence: CLI flags > `pyproject.toml` > built-in defaults.
@@ -135,54 +139,48 @@ Contract errors (`2`) take precedence over gating failures (`3`).
 |--------|----------|--------------------------------|
 | HTML   | `--html` | `.cache/codeclone/report.html` |
 | JSON   | `--json` | `.cache/codeclone/report.json` |
+| Markdown | `--md` | `.cache/codeclone/report.md` |
+| SARIF  | `--sarif` | `.cache/codeclone/report.sarif` |
 | Text   | `--text` | `.cache/codeclone/report.txt`  |
 
-All reports include NEW/KNOWN split, matched code snippets, and provenance metadata.
+All report formats are rendered from one canonical JSON report document.
 
 <details>
-<summary>JSON report shape (v2.0)</summary>
+<summary>JSON report shape (v2.1)</summary>
 
 ```json
 {
-  "report_schema_version": "2.0",
+  "report_schema_version": "2.1",
   "meta": {
+    "codeclone_version": "2.0.0b1",
     "project_name": "...",
-    "scan_root": "..."
+    "scan_root": "...",
+    "report_mode": "full",
+    "baseline": { "...": "..." },
+    "cache": { "...": "..." },
+    "metrics_baseline": { "...": "..." },
+    "runtime": { "report_generated_at_utc": "..." }
   },
-  "files": [],
-  "groups": {
-    "functions": {},
-    "blocks": {},
-    "segments": {}
+  "inventory": {
+    "files": { "...": "..." },
+    "code": { "...": "..." },
+    "file_registry": { "encoding": "relative_path", "items": [] }
   },
-  "groups_split": {
-    "functions": {
-      "new": [],
-      "known": []
-    },
-    "blocks": {
-      "new": [],
-      "known": []
-    },
-    "segments": {
-      "new": [],
-      "known": []
+  "findings": {
+    "summary": { "...": "..." },
+    "groups": {
+      "clones": { "functions": [], "blocks": [], "segments": [] },
+      "structural": { "groups": [] },
+      "dead_code": { "groups": [] },
+      "design": { "groups": [] }
     }
   },
-  "group_item_layout": {
-    "functions": [
-      "..."
-    ],
-    "blocks": [
-      "..."
-    ],
-    "segments": [
-      "..."
-    ]
-  },
-  "facts": {},
-  "metrics": {},
-  "suggestions": []
+  "metrics": { "summary": {}, "families": {} },
+  "derived": { "suggestions": [], "overview": {}, "hotlists": {} },
+  "integrity": {
+    "canonicalization": { "version": "1", "scope": "canonical_only" },
+    "digest": { "algorithm": "sha256", "verified": true, "value": "..." }
+  }
 }
 ```
 

SECURITY.md

@@ -9,6 +9,7 @@ The following versions currently receive security updates:
 
 | Version | Supported |
 |---------|-----------|
+| 2.0.x   | Yes       |
 | 1.4.x   | Yes       |
 | 1.3.x   | No        |
 | 1.2.x   | No        |
@@ -42,7 +43,7 @@ Additional safeguards:
 - Report explainability fields are generated in Python core; UI is rendering-only and does not infer semantics.
 - Scanner traversal is root-confined and prevents symlink-based path escape.
 - Baseline files are schema/type validated with size limits and tamper-evident integrity fields
-  (`meta.generator` as trust gate, `meta.payload_sha256` as integrity hash in baseline v1).
+  (`meta.generator` as trust gate, `meta.payload_sha256` as integrity hash in baseline schema `2.0`).
 - Baseline integrity is tamper-evident (audit signal), not tamper-proof cryptographic signing.
   An actor who can rewrite baseline content and recompute `payload_sha256` can still alter it.
 - Baseline hash covers canonical payload only (`clones.functions`, `clones.blocks`,

codeclone/_cli_args.py

@@ -20,6 +20,8 @@
 DEFAULT_BASELINE_PATH = "codeclone.baseline.json"
 DEFAULT_HTML_REPORT_PATH = ".cache/codeclone/report.html"
 DEFAULT_JSON_REPORT_PATH = ".cache/codeclone/report.json"
+DEFAULT_MARKDOWN_REPORT_PATH = ".cache/codeclone/report.md"
+DEFAULT_SARIF_REPORT_PATH = ".cache/codeclone/report.sarif"
 DEFAULT_TEXT_REPORT_PATH = ".cache/codeclone/report.txt"
 
 
@@ -255,6 +257,22 @@ def build_parser(version: str) -> argparse.ArgumentParser:
         const=DEFAULT_JSON_REPORT_PATH,
         help=ui.HELP_JSON,
     )
+    out_group.add_argument(
+        "--md",
+        dest="md_out",
+        nargs="?",
+        metavar="FILE",
+        const=DEFAULT_MARKDOWN_REPORT_PATH,
+        help=ui.HELP_MD,
+    )
+    out_group.add_argument(
+        "--sarif",
+        dest="sarif_out",
+        nargs="?",
+        metavar="FILE",
+        const=DEFAULT_SARIF_REPORT_PATH,
+        help=ui.HELP_SARIF,
+    )
     out_group.add_argument(
         "--text",
         dest="text_out",

codeclone/_cli_config.py

@@ -48,6 +48,8 @@ class _ConfigKeySpec:
     "skip_dependencies": _ConfigKeySpec(bool),
     "html_out": _ConfigKeySpec(str, allow_none=True),
     "json_out": _ConfigKeySpec(str, allow_none=True),
+    "md_out": _ConfigKeySpec(str, allow_none=True),
+    "sarif_out": _ConfigKeySpec(str, allow_none=True),
     "text_out": _ConfigKeySpec(str, allow_none=True),
     "no_progress": _ConfigKeySpec(bool),
     "no_color": _ConfigKeySpec(bool),
@@ -62,6 +64,8 @@ class _ConfigKeySpec:
         "metrics_baseline",
         "html_out",
         "json_out",
+        "md_out",
+        "sarif_out",
         "text_out",
     }
 )

codeclone/_cli_meta.py

@@ -4,18 +4,24 @@
 from __future__ import annotations
 
 import sys
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import TypedDict
 
 from .baseline import Baseline, current_python_tag
-from .contracts import REPORT_SCHEMA_VERSION
 from .metrics_baseline import MetricsBaseline
 
 
 def _current_python_version() -> str:
     return f"{sys.version_info.major}.{sys.version_info.minor}"
 
 
+def _current_report_timestamp_utc() -> str:
+    return (
+        datetime.now(timezone.utc).replace(microsecond=0).strftime("%Y-%m-%dT%H:%M:%SZ")
+    )
+
+
 class ReportMeta(TypedDict):
     """
     Canonical report metadata contract shared by HTML, JSON, and TXT reports.
@@ -28,7 +34,6 @@ class ReportMeta(TypedDict):
     - cache_*: cache status/provenance for run transparency
     """
 
-    report_schema_version: str
     codeclone_version: str
     project_name: str
     scan_root: str
@@ -59,6 +64,7 @@ class ReportMeta(TypedDict):
     health_grade: str | None
     analysis_mode: str
     metrics_computed: list[str]
+    report_generated_at_utc: str
 
 
 def _build_report_meta(
@@ -85,7 +91,6 @@ def _build_report_meta(
 ) -> ReportMeta:
     project_name = scan_root.name or str(scan_root)
     return {
-        "report_schema_version": REPORT_SCHEMA_VERSION,
         "codeclone_version": codeclone_version,
         "project_name": project_name,
         "scan_root": str(scan_root),
@@ -124,4 +129,5 @@ def _build_report_meta(
         "health_grade": health_grade,
         "analysis_mode": analysis_mode,
         "metrics_computed": list(metrics_computed),
+        "report_generated_at_utc": _current_report_timestamp_utc(),
     }

codeclone/_cli_paths.py

@@ -6,19 +6,22 @@
 import sys
 from collections.abc import Callable
 from pathlib import Path
-
-from rich.console import Console
+from typing import Protocol
 
 from .contracts import ExitCode
 from .ui_messages import fmt_contract_error
 
 
+class _Printer(Protocol):
+    def print(self, *objects: object, **kwargs: object) -> None: ...
+
+
 def _validate_output_path(
     path: str,
     *,
     expected_suffix: str,
     label: str,
-    console: Console,
+    console: _Printer,
     invalid_message: Callable[..., str],
     invalid_path_message: Callable[..., str],
 ) -> Path:

codeclone/_cli_summary.py

@@ -4,9 +4,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-
-from rich.console import Console
-from rich.rule import Rule
+from typing import Protocol
 
 from . import ui_messages as ui
 
@@ -26,9 +24,13 @@ class MetricsSnapshot:
     health_grade: str
 
 
+class _Printer(Protocol):
+    def print(self, *objects: object, **kwargs: object) -> None: ...
+
+
 def _print_summary(
     *,
-    console: Console,
+    console: _Printer,
     quiet: bool,
     files_found: int,
     files_analyzed: int,
@@ -65,6 +67,8 @@ def _print_summary(
             )
         )
     else:
+        from rich.rule import Rule
+
         console.print()
         console.print(Rule(title=ui.SUMMARY_TITLE, style="dim", characters="\u2500"))
         console.print(
@@ -99,7 +103,7 @@ def _print_summary(
 
 def _print_metrics(
     *,
-    console: Console,
+    console: _Printer,
     quiet: bool,
     metrics: MetricsSnapshot,
 ) -> None:
@@ -119,6 +123,8 @@ def _print_metrics(
             )
         )
     else:
+        from rich.rule import Rule
+
         console.print()
         console.print(Rule(title=ui.METRICS_TITLE, style="dim", characters="\u2500"))
         console.print(ui.fmt_metrics_health(metrics.health_total, metrics.health_grade))