fix(cache,html): invalidate stale api-surface cache and unify report badges

- make cache analysis-profile compatibility aware of api-surface collection
- bump cache schema to 2.5 and propagate collect_api_surface through CLI and MCP cache setup
- add regressions for warm-cache api-surface runs and profile mismatch handling
- unify provenance modal chips under one badge UI and remove mixed status/bool badge styles
- polish report cards, typography, mobile wrapping, and hover treatment
- add Findings intro banner and fix dead-code suppressed summary count
- sync cache contract docs, AGENTS version table, changelog, and HTML tests

Author: orenlab

AGENTS.md

@@ -144,7 +144,7 @@ from another doc.** Current values (verified at write time):
 |-----------------------------------|------------------------------|---------------|
 | `BASELINE_SCHEMA_VERSION`         | `codeclone/contracts.py`     | `2.1`         |
 | `BASELINE_FINGERPRINT_VERSION`    | `codeclone/contracts.py`     | `1`           |
-| `CACHE_VERSION`                   | `codeclone/contracts.py`     | `2.4`         |
+| `CACHE_VERSION`                   | `codeclone/contracts.py`     | `2.5`         |
 | `REPORT_SCHEMA_VERSION`           | `codeclone/contracts.py`     | `2.8`         |
 | `METRICS_BASELINE_SCHEMA_VERSION` | `codeclone/contracts.py`     | `1.2`         |
 

CHANGELOG.md

@@ -21,7 +21,7 @@ across MCP/HTML/clients; tightens MCP launcher/runtime behavior.
   `--fail-on-docstring-regression`, `--fail-on-api-break`, `--fail-on-untested-hotspots`, `--coverage-min`.
 - Surface adoption/API/coverage-join in MCP, CLI Metrics, report payloads, and HTML (Overview + Quality subtab).
 - Preserve embedded metrics and optional `api_surface` in unified baselines.
-- Cache `2.4`: drop stale API-surface entries; preserve parameter order; align warm/cold API diffs.
+- Cache `2.5`: make analysis-profile compatibility API-surface-aware; invalidate stale non-API warm caches; preserve parameter order; align warm/cold API diffs.
 
 ### MCP, HTML, and client interpretation
 

codeclone/_html_css.py

@@ -280,7 +280,7 @@ def _tab_badge(count: int) -> str:
         f'<a href="{REPOSITORY_URL}" target="_blank" rel="noopener">CodeClone</a> '
         f'<span class="muted">v{_escape_html(version)}</span> · '
         f'<a href="{DOCS_URL}" target="_blank" rel="noopener">Docs</a> · '
-        f'<a href="{ISSUES_URL}" target="_blank" rel="noopener">Issues</a>'
+        f'<a href="{ISSUES_URL}" target="_blank" rel="noopener">Report Issue</a>'
         "</div>"
         f"{_schema_line}"
         "</footer>"

codeclone/_html_report/_assemble.py

@@ -110,7 +110,7 @@ def render_dead_code_panel(ctx: ReportContext) -> str:
         _stat_card(
             "Candidates",
             dead_total,
-            detail=_micro_badges(("active", dead_total - dead_suppressed_total)),
+            detail=_micro_badges(("active", dead_total)),
             value_tone="warn" if dead_total > 0 else "good",
             glossary_tip_fn=glossary_tip,
         ),

codeclone/_html_report/_sections/_dead_code.py

@@ -63,11 +63,19 @@ def _truncate_middle(value: str, head: int, tail: int) -> str:
     return f"{value[:head]}\u2026{value[-tail:]}"
 
 
-def _prov_badge_html(label: str, value: str, color: str) -> str:
+def _prov_badge_html(label: str | None, value: str, color: str) -> str:
+    classes = ["prov-badge", f"prov-badge--{color}"]
+    if label is None:
+        classes.append("prov-badge--inline")
+    label_html = (
+        f'<span class="prov-badge-lbl">{_escape_html(label)}</span>'
+        if label is not None
+        else ""
+    )
     return (
-        f'<span class="prov-badge prov-badge--{color}">'
+        f'<span class="{" ".join(classes)}">'
         f'<span class="prov-badge-val">{_escape_html(value)}</span>'
-        f'<span class="prov-badge-lbl">{_escape_html(label)}</span>'
+        f"{label_html}"
         "</span>"
     )
 
@@ -365,45 +373,34 @@ def render_meta_panel(ctx: ReportContext) -> str:
     _STATUS_LABELS = frozenset(
         {"Baseline status", "Metrics baseline status", "Cache status"}
     )
+    _prov_badge = _prov_badge_html
 
     runtime_python_tag = str(python_tag_value or "").strip()
 
     def _val_html(label: str, value: object) -> str:
         if label in _BOOL_LABELS and isinstance(value, bool):
             true_text, false_text = _BOOL_LABELS[label]
-            if value:
-                return (
-                    '<span class="meta-bool meta-bool-true">'
-                    f'<span class="meta-bool-icon">\u2713</span>'
-                    f'<span class="meta-bool-text">{true_text}</span>'
-                    "</span>"
-                )
-            return (
-                '<span class="meta-bool meta-bool-false">'
-                f'<span class="meta-bool-icon">\u2717</span>'
-                f'<span class="meta-bool-text">{false_text}</span>'
-                "</span>"
+            return _prov_badge(
+                None,
+                true_text if value else false_text,
+                "green" if value else "red",
             )
         if label in _STATUS_LABELS and isinstance(value, str) and value.strip():
             raw = value.strip()
             key = raw.lower()
             if key == "ok":
-                tone = "ok"
+                color = "green"
                 text = "ok"
             elif key in {"error", "failed", "fail"}:
-                tone = "err"
+                color = "red"
                 text = raw
             elif key in {"missing", "absent", "none"}:
-                tone = "warn"
+                color = "amber"
                 text = raw
             else:
-                tone = "neutral"
+                color = "neutral"
                 text = raw
-            return (
-                f'<span class="meta-status meta-status--{tone}">'
-                f'<span class="meta-status-dot"></span>'
-                f"{_escape_html(text)}</span>"
-            )
+            return _prov_badge(None, text, color)
         # Long path/hash values: middle-truncate with copy button + full title
         if (
             isinstance(value, str)
@@ -437,18 +434,9 @@ def _val_html(label: str, value: object) -> str:
         ):
             text = _escape_html(value)
             if value.strip() == runtime_python_tag:
-                badge = (
-                    '<span class="prov-match prov-match--ok" '
-                    'title="Matches runtime Python tag">'
-                    "\u2713 matches runtime</span>"
-                )
+                badge = _prov_badge(None, "matches runtime", "green")
             else:
-                badge = (
-                    '<span class="prov-match prov-match--mismatch" '
-                    f'title="Runtime is {runtime_python_tag}">'
-                    f"\u26a0 differs from runtime ({_escape_html(runtime_python_tag)})"
-                    "</span>"
-                )
+                badge = _prov_badge(None, f"runtime {runtime_python_tag}", "amber")
             return f"{text} {badge}"
         return _escape_html(_meta_display(value))
 
@@ -505,8 +493,6 @@ def _section_html(title: str, rows: list[tuple[str, object]]) -> str:
         _section_html(st, rows) for st, rows in meta_sections if rows
     )
 
-    _prov_badge = _prov_badge_html
-
     badges: list[str] = []
     if _bl_verified is True:
         badges.append(_prov_badge("Baseline", "verified", "green"))

codeclone/_html_report/_sections/_meta.py

@@ -488,10 +488,6 @@ def build_structural_findings_html_panel(
     context_lines: int = 3,
     max_snippet_lines: int = 220,
 ) -> str:
-    normalized_groups = normalize_structural_findings(groups)
-    if not normalized_groups:
-        return _tab_empty("No structural findings detected.")
-
     intro = (
         '<div class="insight-banner insight-info">'
         '<div class="insight-question">What are structural findings?</div>'
@@ -500,6 +496,9 @@ def build_structural_findings_html_panel(
         "refactoring hints and do not affect clone detection or CI verdicts.</div>"
         "</div>"
     )
+    normalized_groups = normalize_structural_findings(groups)
+    if not normalized_groups:
+        return intro + _tab_empty("No structural findings detected.")
 
     resolved_file_cache = file_cache if file_cache is not None else _FileCache()
     why_templates: list[str] = []

codeclone/_html_report/_sections/_structural.py

@@ -238,6 +238,7 @@ class AnalysisProfile(TypedDict):
     block_min_stmt: int
     segment_min_loc: int
     segment_min_stmt: int
+    collect_api_surface: bool
 
 
 class CacheData(TypedDict):
@@ -344,6 +345,7 @@ def __init__(
         block_min_stmt: int = 8,
         segment_min_loc: int = 20,
         segment_min_stmt: int = 10,
+        collect_api_surface: bool = False,
     ):
         self.path = Path(path)
         self.root = _resolve_root(root)
@@ -355,6 +357,7 @@ def __init__(
             "block_min_stmt": block_min_stmt,
             "segment_min_loc": segment_min_loc,
             "segment_min_stmt": segment_min_stmt,
+            "collect_api_surface": collect_api_surface,
         }
         self.data: CacheData = _empty_cache_data(
             version=self._CACHE_VERSION,
@@ -557,9 +560,13 @@ def _load_and_validate(self, raw_obj: object) -> CacheData | None:
             return self._reject_cache_load(
                 "Cache analysis profile mismatch "
                 f"(found min_loc={analysis_profile['min_loc']}, "
-                f"min_stmt={analysis_profile['min_stmt']}; "
+                f"min_stmt={analysis_profile['min_stmt']}, "
+                "collect_api_surface="
+                f"{str(analysis_profile['collect_api_surface']).lower()}; "
                 f"expected min_loc={self.analysis_profile['min_loc']}, "
-                f"min_stmt={self.analysis_profile['min_stmt']}); "
+                f"min_stmt={self.analysis_profile['min_stmt']}, "
+                "collect_api_surface="
+                f"{str(self.analysis_profile['collect_api_surface']).lower()}); "
                 "ignoring cache.",
                 status=CacheStatus.ANALYSIS_PROFILE_MISMATCH,
                 schema_version=version,
@@ -1482,13 +1489,18 @@ def _as_analysis_profile(value: object) -> AnalysisProfile | None:
     block_min_stmt = _as_int(obj.get("block_min_stmt"))
     segment_min_loc = _as_int(obj.get("segment_min_loc"))
     segment_min_stmt = _as_int(obj.get("segment_min_stmt"))
+    collect_api_surface_raw = obj.get("collect_api_surface", False)
+    collect_api_surface = (
+        collect_api_surface_raw if isinstance(collect_api_surface_raw, bool) else None
+    )
     if (
         min_loc is None
         or min_stmt is None
         or block_min_loc is None
         or block_min_stmt is None
         or segment_min_loc is None
         or segment_min_stmt is None
+        or collect_api_surface is None
     ):
         return None
 
@@ -1499,6 +1511,7 @@ def _as_analysis_profile(value: object) -> AnalysisProfile | None:
         block_min_stmt=block_min_stmt,
         segment_min_loc=segment_min_loc,
         segment_min_stmt=segment_min_stmt,
+        collect_api_surface=collect_api_surface,
     )
 
 

codeclone/cache.py

@@ -1372,6 +1372,7 @@ def _prepare_run_inputs() -> tuple[
         block_min_stmt=args.block_min_stmt,
         segment_min_loc=args.segment_min_loc,
         segment_min_stmt=args.segment_min_stmt,
+        collect_api_surface=bool(args.api_surface),
     )
     cache.load()
     if cache.load_warning:

codeclone/cli.py

@@ -12,7 +12,7 @@
 BASELINE_SCHEMA_VERSION: Final = "2.1"
 BASELINE_FINGERPRINT_VERSION: Final = "1"
 
-CACHE_VERSION: Final = "2.4"
+CACHE_VERSION: Final = "2.5"
 REPORT_SCHEMA_VERSION: Final = "2.8"
 METRICS_BASELINE_SCHEMA_VERSION: Final = "1.2"