feat(vscode,report): rename overloaded modules canonically and harden the VS Code surface

Author: orenlab

.dockerignore

@@ -18,3 +18,4 @@ docs
 codeclone.egg-info
 .pre-commit-config.yaml
 uv.lock
+extensions

.github/actions/codeclone/README.md

@@ -149,7 +149,7 @@ Explicit prerelease:
 
 ```yaml
 with:
-  package-version: "2.0.0b3"
+  package-version: "2.0.0b4"
 ```
 
 Local/self-repo validation:

.gitignore

@@ -38,3 +38,4 @@ site/
 /docs/SPEC-2.0.0.md
 /.uv-cache/
 /package-lock.json
+extensions/vscode-codeclone/node_modules

AGENTS.md

@@ -574,7 +574,7 @@ Use modern syntax when it stays compatible with 3.10+:
 Prefer these rules:
 
 - **Domain / contracts / enums** live near the domain owner (baseline statuses in baseline domain).
-- If a module becomes a “god module”, split by:
+- If a module becomes an “overloaded module”, split by:
     - model (types)
     - io/serialization
     - rules/validation

CHANGELOG.md

@@ -2,46 +2,35 @@
 
 ## [2.0.0b4]
 
-2.0.0b4 deepens the platform model introduced in b3: MCP becomes more self-guiding, report-only analysis expands with
-module-level hotspot ranking, findings and suggestions are separated more cleanly by role, Health Score documentation
-now formalizes phased score-model evolution, and CodeClone gains its first native IDE surface in preview.
-
 ### MCP server
 
-- Add bounded MCP `help(topic=...)` as a compact uncertainty-recovery and semantic-routing tool for workflow, baseline,
-  suppressions, latest-run semantics, review state, and changed-scope routing.
+- Add `help(topic=...)` tool for workflow guidance, baseline semantics, and review-state routing.
+- Optimize MCP payloads: short finding IDs (sha256-based for block clones), compact `derived` section projection,
+  bounded `metrics_detail` with pagination.
 
 ### Report contract
 
-- Bump canonical report schema to `2.3` and add `metrics.families.god_modules` as a project-relative, report-only
-  module-hotspot layer.
-- Surface `God Modules` consistently across canonical JSON, text/markdown, HTML Overview + Quality projections, and
-  bounded MCP `metrics_detail` access without changing findings, health, gates, baseline semantics, or SARIF.
-- Tighten the findings/suggestions role split: low-signal local structural `info` hints remain canonical findings,
-  while separate suggestion cards are reserved for action-surplus cases and structural findings can render compact
-  inline suggested action in HTML.
+- Bump canonical report schema to `2.3`.
+- Add `metrics.overloaded_modules` — report-only module-hotspot ranking by size, complexity, and coupling pressure.
+- Surface Overloaded Modules across JSON, text/markdown, HTML, and MCP without affecting findings, health, or gates.
+- Normalize the canonical family name and MCP/report output to `overloaded_modules`; `god_modules` remains accepted as a read-only MCP input alias during transition.
 
 ### CLI and HTML
 
-- Align CLI and HTML scope summaries with canonical report-wide inventory totals.
-- Polish `God Modules` presentation so report-only module-hotspot summaries read consistently across surfaces.
+- Align CLI and HTML scope summaries with canonical inventory totals.
+- Redesign Overview tab: Executive Summary becomes 2-column (Issue Breakdown + Source Breakdown) with scan scope in
+  the section subtitle; Overloaded Modules section replaces the earlier stretched module-hotspot layout.
 
 ### Documentation
 
-- Add a dedicated Health Score chapter documenting current scoring inputs, report-only / non-scoring layers, and the
-  phased policy for future health-model expansion.
-- Explicitly document that future releases may lower a repository score because the scoring model becomes broader or
-  stricter, not only because the code became worse.
+- Add Health Score chapter: scoring inputs, report-only layers, phased expansion policy.
+- Document that future releases may lower scores due to broader scoring model, not only worse code.
 
-### IDE integration
+### IDE integration (preview)
 
-- Add a preview VS Code extension as the first native IDE surface for `codeclone-mcp`, bringing baseline-aware,
-  triage-first structural review and guided source-first drill-down into the editor.
-- Establish the initial extension interaction model, including explicit setup/session semantics, review-loop navigation,
-  hotspot focus persistence, lightweight Explorer decorations, safe HTML-report bridging, and accessibility/status
-  polish.
-- Add extension-side regression coverage with Node unit tests, local extension-host smoke, and validated preview `.vsix`
-  packaging.
+- Add VS Code extension (`codeclone-mcp` client) with baseline-aware triage, source drill-down, Explorer decorations,
+  and HTML-report bridging.
+- Add Node unit tests, extension-host smoke tests, and `.vsix` packaging.
 
 ## [2.0.0b3] - 20260401
 

README.md

@@ -39,15 +39,13 @@ Live sample report:
 - **Clone detection** — function (CFG fingerprint), block (statement windows), and segment (report-only) clones
 - **Structural findings** — duplicated branch families, clone guard/exit divergence and clone-cohort drift (report-only)
 - **Quality metrics** — cyclomatic complexity, coupling (`CBO`), cohesion (`LCOM4`), dependency cycles, dead code,
-  health
-  score, and report-only `God Modules` profiling
+  health score, and report-only `Overloaded Modules` profiling
 - **Baseline governance** — separates accepted **legacy** debt from **new regressions** and lets CI fail **only** on
   what changed
 - **Reports** — interactive HTML, deterministic JSON/TXT plus Markdown and SARIF projections from one canonical report
-- **MCP server** — optional read-only MCP surface for AI agents and IDEs, designed as a budget-aware guided control
+- **MCP server** — optional read-only surface for AI agents and IDEs, designed as a budget-aware guided control
   surface for agentic development
-- **VS Code extension** — preview native client for CodeClone MCP with baseline-aware, triage-first structural
-  review inside the editor
+- **VS Code extension** — preview native client for CodeClone MCP with triage-first structural review
 - **CI-first** — deterministic output, stable ordering, exit code contract, pre-commit support
 - **Fast** — incremental caching, parallel processing, warm-run optimization, and reproducible benchmark coverage
 
@@ -170,18 +168,8 @@ codeclone-mcp --transport stdio
 codeclone-mcp --transport streamable-http --port 8000
 ```
 
-21 tools + 10 resources — deterministic, baseline-aware, and read-only.
-Never mutates source files, baselines, or repo state.
-
-Payloads are optimized for LLM context: compact summaries by default, full detail on demand.
-The cheapest useful path is also the most obvious path: first-pass triage stays compact, and deeper detail is explicit.
-
-Recommended agent flow:
-`analyze_repository` or `analyze_changed_paths` → `get_run_summary` or `get_production_triage` →
-`list_hotspots` or `check_*` → `get_finding` → `get_remediation`
-
-If workflow or contract meaning is unclear, `help(topic=...)` returns a compact
-semantic guide with the safest next step and canonical doc links.
+21 tools + 10 resources. Read-only — never mutates source, baselines, or repo state.
+Payloads are optimized for LLM context: compact summaries by default, full detail on drill-down.
 
 Docs:
 [MCP usage guide](https://orenlab.github.io/codeclone/mcp/)
@@ -190,21 +178,10 @@ Docs:
 
 ### VS Code Extension
 
-The repository also ships a preview VS Code extension in
+A preview VS Code extension ships in
 [`extensions/vscode-codeclone/`](https://github.com/orenlab/codeclone/tree/main/extensions/vscode-codeclone).
-
-It is:
-
-- native VS Code first
-- baseline-aware
-- triage-first
-- read-only with respect to repository state
-- powered by the same `codeclone-mcp` contract surface
-- limited in Restricted Mode until workspace trust is granted
-
-It focuses on source-first structural review inside the editor: overview,
-hotspots, review loop, changed-files pass, and explicit drill-down into finding,
-remediation, or local HTML report when needed.
+It connects to `codeclone-mcp` and provides triage-first structural review inside the editor:
+overview, hotspots, review loop, and drill-down into findings or the HTML report.
 
 Docs:
 [VS Code extension guide](https://orenlab.github.io/codeclone/vscode-extension/)
@@ -300,11 +277,11 @@ class Middleware:  # codeclone: ignore[dead-code]
 Dynamic/runtime false positives are resolved via explicit inline suppressions, not via broad heuristics.
 
 <details>
-<summary>Canonical JSON report shape (v2.2)</summary>
+<summary>Canonical JSON report shape (v2.3)</summary>
 
 ```json
 {
-  "report_schema_version": "2.2",
+  "report_schema_version": "2.3",
   "meta": {
     "codeclone_version": "2.0.0b4",
     "project_name": "...",

codeclone/_cli_summary.py

@@ -26,10 +26,10 @@ class MetricsSnapshot:
     health_total: int
     health_grade: str
     suppressed_dead_code_count: int = 0
-    god_modules_candidates: int = 0
-    god_modules_total: int = 0
-    god_modules_population_status: str = ""
-    god_modules_top_score: float = 0.0
+    overloaded_modules_candidates: int = 0
+    overloaded_modules_total: int = 0
+    overloaded_modules_population_status: str = ""
+    overloaded_modules_top_score: float = 0.0
 
 
 @dataclass(frozen=True, slots=True)
@@ -136,7 +136,7 @@ def _print_metrics(
                 dead=metrics.dead_code_count,
                 health=metrics.health_total,
                 grade=metrics.health_grade,
-                god_modules=metrics.god_modules_candidates,
+                overloaded_modules=metrics.overloaded_modules_candidates,
             )
         )
     else:
@@ -166,11 +166,11 @@ def _print_metrics(
             )
         )
         console.print(
-            ui.fmt_metrics_god_modules(
-                candidates=metrics.god_modules_candidates,
-                total=metrics.god_modules_total,
-                population_status=metrics.god_modules_population_status,
-                top_score=metrics.god_modules_top_score,
+            ui.fmt_metrics_overloaded_modules(
+                candidates=metrics.overloaded_modules_candidates,
+                total=metrics.overloaded_modules_total,
+                population_status=metrics.overloaded_modules_population_status,
+                top_score=metrics.overloaded_modules_top_score,
             )
         )
 

codeclone/_html_css.py

@@ -683,23 +683,23 @@
 .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}
-.god-module-list{display:flex;flex-direction:column;gap:0}
-.god-module-entry{padding:var(--sp-2) 0;border-bottom:1px solid color-mix(in srgb,var(--border) 50%,transparent)}
-.god-module-entry:last-child{border-bottom:none;padding-bottom:0}
-.god-module-entry:first-child{padding-top:0}
-.god-module-head{display:flex;align-items:flex-start;justify-content:space-between;gap:var(--sp-2);margin-bottom:4px}
-.god-module-title{display:flex;align-items:center;flex-wrap:wrap;gap:var(--sp-2);min-width:0}
-.god-module-title code{font-size:.78rem;font-weight:600;color:var(--text-primary);line-height:1.35}
-.god-module-score{flex-shrink:0;font-size:.72rem;font-weight:700;font-variant-numeric:tabular-nums;
+.overloaded-module-list{display:flex;flex-direction:column;gap:0}
+.overloaded-module-entry{padding:var(--sp-2) 0;border-bottom:1px solid color-mix(in srgb,var(--border) 50%,transparent)}
+.overloaded-module-entry:last-child{border-bottom:none;padding-bottom:0}
+.overloaded-module-entry:first-child{padding-top:0}
+.overloaded-module-head{display:flex;align-items:flex-start;justify-content:space-between;gap:var(--sp-2);margin-bottom:4px}
+.overloaded-module-title{display:flex;align-items:center;flex-wrap:wrap;gap:var(--sp-2);min-width:0}
+.overloaded-module-title code{font-size:.78rem;font-weight:600;color:var(--text-primary);line-height:1.35}
+.overloaded-module-score{flex-shrink:0;font-size:.72rem;font-weight:700;font-variant-numeric:tabular-nums;
   color:var(--accent-primary);background:var(--accent-muted);border-radius:999px;padding:2px 8px}
-.god-module-metrics{display:flex;flex-wrap:wrap;gap:6px;font-size:.68rem;color:var(--text-muted)}
-.god-module-metrics span{font-variant-numeric:tabular-nums}
-.god-module-reasons,.god-module-signal-list{display:flex;flex-wrap:wrap;gap:var(--sp-1);margin-top:var(--sp-2)}
-.god-module-reason-chip,.god-module-signal-pill{display:inline-flex;align-items:center;gap:5px;
+.overloaded-module-metrics{display:flex;flex-wrap:wrap;gap:6px;font-size:.68rem;color:var(--text-muted)}
+.overloaded-module-metrics span{font-variant-numeric:tabular-nums}
+.overloaded-module-reasons,.overloaded-module-signal-list{display:flex;flex-wrap:wrap;gap:var(--sp-1);margin-top:var(--sp-2)}
+.overloaded-module-reason-chip,.overloaded-module-signal-pill{display:inline-flex;align-items:center;gap:5px;
   font-size:.68rem;font-weight:500;color:var(--text-secondary);background:var(--bg-raised);
   border:1px solid color-mix(in srgb,var(--border) 60%,transparent);border-radius:999px;
   padding:2px 8px}
-.god-module-signal-count{font-variant-numeric:tabular-nums;color:var(--text-muted)}
+.overloaded-module-signal-count{font-variant-numeric:tabular-nums;color:var(--text-muted)}
 /* 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}

codeclone/_html_report/_assemble.py

@@ -111,7 +111,9 @@ def build_html_report(
         _as_int(_as_mapping(ctx.complexity_map.get("summary")).get("high_risk"))
         + _as_int(_as_mapping(ctx.coupling_map.get("summary")).get("high_risk"))
         + _as_int(_as_mapping(ctx.cohesion_map.get("summary")).get("low_cohesion"))
-        + _as_int(_as_mapping(ctx.god_modules_map.get("summary")).get("candidates"))
+        + _as_int(
+            _as_mapping(ctx.overloaded_modules_map.get("summary")).get("candidates")
+        )
     )
 
     def _tab_badge(count: int) -> str:

codeclone/_html_report/_components.py

@@ -51,15 +51,14 @@ def overview_cluster_header(title: str, subtitle: str | None = None) -> str:
 
 
 _SUMMARY_ICON_KEYS: dict[str, tuple[str, str]] = {
-    "scan scope": ("overview", "summary-icon summary-icon--info"),
     "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"),
     "top candidates": ("quality", "summary-icon summary-icon--info"),
-    "candidate profile": ("quality", "summary-icon summary-icon--info"),
+    "more candidates": ("quality", "summary-icon summary-icon--info"),
     "health profile": ("health-profile", "summary-icon summary-icon--info"),
 }