feat(report): add baseline provenance metadata to html/text/json and raise test coverage to 100%

Author: orenlab

README.md

@@ -140,6 +140,11 @@ codeclone . \
   --text .cache/codeclone/report.txt
 ```
 
+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).
+
 Generate an HTML report:
 
 ```bash

codeclone/cli.py

@@ -33,7 +33,7 @@
     build_segment_groups,
     prepare_segment_report_groups,
     to_json_report,
-    to_text,
+    to_text_report,
 )
 from .scanner import iter_py_files, module_name_from_path
 
@@ -181,6 +181,33 @@ def _validate_output_path(path: str, *, expected_suffix: str, label: str) -> Pat
     return out.resolve()
 
 
+def _current_python_version() -> str:
+    return f"{sys.version_info.major}.{sys.version_info.minor}"
+
+
+def _build_report_meta(
+    *,
+    baseline_path: Path,
+    baseline: Baseline,
+    baseline_loaded: bool,
+    baseline_status: str,
+    cache_path: Path,
+    cache_used: bool,
+) -> dict[str, Any]:
+    return {
+        "codeclone_version": __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,
+    }
+
+
 def main() -> None:
     ap = argparse.ArgumentParser(
         prog="codeclone",
@@ -664,53 +691,74 @@ def process_sequential(with_progress: bool) -> None:
 
     baseline = Baseline(baseline_path)
     baseline_exists = baseline_path.exists()
+    baseline_loaded = False
+    baseline_status = "missing"
+    baseline_failure_code: int | None = None
 
     if baseline_exists:
-        baseline.load()
-        if not args.update_baseline:
-            if baseline.baseline_version != __version__:
-                if baseline.baseline_version is None:
-                    console.print(
-                        "[error]Baseline version mismatch.[/error]\n"
-                        "Baseline version missing (legacy baseline format).\n"
-                        f"Current version: {__version__}.\n"
-                        "Please regenerate the baseline with --update-baseline."
-                    )
-                else:
-                    console.print(
-                        "[error]Baseline version mismatch.[/error]\n"
-                        "Baseline was generated with CodeClone "
-                        f"{baseline.baseline_version}.\n"
-                        f"Current version: {__version__}.\n"
-                        "Please regenerate the baseline with --update-baseline."
-                    )
-                sys.exit(2)
-            if (
-                baseline.schema_version is not None
-                and baseline.schema_version != BASELINE_SCHEMA_VERSION
-            ):
+        try:
+            baseline.load()
+        except ValueError as e:
+            baseline_status = "invalid"
+            if not args.update_baseline:
                 console.print(
-                    "[error]Baseline schema version mismatch.[/error]\n"
-                    f"Baseline schema: {baseline.schema_version}. "
-                    f"Current schema: {BASELINE_SCHEMA_VERSION}.\n"
+                    "[error]Invalid baseline file.[/error]\n"
+                    f"{e}\n"
                     "Please regenerate the baseline with --update-baseline."
                 )
-                sys.exit(2)
-        if not args.update_baseline and baseline.python_version:
-            current_version = f"{sys.version_info.major}.{sys.version_info.minor}"
-            if baseline.python_version != current_version:
-                console.print(
-                    "[warning]Baseline Python version mismatch.[/warning]\n"
-                    f"Baseline was generated with Python {baseline.python_version}.\n"
-                    f"Current interpreter: Python {current_version}."
-                )
-                if args.fail_on_new:
+                baseline_failure_code = 2
+        else:
+            baseline_loaded = True
+            baseline_status = "ok"
+            if not args.update_baseline:
+                if baseline.baseline_version != __version__:
+                    baseline_status = "mismatch"
+                    if baseline.baseline_version is None:
+                        console.print(
+                            "[error]Baseline version mismatch.[/error]\n"
+                            "Baseline version missing (legacy baseline format).\n"
+                            f"Current version: {__version__}.\n"
+                            "Please regenerate the baseline with --update-baseline."
+                        )
+                    else:
+                        console.print(
+                            "[error]Baseline version mismatch.[/error]\n"
+                            "Baseline was generated with CodeClone "
+                            f"{baseline.baseline_version}.\n"
+                            f"Current version: {__version__}.\n"
+                            "Please regenerate the baseline with --update-baseline."
+                        )
+                    baseline_failure_code = 2
+                if (
+                    baseline.schema_version is not None
+                    and baseline.schema_version != BASELINE_SCHEMA_VERSION
+                ):
+                    baseline_status = "mismatch"
                     console.print(
-                        "[error]Baseline checks require the same Python version to "
-                        "ensure deterministic results. Please regenerate the baseline "
-                        "using the current interpreter.[/error]"
+                        "[error]Baseline schema version mismatch.[/error]\n"
+                        f"Baseline schema: {baseline.schema_version}. "
+                        f"Current schema: {BASELINE_SCHEMA_VERSION}.\n"
+                        "Please regenerate the baseline with --update-baseline."
+                    )
+                    baseline_failure_code = 2
+            if not args.update_baseline and baseline.python_version:
+                current_version = _current_python_version()
+                if baseline.python_version != current_version:
+                    baseline_status = "mismatch"
+                    console.print(
+                        "[warning]Baseline Python version mismatch.[/warning]\n"
+                        "Baseline was generated with Python "
+                        f"{baseline.python_version}.\n"
+                        f"Current interpreter: Python {current_version}."
                     )
-                    sys.exit(2)
+                    if args.fail_on_new:
+                        console.print(
+                            "[error]Baseline checks require the same Python version to "
+                            "ensure deterministic results. Please regenerate the "
+                            "baseline "
+                            "using the current interpreter.[/error]"
+                        )
+                        baseline_failure_code = 2
     else:
         if not args.update_baseline:
             console.print(
@@ -735,6 +783,15 @@ def process_sequential(with_progress: bool) -> None:
         # When updating, we don't fail on new, we just saved the new state.
         # But we might still want to print the summary.
 
+    report_meta = _build_report_meta(
+        baseline_path=baseline_path,
+        baseline=baseline,
+        baseline_loaded=baseline_loaded,
+        baseline_status=baseline_status,
+        cache_path=cache_path.resolve(),
+        cache_used=cache.load_warning is None,
+    )
+
     # Diff
     new_func, new_block = baseline.diff(func_groups, block_groups)
     new_clones_count = len(new_func) + len(new_block)
@@ -770,6 +827,7 @@ def process_sequential(with_progress: bool) -> None:
                 func_groups=func_groups,
                 block_groups=block_groups,
                 segment_groups=segment_groups,
+                report_meta=report_meta,
                 title="CodeClone Report",
                 context_lines=3,
                 max_snippet_lines=220,
@@ -784,7 +842,7 @@ def process_sequential(with_progress: bool) -> None:
         out = json_out_path
         out.parent.mkdir(parents=True, exist_ok=True)
         out.write_text(
-            to_json_report(func_groups, block_groups, segment_groups),
+            to_json_report(func_groups, block_groups, segment_groups, report_meta),
             "utf-8",
         )
         if not args.quiet:
@@ -794,17 +852,20 @@ def process_sequential(with_progress: bool) -> None:
         out = text_out_path
         out.parent.mkdir(parents=True, exist_ok=True)
         out.write_text(
-            "FUNCTION CLONES\n"
-            + to_text(func_groups)
-            + "\nBLOCK CLONES\n"
-            + to_text(block_groups)
-            + "\nSEGMENT CLONES\n"
-            + to_text(segment_groups),
+            to_text_report(
+                meta=report_meta,
+                func_groups=func_groups,
+                block_groups=block_groups,
+                segment_groups=segment_groups,
+            ),
             "utf-8",
         )
         if not args.quiet:
             console.print(f"[info]Text report saved:[/info] {out}")
 
+    if baseline_failure_code is not None:
+        sys.exit(baseline_failure_code)
+
     # Exit Codes
     if args.fail_on_new and (new_func or new_block):
         default_report = Path(".cache/codeclone/report.html")

codeclone/html_report.py

@@ -229,6 +229,15 @@ def _escape(v: Any) -> str:
     return html.escape("" if v is None else str(v))
 
 
+def _meta_display(v: Any) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if v is None:
+        return "n/a"
+    text = str(v).strip()
+    return text if text else "n/a"
+
+
 def _group_sort_key(items: list[dict[str, Any]]) -> tuple[int, int]:
     return (
         -len(items),
@@ -241,6 +250,7 @@ def build_html_report(
     func_groups: dict[str, list[dict[str, Any]]],
     block_groups: dict[str, list[dict[str, Any]]],
     segment_groups: dict[str, list[dict[str, Any]]],
+    report_meta: dict[str, Any] | None = None,
     title: str = "CodeClone Report",
     context_lines: int = 3,
     max_snippet_lines: int = 220,
@@ -404,6 +414,8 @@ def render_section(
 
             out.append(
                 f'<div class="group" data-group="{section_id}" '
+                f'data-group-index="{idx}" '
+                f'data-group-key="{_escape(gkey)}" '
                 f'data-search="{search_blob_escaped}">'
             )
 
@@ -416,7 +428,7 @@ def render_section(
                 f'<span class="pill small {pill_cls}">{len(items)} items</span>'
                 "</div>"
                 '<div class="group-right">'
-                f'<code class="gkey">{_escape(gkey)}</code>'
+                f'<code class="gkey" title="{_escape(gkey)}">{_escape(gkey)}</code>'
                 "</div>"
                 "</div>"
             )
@@ -437,16 +449,18 @@ def render_section(
                         max_lines=max_snippet_lines,
                     )
 
+                    qualname = _escape(item["qualname"])
+                    filepath = _escape(item["filepath"])
+                    start_line = int(item["start_line"])
+                    end_line = int(item["end_line"])
                     out.append(
-                        '<div class="item">'
-                        f'<div class="item-head" title="{_escape(item["qualname"])}">'
-                        f"{_escape(item['qualname'])}"
-                        "</div>"
+                        f'<div class="item" data-qualname="{qualname}" '
+                        f'data-filepath="{filepath}" data-start-line="{start_line}" '
+                        f'data-end-line="{end_line}">'
+                        f'<div class="item-head" title="{qualname}">{qualname}</div>'
                         f'<div class="item-file" '
-                        f'title="{_escape(item["filepath"])}:'
-                        f'{item["start_line"]}-{item["end_line"]}">'
-                        f"{_escape(item['filepath'])}:"
-                        f"{item['start_line']}-{item['end_line']}"
+                        f'title="{filepath}:{start_line}-{end_line}">'
+                        f"{filepath}:{start_line}-{end_line}"
                         f"</div>"
                         f"{snippet.code_html}"
                         "</div>"
@@ -489,11 +503,61 @@ def render_section(
         "segments", "Segment clones", segment_sorted, "pill-segment"
     )
 
+    meta = dict(report_meta or {})
+    meta_rows: list[tuple[str, Any]] = [
+        ("CodeClone", meta.get("codeclone_version", __version__)),
+        ("Python", meta.get("python_version")),
+        ("Baseline", meta.get("baseline_path")),
+        ("Baseline version", meta.get("baseline_version")),
+        ("Baseline schema", meta.get("baseline_schema_version")),
+        ("Baseline Python", meta.get("baseline_python_version")),
+        ("Baseline loaded", meta.get("baseline_loaded")),
+        ("Baseline status", meta.get("baseline_status")),
+    ]
+    if "cache_path" in meta:
+        meta_rows.append(("Cache path", meta.get("cache_path")))
+    if "cache_used" in meta:
+        meta_rows.append(("Cache used", meta.get("cache_used")))
+
+    meta_attrs = " ".join(
+        [
+            (
+                'data-codeclone-version="'
+                f'{_escape(meta.get("codeclone_version", __version__))}"'
+            ),
+            f'data-python-version="{_escape(meta.get("python_version"))}"',
+            f'data-baseline-path="{_escape(meta.get("baseline_path"))}"',
+            f'data-baseline-version="{_escape(meta.get("baseline_version"))}"',
+            f'data-baseline-schema-version="{_escape(meta.get("baseline_schema_version"))}"',
+            f'data-baseline-python-version="{_escape(meta.get("baseline_python_version"))}"',
+            f'data-baseline-loaded="{_escape(_meta_display(meta.get("baseline_loaded")))}"',
+            f'data-baseline-status="{_escape(meta.get("baseline_status"))}"',
+            f'data-cache-path="{_escape(meta.get("cache_path"))}"',
+            f'data-cache-used="{_escape(_meta_display(meta.get("cache_used")))}"',
+        ]
+    )
+    meta_rows_html = "".join(
+        (
+            '<div class="meta-row">'
+            f"<dt>{_escape(label)}</dt>"
+            f"<dd>{_escape(_meta_display(value))}</dd>"
+            "</div>"
+        )
+        for label, value in meta_rows
+    )
+    report_meta_html = (
+        f'<section class="meta-panel" id="report-meta" {meta_attrs}>'
+        '<div class="meta-title">Report Provenance</div>'
+        f'<dl class="meta-grid">{meta_rows_html}</dl>'
+        "</section>"
+    )
+
     return REPORT_TEMPLATE.substitute(
         title=_escape(title),
         version=__version__,
         pyg_dark=pyg_dark,
         pyg_light=pyg_light,
+        report_meta_html=report_meta_html,
         empty_state_html=empty_state_html,
         func_section=func_section,
         block_section=block_section,