feat(core): tighten report semantics and polish MCP and HTML projections

Author: orenlab

AGENTS.md

@@ -299,6 +299,7 @@ Before cutting a release:
 - Don’t introduce nondeterministic ordering (dict iteration, set ordering, filesystem traversal without sort).
 - Don’t make the base `codeclone` install depend on optional MCP runtime packages.
 - Don’t let MCP mutate baselines, source files, or repo state.
+- Don’t let MCP re-synthesize design findings from raw metrics; read canonical `findings.groups.design` only.
 
 ---
 
@@ -367,6 +368,8 @@ Use this map to route changes to the right owner module.
   `sys.exit` behavior here.
 - `codeclone/mcp_server.py` — optional MCP launcher/server wiring, transport config, and MCP tool/resource
   registration; keep dependency loading lazy so base installs/CI do not require MCP runtime packages.
+- `tests/test_mcp_service.py`, `tests/test_mcp_server.py` — MCP contract and integration tests; run these when
+  touching any MCP surface.
 - `codeclone/html_report.py` — public HTML facade/re-export surface; preserve backward-compatible imports here; do not
   grow section/layout logic in this module.
 - `codeclone/_html_report/*` — actual HTML assembly, context shaping, tabs, sections, and overview/navigation behavior;

CHANGELOG.md

@@ -22,6 +22,9 @@ sync SPDX headers.
   split — all without changing canonical report schema until the later `2.2` report-threshold update below.
 - `cache.effective_freshness` marker and `get_production_triage` / `codeclone://latest/triage` for compact
   production-first overview.
+- `compare_runs` now reports `mixed` when new regressions and `health_delta` point in opposite directions.
+- `compare_runs` now reports `incomparable` and omits `health_delta` when run roots or effective analysis settings do not match.
+- MCP summary/triage/health surfaces now mark `health` as unavailable in `clones_only` runs instead of emitting zeroed placeholders.
 - Fix hotlist key resolution for `production_hotspots` and `test_fixture_hotspots`.
 - Bump cache schema to `2.3` (stale metric entries rebuilt, not reused).
 

README.md

@@ -170,6 +170,9 @@ codeclone-mcp --transport streamable-http --port 8000
 20 tools + 10 resources — deterministic, baseline-aware, and read-only. Never mutates source files, baselines, or repo
 state.
 Payloads are optimised for LLM context: compact summaries by default, full detail on demand.
+Run comparison stays compact too: `compare_runs` reports `mixed` when finding deltas and run-to-run health move in
+opposite directions, and `incomparable` when roots or effective analysis settings differ.
+When metrics are skipped (`clones_only`), MCP marks `health` as unavailable instead of returning fake zeros.
 
 Docs:
 [MCP usage guide](https://orenlab.github.io/codeclone/mcp/)

codeclone/_html_css.py

@@ -170,12 +170,14 @@
   background:var(--bg-surface);border:1px solid var(--border);border-radius:var(--radius-lg);
   overflow-x:auto;scrollbar-width:none;-webkit-overflow-scrolling:touch}
 .main-tabs::-webkit-scrollbar{display:none}
-.main-tab{position:relative;flex:1;text-align:center;padding:var(--sp-2) var(--sp-3);
-  background:none;border:none;cursor:pointer;font-size:.85rem;font-weight:500;
-  color:var(--text-muted);white-space:nowrap;border-radius:var(--radius-md);
-  transition:all var(--dur-fast) var(--ease)}
+.main-tab{position:relative;flex:1;display:inline-flex;align-items:center;justify-content:center;
+  gap:var(--sp-1);text-align:center;padding:var(--sp-2) var(--sp-3);background:none;
+  border:none;cursor:pointer;font-size:.85rem;font-weight:500;color:var(--text-muted);
+  white-space:nowrap;border-radius:var(--radius-md);transition:all var(--dur-fast) var(--ease)}
 .main-tab:hover{color:var(--text-primary);background:var(--bg-raised)}
 .main-tab[aria-selected="true"]{color:var(--accent-primary);background:var(--accent-muted)}
+.main-tab-icon{flex-shrink:0;opacity:.72}
+.main-tab-label{display:inline-flex;align-items:center}
 .tab-count{display:inline-flex;align-items:center;justify-content:center;min-width:18px;
   height:18px;padding:0 5px;font-size:.7rem;font-weight:700;border-radius:9px;
   background:var(--bg-overlay);color:var(--text-muted);margin-left:var(--sp-1)}
@@ -656,6 +658,23 @@
 .breakdown-bar-track{height:6px;border-radius:3px;background:var(--bg-raised);overflow:hidden}
 .breakdown-bar-fill{display:block;height:100%;border-radius:3px;
   background:var(--accent-primary);transition:width .6s var(--ease)}
+/* Directory hotspot entries */
+.dir-hotspot-list{display:flex;flex-direction:column;gap:0}
+.dir-hotspot-entry{padding:var(--sp-2) 0;border-bottom:1px solid color-mix(in srgb,var(--border) 50%,transparent)}
+.dir-hotspot-entry:last-child{border-bottom:none;padding-bottom:0}
+.dir-hotspot-entry:first-child{padding-top:0}
+.dir-hotspot-path{display:flex;align-items:center;gap:var(--sp-2);margin-bottom:4px;min-width:0}
+.dir-hotspot-path code{font-size:.78rem;font-weight:600;color:var(--text-primary);line-height:1.3}
+.dir-hotspot-bar-row{display:flex;align-items:center;gap:var(--sp-2);margin-bottom:3px}
+.dir-hotspot-bar-track{flex:1;height:4px;border-radius:2px;background:var(--bg-raised);
+  overflow:hidden;display:flex}
+.dir-hotspot-bar-prev{height:100%;background:var(--text-muted);opacity:.18}
+.dir-hotspot-bar-cur{height:100%;background:var(--accent-primary);opacity:.7}
+.dir-hotspot-pct{font-size:.7rem;font-weight:600;font-variant-numeric:tabular-nums;
+  color:var(--text-muted);min-width:3.2em;text-align:right}
+.dir-hotspot-meta{display:flex;flex-wrap:wrap;gap:6px;font-size:.68rem;color:var(--text-muted)}
+.dir-hotspot-meta span{font-variant-numeric:tabular-nums}
+.dir-hotspot-meta-sep{opacity:.3}
 /* Health radar chart */
 .health-radar{display:flex;justify-content:center;padding:var(--sp-3) 0}
 .health-radar svg{width:100%;max-width:520px;height:auto;overflow:visible}
@@ -781,10 +800,10 @@
 .suggestion-sev-inline{font-size:.72rem;font-weight:600;padding:1px var(--sp-1);
   border-radius:var(--radius-sm)}
 .suggestion-title{font-weight:600;font-size:.85rem;color:var(--text-primary);flex:1;min-width:0}
-.suggestion-meta{display:flex;align-items:center;gap:var(--sp-1);flex-shrink:0;flex-wrap:wrap}
-.suggestion-meta-badge{font-size:.68rem;font-family:var(--font-mono);font-weight:500;
-  padding:1px var(--sp-2);border-radius:var(--radius-sm);background:var(--bg-overlay);
-  color:var(--text-muted);white-space:nowrap}
+.suggestion-meta{display:flex;align-items:center;gap:var(--sp-2);flex-shrink:0;flex-wrap:wrap}
+.suggestion-meta-badge{font-size:.68rem;font-weight:600;padding:2px var(--sp-2);
+  border-radius:999px;background:var(--bg-overlay);color:var(--text-muted);
+  white-space:nowrap;line-height:1.2;font-variant-numeric:tabular-nums}
 .suggestion-effort--easy{color:var(--success);background:var(--success-muted, rgba(34,197,94,.1))}
 .suggestion-effort--moderate{color:var(--warning);background:var(--warning-muted)}
 .suggestion-effort--hard{color:var(--error);background:var(--error-muted)}
@@ -1092,6 +1111,7 @@
       linear-gradient(to left,rgba(0,0,0,.12),transparent) right center / 10px 100% no-repeat scroll,
       var(--bg-surface)}
   .main-tab{flex:none;padding:var(--sp-1) var(--sp-2);font-size:.78rem}
+  .main-tab-icon{width:13px;height:13px}
 }
 @media(max-width:480px){
   .overview-kpi-grid{grid-template-columns:1fr}

codeclone/_html_report/_assemble.py

@@ -21,7 +21,7 @@
 from ..structural_findings import normalize_structural_findings
 from ..templates import FONT_CSS_URL, REPORT_TEMPLATE
 from ._context import _meta_pick, build_context
-from ._icons import BRAND_LOGO, ICONS
+from ._icons import BRAND_LOGO, ICONS, section_icon_html
 from ._sections._clones import render_clones_panel
 from ._sections._coupling import render_quality_panel
 from ._sections._dead_code import render_dead_code_panel
@@ -119,6 +119,15 @@ def _tab_badge(count: int) -> str:
         return f'<span class="tab-count">{count}</span>'
 
     # -- Main tab navigation --
+    tab_icon_keys: dict[str, str] = {
+        "overview": "overview",
+        "clones": "clones",
+        "quality": "quality",
+        "dependencies": "dependencies",
+        "dead-code": "dead-code",
+        "suggestions": "suggestions",
+        "structural-findings": "structural-findings",
+    }
     tab_defs = [
         ("overview", "Overview", overview_html, ""),
         ("clones", "Clones", clones_html, _tab_badge(ctx.clone_groups_total)),
@@ -151,10 +160,15 @@ def _tab_badge(count: int) -> str:
         extra = tab_extra_attrs.get(tab_id, "")
         if extra:
             extra = " " + extra
+        tab_icon = section_icon_html(
+            tab_icon_keys.get(tab_id, ""),
+            class_name="main-tab-icon",
+            size=14,
+        )
         tab_buttons.append(
             f'<button class="main-tab" role="tab" data-tab="{tab_id}" '
             f'aria-selected="{selected}" aria-controls="panel-{tab_id}"{extra}>'
-            f"{tab_label}{badge}</button>"
+            f'{tab_icon}<span class="main-tab-label">{tab_label}</span>{badge}</button>'
         )
         active = " active" if idx == 0 else ""
         tab_panels.append(

codeclone/_html_report/_components.py

@@ -14,6 +14,7 @@
 from .. import _coerce
 from .._html_badges import _source_kind_badge_html
 from .._html_escape import _escape_attr, _escape_html
+from ._icons import section_icon_html
 
 _as_int = _coerce.as_int
 _as_mapping = _coerce.as_mapping
@@ -52,52 +53,24 @@ def overview_cluster_header(title: str, subtitle: str | None = None) -> str:
     )
 
 
-_ICON_ALERT = (
-    '<svg class="summary-icon summary-icon--risk" width="16" height="16" '
-    'viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" '
-    'stroke-linecap="round" stroke-linejoin="round">'
-    '<path d="M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86'
-    'a2 2 0 00-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/>'
-    '<line x1="12" y1="17" x2="12.01" y2="17"/></svg>'
-)
-
-_ICON_PIE = (
-    '<svg class="summary-icon summary-icon--info" width="16" height="16" '
-    'viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" '
-    'stroke-linecap="round" stroke-linejoin="round">'
-    '<path d="M21.21 15.89A10 10 0 118 2.83"/>'
-    '<path d="M22 12A10 10 0 0012 2v10z"/></svg>'
-)
-
-_ICON_RADAR = (
-    '<svg class="summary-icon summary-icon--info" width="16" height="16" '
-    'viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" '
-    'stroke-linecap="round" stroke-linejoin="round">'
-    '<circle cx="12" cy="12" r="10"/><circle cx="12" cy="12" r="6"/>'
-    '<circle cx="12" cy="12" r="2"/>'
-    '<line x1="12" y1="2" x2="12" y2="6"/>'
-    '<line x1="12" y1="18" x2="12" y2="22"/></svg>'
-)
-
-_ICON_BAR = (
-    '<svg class="summary-icon summary-icon--info" width="16" height="16" '
-    'viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" '
-    'stroke-linecap="round" stroke-linejoin="round">'
-    '<rect x="3" y="3" width="18" height="4" rx="1"/>'
-    '<rect x="3" y="10" width="13" height="4" rx="1"/>'
-    '<rect x="3" y="17" width="8" height="4" rx="1"/></svg>'
-)
-
-_SUMMARY_ICONS: dict[str, str] = {
-    "top risks": _ICON_ALERT,
-    "source breakdown": _ICON_PIE,
-    "health profile": _ICON_RADAR,
-    "issue breakdown": _ICON_BAR,
+_SUMMARY_ICON_KEYS: dict[str, tuple[str, str]] = {
+    "top risks": ("top-risks", "summary-icon summary-icon--risk"),
+    "issue breakdown": ("issue-breakdown", "summary-icon summary-icon--info"),
+    "source breakdown": ("source-breakdown", "summary-icon summary-icon--info"),
+    "all findings": ("all-findings", "summary-icon summary-icon--info"),
+    "clone groups": ("clone-groups", "summary-icon summary-icon--info"),
+    "low cohesion": ("low-cohesion", "summary-icon summary-icon--info"),
+    "health profile": ("health-profile", "summary-icon summary-icon--info"),
 }
 
 
 def overview_summary_item_html(*, label: str, body_html: str) -> str:
-    icon = _SUMMARY_ICONS.get(label.lower(), "")
+    icon_key, icon_class = _SUMMARY_ICON_KEYS.get(label.lower(), ("", ""))
+    icon = (
+        section_icon_html(icon_key, class_name=icon_class)
+        if icon_key and icon_class
+        else ""
+    )
     return (
         '<article class="overview-summary-item">'
         '<div class="overview-summary-label">'

codeclone/_html_report/_icons.py

@@ -17,6 +17,15 @@ def _svg(size: int, sw: str, body: str) -> str:
     )
 
 
+def _svg_with_class(size: int, sw: str, body: str, *, class_name: str = "") -> str:
+    class_attr = f' class="{class_name}"' if class_name else ""
+    return (
+        f'<svg{class_attr} width="{size}" height="{size}" viewBox="0 0 24 24" '
+        f'fill="none" stroke="currentColor" stroke-width="{sw}" '
+        f'stroke-linecap="round" stroke-linejoin="round">{body}</svg>'
+    )
+
+
 BRAND_LOGO = (
     '<svg class="brand-logo" width="32" height="32" viewBox="0 0 32 32" fill="none">'
     '<rect x="9" y="3" width="18" height="23" rx="3.5" '
@@ -82,3 +91,99 @@ def _svg(size: int, sw: str, body: str) -> str:
         '<polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/>',
     ),
 }
+
+_SECTION_ICON_BODIES: dict[str, tuple[str, str]] = {
+    "overview": (
+        "2",
+        '<rect x="3" y="4" width="8" height="7" rx="1.5"/>'
+        '<rect x="13" y="4" width="8" height="7" rx="1.5"/>'
+        '<rect x="3" y="13" width="8" height="7" rx="1.5"/>'
+        '<rect x="13" y="13" width="8" height="7" rx="1.5"/>',
+    ),
+    "clones": (
+        "2",
+        '<rect x="9" y="9" width="10" height="10" rx="2"/>'
+        '<rect x="5" y="5" width="10" height="10" rx="2"/>',
+    ),
+    "quality": (
+        "2",
+        '<path d="M4 19h16"/><rect x="5" y="11" width="3" height="6" rx="1"/>'
+        '<rect x="10.5" y="7" width="3" height="10" rx="1"/>'
+        '<rect x="16" y="4" width="3" height="13" rx="1"/>',
+    ),
+    "dependencies": (
+        "2",
+        '<circle cx="6" cy="6" r="2"/><circle cx="18" cy="6" r="2"/>'
+        '<circle cx="12" cy="18" r="2"/><path d="M8 7.5l2.5 6.5"/>'
+        '<path d="M16 7.5l-2.5 6.5"/>',
+    ),
+    "dead-code": (
+        "2",
+        '<path d="M14 3H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"/>'
+        '<path d="M14 3v6h6"/><path d="M9 14l6 6"/><path d="M15 14l-6 6"/>',
+    ),
+    "suggestions": (
+        "2",
+        '<path d="M12 3l1.8 4.7L18.5 9.5l-4.7 1.8L12 16l-1.8-4.7L5.5 9.5l4.7-1.8Z"/>'
+        '<path d="M19 16l.8 2.2L22 19l-2.2.8L19 22l-.8-2.2L16 19l2.2-.8Z"/>',
+    ),
+    "structural-findings": (
+        "2",
+        '<circle cx="6" cy="6" r="2"/><circle cx="18" cy="18" r="2"/>'
+        '<circle cx="18" cy="6" r="2"/><path d="M8 6h8"/>'
+        '<path d="M6 8v8a2 2 0 0 0 2 2h8"/>',
+    ),
+    "top-risks": (
+        "2",
+        '<path d="M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86'
+        'a2 2 0 00-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/>'
+        '<line x1="12" y1="17" x2="12.01" y2="17"/>',
+    ),
+    "issue-breakdown": (
+        "2",
+        '<rect x="3" y="3" width="18" height="4" rx="1"/>'
+        '<rect x="3" y="10" width="13" height="4" rx="1"/>'
+        '<rect x="3" y="17" width="8" height="4" rx="1"/>',
+    ),
+    "source-breakdown": (
+        "2",
+        '<path d="M21.21 15.89A10 10 0 118 2.83"/>'
+        '<path d="M22 12A10 10 0 0012 2v10z"/>',
+    ),
+    "health-profile": (
+        "2",
+        '<circle cx="12" cy="12" r="10"/><circle cx="12" cy="12" r="6"/>'
+        '<circle cx="12" cy="12" r="2"/><line x1="12" y1="2" x2="12" y2="6"/>'
+        '<line x1="12" y1="18" x2="12" y2="22"/>',
+    ),
+    "all-findings": (
+        "2",
+        '<circle cx="5" cy="6" r="1.5"/><circle cx="5" cy="12" r="1.5"/>'
+        '<circle cx="5" cy="18" r="1.5"/><path d="M10 6h10"/><path d="M10 12h10"/>'
+        '<path d="M10 18h10"/>',
+    ),
+    "clone-groups": (
+        "2",
+        '<rect x="9" y="9" width="10" height="10" rx="2"/>'
+        '<rect x="5" y="5" width="10" height="10" rx="2"/>',
+    ),
+    "low-cohesion": (
+        "2",
+        '<rect x="4" y="5" width="6" height="14" rx="1.5"/>'
+        '<rect x="14" y="5" width="6" height="14" rx="1.5"/>'
+        '<path d="M10 12h4"/>',
+    ),
+}
+
+
+def section_icon_html(
+    key: str,
+    *,
+    class_name: str = "",
+    size: int = 16,
+) -> str:
+    spec = _SECTION_ICON_BODIES.get(key.strip().lower())
+    if spec is None:
+        return ""
+    stroke_width, body = spec
+    return _svg_with_class(size, stroke_width, body, class_name=class_name)