tech-debt-visualizer 0.2.0 → 0.2.2

package/README.md

@@ -68,6 +68,8 @@ So: **static metrics + git → score & tier → optional LLM explanations and co
 | **Global (after publish)** | `npm install -g tech-debt-visualizer` then `tech-debt analyze [path]` |
 | **No install (after publish)** | `npx tech-debt-visualizer analyze [path]` |
 
+Use **`tech-debt-visualizer`** in the command (not `tech-debt`); `npx tech-debt` runs a different npm package. From this repo you can also run `npm run analyze` or `node dist/cli.js analyze .`.
+
 Requires **Node 18+**.
 
 ---

package/dist/cli.js

@@ -30,9 +30,10 @@ program
     .option("-f, --format <type>", "Output format: cli | html | json | markdown", "cli")
     .option("--no-llm", "Skip LLM-powered insights")
     .option("--llm", "Enable LLM (default). Use with --llm-key and/or --llm-model")
-    .option("--llm-key <key>", "API key for LLM (overrides GEMINI_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY)")
-    .option("--llm-model <model>", "Model name (e.g. gemini-1.5-flash, gpt-4o-mini)")
-    .option("--llm-max-tokens <n>", "Max tokens for LLM responses (default: 2048 for overall, 1024 per-file)", (v) => parseInt(v, 10))
+    .option("--llm-key <key>", "API key (overrides env: GEMINI_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY)")
+    .option("--llm-endpoint <url>", "OpenAI-compatible API base URL (e.g. https://api.openai.com/v1 or proxy)")
+    .option("--llm-model <model>", "Model name (e.g. gpt-4o-mini, gemini-2.5-flash)")
+    .option("--llm-max-tokens <n>", "Max tokens per response", (v) => parseInt(v, 10))
     .option("--ci", "CI mode: minimal output, exit with non-zero if debt score is high")
     .action(async (path, opts) => {
     const repoPath = join(process.cwd(), path);
@@ -41,6 +42,7 @@ program
     const outputPath = opts.output ?? (format === "html" ? "tech-debt-report.html" : undefined);
     const llmConfigOverrides = {
         apiKey: opts.llmKey,
+        baseURL: opts.llmEndpoint,
         model: opts.llmModel,
         ...(opts.llmMaxTokens != null && opts.llmMaxTokens > 0 ? { maxTokens: opts.llmMaxTokens } : {}),
     };
@@ -82,9 +84,9 @@ program
             if (!llmConfig) {
                 progress.update(totalSteps, { task: "Skipping LLM (no key)" });
                 progress.stop();
-                process.stderr.write(chalk.yellow("  No LLM API key found. Set GEMINI_API_KEY or OPENAI_API_KEY (or use --llm-key <key>).\n" +
-                    "  Example: export GEMINI_API_KEY=your_key   or   --llm-key your_key\n" +
-                    "  Or add GEMINI_API_KEY=your_key to a .env file in the current directory.\n" +
+                process.stderr.write(chalk.yellow("  No LLM API key found. Use --llm-key <key> or set one of:\n" +
+                    "  GEMINI_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY (or .env).\n" +
+                    "  For a custom endpoint: --llm-endpoint <url> --llm-key <key>\n" +
                     "  Skipping AI insights for this run.\n\n"));
             }
             else {

package/dist/llm.d.ts

@@ -18,7 +18,7 @@ export interface LLMConfig {
     maxTokens?: number;
 }
 export type LLMProvider = "openai" | "openrouter" | "gemini";
-/** Resolve provider and auth from config + env. When --llm-key is used, provider is inferred from key format so a Gemini key is not sent to OpenRouter. */
+/** Resolve provider and auth from config + env. Explicit baseURL = OpenAI-compatible; else key format or env picks provider. */
 export declare function resolveLLMConfig(config?: LLMConfig): {
     provider: LLMProvider;
     apiKey: string;

package/dist/llm.js

@@ -68,13 +68,20 @@ function parseFileAssessmentResponse(raw) {
         code: code || undefined,
     };
 }
-/** Resolve provider and auth from config + env. When --llm-key is used, provider is inferred from key format so a Gemini key is not sent to OpenRouter. */
+/** Resolve provider and auth from config + env. Explicit baseURL = OpenAI-compatible; else key format or env picks provider. */
 export function resolveLLMConfig(config = {}) {
-    const cliKey = config.apiKey;
-    const openRouterKey = cliKey ?? process.env.OPENROUTER_API_KEY;
-    const geminiKey = cliKey ?? process.env.GEMINI_API_KEY ?? process.env.GOOGLE_GENAI_API_KEY;
-    const openaiKey = cliKey ?? process.env.OPENAI_API_KEY ?? process.env.ANTHROPIC_API_KEY;
-    // When a single key is passed (e.g. --llm-key), pick provider by key format so we don't send a Gemini key to OpenRouter (401 "No cookie auth").
+    const trim = (s) => (typeof s === "string" ? s.trim() : undefined) || undefined;
+    const explicitBase = (config.baseURL ?? process.env.OPENAI_BASE_URL)?.replace(/\/$/, "");
+    const cliKey = trim(config.apiKey);
+    const openaiKey = trim(cliKey ?? process.env.OPENAI_API_KEY ?? process.env.ANTHROPIC_API_KEY);
+    if (explicitBase && openaiKey) {
+        return {
+            provider: "openai",
+            apiKey: openaiKey,
+            baseURL: explicitBase,
+            model: config.model ?? process.env.OPENAI_MODEL ?? OPENAI_DEFAULT_MODEL,
+        };
+    }
     if (cliKey) {
         if (cliKey.startsWith("AIza")) {
             return {
@@ -88,11 +95,12 @@ export function resolveLLMConfig(config = {}) {
             return {
                 provider: "openai",
                 apiKey: cliKey,
-                baseURL: config.baseURL ?? process.env.OPENAI_BASE_URL ?? "",
+                baseURL: (config.baseURL ?? process.env.OPENAI_BASE_URL ?? "").replace(/\/$/, ""),
                 model: config.model ?? process.env.OPENAI_MODEL ?? OPENAI_DEFAULT_MODEL,
             };
         }
     }
+    const openRouterKey = trim(cliKey ?? process.env.OPENROUTER_API_KEY);
     if (openRouterKey) {
         return {
             provider: "openrouter",
@@ -101,6 +109,7 @@ export function resolveLLMConfig(config = {}) {
             model: config.model ?? process.env.OPENROUTER_MODEL ?? OPENROUTER_DEFAULT_MODEL,
         };
     }
+    const geminiKey = trim(cliKey ?? process.env.GEMINI_API_KEY ?? process.env.GOOGLE_GENAI_API_KEY);
     if (geminiKey) {
         return {
             provider: "gemini",
@@ -113,7 +122,7 @@ export function resolveLLMConfig(config = {}) {
         return {
             provider: "openai",
             apiKey: openaiKey,
-            baseURL: config.baseURL ?? process.env.OPENAI_BASE_URL ?? "",
+            baseURL: (config.baseURL ?? process.env.OPENAI_BASE_URL ?? "").replace(/\/$/, ""),
             model: config.model ?? process.env.OPENAI_MODEL ?? OPENAI_DEFAULT_MODEL,
         };
     }

package/dist/reports/assets/report.css

@@ -1,141 +1,297 @@
-/* Technical Debt Report - theme and layout */
+/* Technical Debt Report — Grafana-style dashboard */
 :root {
-  --bg: #fff;
-  --surface: #fff;
-  --border: #ccc;
-  --text: #222;
-  --text-muted: #666;
-  --link: #0568c2;
+  --bg: #0b0c0e;
+  --bg-elevated: #111214;
+  --surface: #181b1f;
+  --surface-hover: #1e2127;
+  --border: #2c3239;
+  --border-subtle: #252a30;
+  --text: #e8e9ea;
+  --text-muted: #8b9199;
+  --link: #5794f2;
+  --radius: 4px;
+  --shadow: 0 1px 2px rgba(0, 0, 0, 0.2);
 }
 
-[data-theme="dark"] {
-  --bg: #1a1a1a;
-  --surface: #252525;
-  --border: #404040;
-  --text: #e0e0e0;
-  --text-muted: #999;
-  --link: #6eb3f7;
+[data-theme="light"] {
+  --bg: #f4f5f5;
+  --bg-elevated: #fff;
+  --surface: #fff;
+  --surface-hover: #f9fafb;
+  --border: #d8d9da;
+  --border-subtle: #e8e9ea;
+  --text: #1e2022;
+  --text-muted: #6b7077;
+  --link: #3274d9;
+  --shadow: 0 1px 2px rgba(0, 0, 0, 0.06);
 }
 
 * { box-sizing: border-box; }
 
 body {
   margin: 0;
-  font-family: system-ui, sans-serif;
+  font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
   background: var(--bg);
   color: var(--text);
   min-height: 100vh;
-  font-size: 14px;
+  font-size: 13px;
   line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
 }
 
-.container {
-  max-width: 900px;
-  margin: 0 auto;
-  padding: 1.5rem 1.25rem;
+body.dashboard-page {
+  padding-bottom: 2rem;
 }
 
-/* Banner */
-.no-llm-banner {
-  width: 100%;
-  background: var(--surface);
+/* ——— Dashboard header (Grafana-style top bar) ——— */
+.dashboard-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  flex-wrap: wrap;
+  gap: 0.75rem;
+  padding: 0.75rem 1.5rem;
+  background: var(--bg-elevated);
   border-bottom: 1px solid var(--border);
-  padding: 0.5rem 1rem;
-  text-align: center;
+  position: sticky;
+  top: 0;
+  z-index: 10;
 }
 
-.no-llm-banner .no-llm-cta {
-  font-size: 14px;
-  font-weight: normal;
+.dashboard-header-left {
+  display: flex;
+  align-items: baseline;
+  gap: 0.75rem;
+  min-width: 0;
+}
+
+.dashboard-title {
+  margin: 0;
+  font-size: 1.125rem;
+  font-weight: 600;
+  letter-spacing: -0.01em;
   color: var(--text);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.dashboard-meta {
+  font-size: 12px;
+  color: var(--text-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.dashboard-header-right {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  flex-shrink: 0;
+}
+
+.dashboard-score {
+  display: inline-flex;
+  align-items: baseline;
+  gap: 0.2rem;
+  padding: 0.35rem 0.65rem;
+  border-radius: var(--radius);
+  font-weight: 600;
+}
+
+.dashboard-score-value {
+  font-size: 1.25rem;
+  line-height: 1;
+}
+
+.dashboard-score-of {
+  font-size: 0.85rem;
+  font-weight: 500;
+  color: var(--text-muted);
+}
+
+.dashboard-score-label {
+  font-size: 11px;
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  margin-left: 0.35rem;
+  opacity: 0.95;
+}
+
+.dashboard-score.tier-1 { background: rgba(204, 0, 0, 0.2); color: #f66; }
+.dashboard-score.tier-2 { background: rgba(232, 93, 0, 0.2); color: #f90; }
+.dashboard-score.tier-3 { background: rgba(184, 134, 11, 0.2); color: #db9; }
+.dashboard-score.tier-4 { background: rgba(0, 102, 153, 0.2); color: #6cf; }
+.dashboard-score.tier-5 { background: rgba(10, 107, 10, 0.2); color: #6c6; }
+
+.dashboard-date {
+  font-size: 12px;
+  color: var(--text-muted);
+}
+
+/* ——— Main content & grid ——— */
+.dashboard-main {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 1.25rem 1.5rem;
+}
+
+.dashboard-grid {
+  display: grid;
+  gap: 1rem;
+  margin-bottom: 1rem;
+}
+
+.dashboard-grid-stats {
+  grid-template-columns: repeat(4, 1fr);
+}
+
+.dashboard-grid-half {
+  grid-template-columns: repeat(2, 1fr);
+}
+
+@media (max-width: 900px) {
+  .dashboard-grid-stats { grid-template-columns: repeat(2, 1fr); }
+  .dashboard-grid-half { grid-template-columns: 1fr; }
+}
+
+@media (max-width: 560px) {
+  .dashboard-header { padding: 0.6rem 1rem; }
+  .dashboard-main { padding: 1rem; }
+  .dashboard-grid-stats { grid-template-columns: 1fr; }
+}
+
+/* ——— Panels (Grafana-style) ——— */
+.panel {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  box-shadow: var(--shadow);
+  overflow: hidden;
+}
+
+.panel-header {
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--border-subtle);
+  background: rgba(0, 0, 0, 0.03);
+}
+
+[data-theme="light"] .panel-header {
+  background: rgba(0, 0, 0, 0.02);
+}
+
+.panel-title {
   margin: 0;
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--text);
+  letter-spacing: -0.01em;
 }
 
-/* Hero / score */
-.hero-caption {
+.panel-desc {
+  margin: 0.25rem 0 0;
   font-size: 12px;
   color: var(--text-muted);
-  margin: 0 0 0.5rem;
-  text-align: center;
+  line-height: 1.4;
 }
 
-.hero {
+.panel-body {
+  padding: 1rem;
+}
+
+.panel-body-center {
   text-align: center;
-  margin-bottom: 1.5rem;
 }
 
-.score-badge {
+/* Stat panels (KPI row) */
+.stat-panel .panel-body {
+  padding: 1rem 1.25rem;
+}
+
+.stat-value {
+  font-size: 1.75rem;
+  font-weight: 700;
+  line-height: 1.2;
+  color: var(--text);
+  letter-spacing: -0.02em;
+}
+
+.stat-label {
+  font-size: 11px;
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--text-muted);
+  margin-top: 0.25rem;
+}
+
+.stat-panel-warn .stat-value { color: #f44; }
+
+/* Score panel (cleanliness gauge) */
+.panel-score .panel-body-center {
+  padding: 1.25rem 1rem;
+}
+
+.panel-score .score-badge {
   display: inline-block;
   margin-bottom: 0.75rem;
   line-height: 0;
 }
 
-.score-badge-svg {
+.panel-score .score-badge-svg {
   display: block;
-  width: 160px;
+  width: 120px;
   height: auto;
-  max-width: min(160px, 40vw);
 }
 
-.score-badge-svg .score-badge-num {
-  font-family: system-ui, -apple-system, sans-serif;
-  font-size: 56px;
+.panel-score .score-badge-svg .score-badge-num {
+  font-size: 42px;
   font-weight: 800;
   letter-spacing: -0.02em;
 }
 
-.score-badge-svg .score-badge-of {
-  font-family: system-ui, -apple-system, sans-serif;
-  font-size: 14px;
+.panel-score .score-badge-svg .score-badge-of {
+  font-size: 12px;
   font-weight: 700;
   letter-spacing: 0.08em;
   text-transform: uppercase;
   opacity: 0.95;
 }
 
-.hero .score-label { font-size: 1.1rem; font-weight: bold; color: var(--text); margin: 0 0 0.2rem; }
-.hero .score-desc { font-size: 13px; color: var(--text-muted); margin: 0 0 0.35rem; max-width: 360px; margin-left: auto; margin-right: auto; }
-.hero .report-meta { font-size: 12px; color: var(--text-muted); }
-
-.hero.tier-1 { --tier-bg: #c00; --tier-num: #fff; }
-.hero.tier-2 { --tier-bg: #e85d00; --tier-num: #fff; }
-.hero.tier-3 { --tier-bg: #b8860b; --tier-num: #fff; }
-.hero.tier-4 { --tier-bg: #069; --tier-num: #fff; }
-.hero.tier-5 { --tier-bg: #0a6b0a; --tier-num: #fff; }
-
-/* Summary cards */
-.summary-cards {
-  display: grid;
-  grid-template-columns: repeat(4, 1fr);
-  gap: 0.75rem;
-  margin-bottom: 1.5rem;
+.panel-score .score-desc {
+  font-size: 13px;
+  color: var(--text-muted);
+  margin: 0;
+  max-width: 320px;
+  margin-left: auto;
+  margin-right: auto;
+  line-height: 1.45;
 }
 
-@media (max-width: 640px) {
-  .summary-cards { grid-template-columns: repeat(2, 1fr); }
+/* LLM panel accent */
+.panel-llm {
+  border-left: 3px solid var(--link);
 }
 
-.card {
+/* ——— Banner ——— */
+.no-llm-banner {
+  width: 100%;
   background: var(--surface);
-  border: 1px solid var(--border);
-  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--border);
+  padding: 0.5rem 1rem;
+  text-align: center;
 }
 
-.card .value { font-size: 1.35rem; font-weight: bold; color: var(--text); }
-.card .label { font-size: 12px; color: var(--text-muted); margin-top: 0.15rem; }
-
-/* Sections */
-.section {
-  background: var(--surface);
-  border: 1px solid var(--border);
-  padding: 1rem 1.25rem;
-  margin-bottom: 1rem;
+.no-llm-banner .no-llm-cta {
+  font-size: 13px;
+  font-weight: normal;
+  color: var(--text-muted);
+  margin: 0;
 }
 
-.section h2 { font-size: 1rem; margin: 0 0 0.75rem; color: var(--text); font-weight: bold; }
-.section-desc { font-size: 13px; color: var(--text-muted); margin: -0.35rem 0 0.75rem; line-height: 1.4; }
-
-/* Treemap */
+/* ——— Treemap ——— */
 #treemap {
   display: flex;
   flex-wrap: wrap;
@@ -154,10 +310,14 @@ body {
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
-  border: 1px solid rgba(0,0,0,0.1);
+  border: 1px solid rgba(0, 0, 0, 0.15);
+  border-radius: 2px;
 }
 
-.treemap-cell:hover { outline: 2px solid var(--text); outline-offset: 1px; }
+.treemap-cell:hover {
+  outline: 2px solid var(--link);
+  outline-offset: 1px;
+}
 
 .treemap-cell[data-severity="critical"] { background: #c00; color: #fff; border-color: #900; }
 .treemap-cell[data-severity="high"]    { background: #e85d00; color: #fff; border-color: #b84a00; }
@@ -165,37 +325,77 @@ body {
 .treemap-cell[data-severity="low"]     { background: #0a6b0a; color: #fff; border-color: #064906; }
 .treemap-cell[data-severity="none"]    { background: var(--border); color: var(--text-muted); border-color: var(--border); }
 
-/* Legend */
-.legend { display: flex; flex-wrap: wrap; gap: 0.75rem; align-items: center; margin-bottom: 0.75rem; font-size: 12px; color: var(--text-muted); }
-.legend span { display: inline-flex; align-items: center; gap: 0.25rem; }
-.legend .swatch { width: 10px; height: 10px; }
+.legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1rem;
+  align-items: center;
+  margin-bottom: 0.75rem;
+  font-size: 12px;
+  color: var(--text-muted);
+}
+
+.legend span { display: inline-flex; align-items: center; gap: 0.35rem; }
+.legend .swatch { width: 10px; height: 10px; border-radius: 2px; }
 .legend .swatch-crit { background: #c00; }
 .legend .swatch-high { background: #e85d00; }
 .legend .swatch-med { background: #b8860b; }
 .legend .swatch-low { background: #0a6b0a; }
 .legend .swatch-none { background: var(--border); }
 
-/* Debt list */
-.debt-list { list-style: none; padding: 0; margin: 0; }
+/* ——— Priority lists ——— */
+.priority-list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  font-size: 12px;
+}
+
+.priority-list li {
+  padding: 0.4rem 0;
+  border-bottom: 1px solid var(--border-subtle);
+  color: var(--text);
+  font-family: ui-monospace, monospace;
+}
+
+.priority-list li:last-child { border-bottom: none; }
+
+/* ——— Debt list ——— */
+.debt-list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
 
 .debt-list li {
-  border-bottom: 1px solid var(--border);
-  padding: 0.6rem 0;
+  border-bottom: 1px solid var(--border-subtle);
+  padding: 0.65rem 0;
   cursor: pointer;
+  transition: background 0.12s ease;
 }
 
 .debt-list li:last-child { border-bottom: none; }
-.debt-list li:hover { background: var(--bg); }
-.debt-list .title { font-weight: bold; margin-bottom: 0.2rem; }
-.debt-list .meta { font-size: 12px; color: var(--text-muted); display: block; margin-top: 0.2rem; }
+.debt-list li:hover { background: var(--surface-hover); }
+
+.debt-list .title { font-weight: 600; margin-bottom: 0.2rem; }
+.debt-list .meta { font-size: 12px; color: var(--text-muted); display: block; margin-top: 0.25rem; font-family: ui-monospace, monospace; }
 .debt-list .insight { font-size: 13px; color: var(--text-muted); margin-top: 0.25rem; line-height: 1.4; white-space: pre-wrap; word-break: break-word; }
 .debt-list-ratings { display: flex; align-items: center; gap: 1rem; margin: 0.25rem 0; flex-wrap: wrap; }
 .debt-list-rating { display: inline-flex; align-items: center; gap: 0.35rem; }
 .debt-list-rating-label { font-size: 10px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.03em; color: var(--text-muted); }
-.debt-list-llm-none { color: var(--text-muted); font-size: 13px; }
+.debt-list-llm-none { color: var(--text-muted); font-size: 12px; }
 
 /* Badges */
-.badge { display: inline-block; padding: 0.15em 0.4em; font-size: 11px; font-weight: bold; }
+.badge {
+  display: inline-block;
+  padding: 0.15em 0.45em;
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  border-radius: 3px;
+}
+
 .badge-critical { background: #c00; color: #fff; }
 .badge-high { background: #e85d00; color: #fff; }
 .badge-medium { background: #b8860b; color: #fff; }
@@ -203,11 +403,11 @@ body {
 .badge-none { background: var(--border); color: var(--text-muted); }
 .badge-llm { background: var(--link); color: #fff; }
 
-/* Detail modal */
+/* ——— Detail modal ——— */
 #detail {
   position: fixed;
   inset: 0;
-  background: rgba(0,0,0,0.5);
+  background: rgba(0, 0, 0, 0.55);
   display: none;
   align-items: center;
   justify-content: center;
@@ -220,7 +420,9 @@ body {
 #detail .panel {
   background: var(--surface);
   border: 1px solid var(--border);
-  max-width: 520px;
+  border-radius: var(--radius);
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.35);
+  max-width: 540px;
   width: 100%;
   max-height: 90vh;
   overflow-y: auto;
@@ -229,7 +431,7 @@ body {
   -webkit-overflow-scrolling: touch;
 }
 
-#detail .panel h3 { margin: 0 0 0.35rem; font-size: 1rem; }
+#detail .panel h3 { margin: 0 0 0.35rem; font-size: 14px; font-weight: 600; }
 #detail .panel .file { font-family: ui-monospace, monospace; font-size: 13px; color: var(--link); }
 #detail .panel .close-hint { margin-top: 0.75rem; font-size: 12px; color: var(--text-muted); }
 
@@ -250,6 +452,10 @@ body {
 #detail .panel .detail-explanation .detail-llm-label { margin-top: 0.5rem; margin-bottom: 0.25rem; }
 #detail .panel .detail-explanation .detail-no-llm { font-style: italic; color: var(--text-muted); }
 #detail .panel .detail-explanation .detail-static-desc { margin-top: 0.5rem; font-size: 12px; color: var(--text-muted); }
+#detail .panel .detail-explanation .detail-issues-list { margin: 0.25rem 0 0 0; padding-left: 1.25rem; list-style: none; }
+#detail .panel .detail-explanation .detail-issues-list > li { margin-bottom: 0.35rem; }
+#detail .panel .detail-explanation .detail-issues-list .detail-issue-desc { margin: 0.15rem 0 0 1rem; font-size: 11px; opacity: 0.9; }
+#detail .panel .detail-explanation .detail-issues-list .detail-line { color: var(--text-muted); font-size: 11px; }
 
 #detail .panel .file-assessment {
   margin-top: 0.75rem;
@@ -265,14 +471,14 @@ body {
 #detail .panel .file-assessment strong { color: var(--text); font-size: 12px; }
 #detail .panel .suggested-code { margin-top: 0.75rem; }
 
-/* Code blocks - shared */
+/* ——— Code blocks ——— */
 .code-block {
   margin: 0.5rem 0;
   padding: 0.75rem 1rem;
   background: var(--bg);
   border: 1px solid var(--border);
-  border-radius: 6px;
-  font-size: 13px;
+  border-radius: var(--radius);
+  font-size: 12px;
   overflow-x: auto;
   overflow-y: auto;
   max-height: 20em;
@@ -280,43 +486,36 @@ body {
 
 .code-block .lang-label {
   display: block;
-  font-size: 11px;
+  font-size: 10px;
   font-family: system-ui, sans-serif;
   color: var(--text-muted);
   margin-bottom: 0.5rem;
   text-transform: uppercase;
-  letter-spacing: 0.03em;
+  letter-spacing: 0.04em;
 }
 
 .code-block pre { margin: 0; white-space: pre; overflow-x: auto; min-width: min-content; }
 .code-block code {
-  font-family: ui-monospace, 'SF Mono', 'Cascadia Code', 'Consolas', monospace;
+  font-family: ui-monospace, "SF Mono", "Cascadia Code", Consolas, monospace;
   font-size: 12px;
   line-height: 1.5;
   color: var(--text);
   display: block;
 }
 
-#detail .panel .code-block {
-  max-height: 16em;
-}
-
+#detail .panel .code-block { max-height: 16em; }
 #detail .panel .suggested-code .code-block { margin: 0.35rem 0 0; background: var(--surface); }
 #detail .panel .file-assessment .code-block { margin: 0.5rem 0 0; background: var(--surface); }
 
-/* LLM sections */
-.llm-overall { border-left: 3px solid var(--link); padding-left: 0.5rem; margin-left: -0.5rem; }
-.llm-overall h2 { color: var(--text); font-size: 1rem; }
-.llm-overall .llm-overall-text { margin: 0; color: var(--text); line-height: 1.5; font-size: 14px; white-space: pre-wrap; word-break: break-word; }
+/* ——— LLM output ——— */
+.llm-output .llm-prose {
+  margin: 0 0 0.75rem;
+  line-height: 1.55;
+  white-space: pre-wrap;
+  word-break: break-word;
+  color: var(--text);
+}
 
-.llm-output .llm-prose { margin: 0 0 0.75rem; line-height: 1.5; white-space: pre-wrap; word-break: break-word; }
 .llm-output .llm-prose:last-child { margin-bottom: 0; }
 
-.llm-next-steps h2 { color: var(--text); font-size: 1rem; }
-.llm-next-steps ul { margin: 0; padding-left: 1.25rem; color: var(--text); line-height: 1.5; white-space: pre-wrap; word-break: break-word; }
-
-/* Priority matrix */
-.priority-matrix { display: grid; grid-template-columns: 1fr 1fr; gap: 0.75rem; margin-top: 0.75rem; }
-.priority-matrix .quadrant { padding: 0.75rem; border: 1px solid var(--border); }
-.priority-matrix .quadrant h4 { margin: 0 0 0.35rem; font-size: 0.9rem; font-weight: bold; }
-.priority-matrix .quadrant p { margin: 0; font-size: 13px; color: var(--text-muted); }
+.panel-llm .panel-body .llm-output { margin: 0; }

package/dist/reports/assets/report.js

@@ -166,58 +166,82 @@ document.getElementById("q2").innerHTML = highImpact
   .map(function (d) { return '<li style="font-size:0.8rem">' + escapeHtml(d.file) + "</li>"; })
   .join("");
 
-// Debt list: static and LLM ratings side by side (LLM = file's rating, one per file)
+// Debt list: one row per file; static = worst severity across that file's issues, LLM = file's rating
 var sev = { critical: 4, high: 3, medium: 2, low: 1 };
 var list = document.getElementById("debtList");
-DATA.debtItems.sort(function (a, b) {
-  return (sev[b.severity] || 0) - (sev[a.severity] || 0);
-}).forEach(function (d) {
-  var li = document.createElement("li");
-  var fileM = DATA.fileMetrics.find(function (m) { return m.file === d.file; });
+var filesWithDebt = Array.from(debtByFile.keys()).sort(function (fa, fb) {
+  var itemsA = debtByFile.get(fa);
+  var itemsB = debtByFile.get(fb);
+  var worstA = itemsA.length ? Math.max.apply(null, itemsA.map(function (d) { return sev[d.severity] || 0; })) : 0;
+  var worstB = itemsB.length ? Math.max.apply(null, itemsB.map(function (d) { return sev[d.severity] || 0; })) : 0;
+  if (worstB !== worstA) return worstB - worstA;
+  return fa.localeCompare(fb);
+});
+filesWithDebt.forEach(function (file) {
+  var items = debtByFile.get(file);
+  var worstSeverityVal = items.length ? items.reduce(function (best, d) {
+    return (sev[d.severity] || 0) > (sev[best.severity] || 0) ? d : best;
+  }, items[0]) : null;
+  var staticSeverity = worstSeverityVal ? worstSeverityVal.severity : "low";
+  var fileM = DATA.fileMetrics.find(function (m) { return m.file === file; });
   var fileLlmSeverity = fileM && fileM.llmSeverity ? fileM.llmSeverity : null;
-  var staticBadge = '<span class="badge badge-' + d.severity + '" title="Static analysis">' + d.severity + "</span>";
+  var staticBadge = '<span class="badge badge-' + staticSeverity + '" title="Static analysis (worst of ' + items.length + ' issue(s))">' + staticSeverity + "</span>";
   var llmRating = fileLlmSeverity
     ? '<span class="badge badge-' + fileLlmSeverity + '" title="LLM rating for this file">' + fileLlmSeverity + "</span>"
     : '<span class="debt-list-llm-none">—</span>';
+  var titleText = items.length === 1
+    ? items[0].title
+    : worstSeverityVal.title + " (+" + (items.length - 1) + " more)";
   var ratingsRow =
     '<div class="debt-list-ratings">' +
     '<span class="debt-list-rating"><span class="debt-list-rating-label">Static</span> ' + staticBadge + "</span>" +
     '<span class="debt-list-rating"><span class="debt-list-rating-label">LLM</span> ' + llmRating + "</span>" +
     "</div>";
+  var li = document.createElement("li");
   li.innerHTML =
     '<span class="title">' +
-    escapeHtml(d.title) +
+    escapeHtml(titleText) +
     "</span> " +
     ratingsRow +
-    '<span class="meta">' +
-    escapeHtml(d.file) +
-    (d.line ? ":" + d.line : "") +
-    "</span>";
-  li.addEventListener("click", function () { showDetail(d.file, [d]); });
+    '<span class="meta">' + escapeHtml(file) + "</span>";
+  li.addEventListener("click", function () { showDetail(file, items); });
   list.appendChild(li);
 });
 
 function showDetail(file, items) {
   var panel = document.getElementById("detail");
-  var item = items.length ? items[0] : null;
   var fileMetric = DATA.fileMetrics.find(function (m) { return m.file === file; });
+  var worstItem = items.length ? items.reduce(function (best, d) {
+    return (sev[d.severity] || 0) > (sev[best.severity] || 0) ? d : best;
+  }, items[0]) : null;
+  var staticSeverity = worstItem ? worstItem.severity : "low";
 
-  document.getElementById("detailTitle").textContent = item ? item.title : "No debt items";
+  document.getElementById("detailTitle").textContent = items.length === 1
+    ? (items[0].title || "Debt item")
+    : items.length + " static issues";
   document.getElementById("detailFile").textContent = file;
 
   var explanationEl = document.getElementById("detailExplanation");
   var parts = [];
-  var staticSev = item ? item.severity : "—";
-  var llmSev = fileMetric && fileMetric.llmSeverity ? fileMetric.llmSeverity : "—";
   parts.push(
     '<div class="detail-severities">' +
-    '<span class="detail-sev"><strong>Static</strong> <span class="badge badge-' + (item ? item.severity : "low") + '">' + staticSev + "</span></span> " +
+    '<span class="detail-sev"><strong>Static</strong> <span class="badge badge-' + staticSeverity + '">' + staticSeverity + "</span> (worst of " + items.length + ")</span> " +
     '<span class="detail-sev"><strong>LLM</strong> ' +
     (fileMetric && fileMetric.llmSeverity ? '<span class="badge badge-' + fileMetric.llmSeverity + '">' + fileMetric.llmSeverity + "</span>" : "<span class=\"debt-list-llm-none\">—</span>") +
     "</span></div>"
   );
-  if (item && item.description)
-    parts.push('<div class="detail-static-desc"><strong>Static description</strong><br>' + escapeHtml(item.description).replace(/\n/g, "<br>") + "</div>");
+  parts.push('<div class="detail-static-desc"><strong>Static issues</strong><ul class="detail-issues-list">');
+  items.forEach(function (item) {
+    parts.push(
+      '<li><span class="badge badge-' + item.severity + '">' + item.severity + "</span> " +
+      escapeHtml(item.title || "Issue") +
+      (item.line ? " <span class=\"detail-line\">line " + item.line + "</span>" : "")
+    );
+    if (item.description)
+      parts.push('<div class="detail-issue-desc">' + escapeHtml(item.description).replace(/\n/g, "<br>") + "</div>");
+    parts.push("</li>");
+  });
+  parts.push("</ul></div>");
   parts.push('<div class="detail-llm-label"><strong>LLM assessment</strong></div>');
   if (fileMetric && (fileMetric.llmRawAssessment || fileMetric.llmAssessment)) {
     if (fileMetric.llmRawAssessment)

package/dist/reports/html.js

@@ -78,17 +78,20 @@ function buildHtml(run, title, darkMode, css, script) {
     };
     const tierColor = tierColors[cleanliness.tier] ?? "#666";
     const scoreBadgeSvg = buildScoreBadgeSvg(cleanliness.tier, tierColor);
-    const llmOverallSection = run.llmOverallAssessment || run.llmOverallRaw
+    const llmPanelHtml = run.llmOverallAssessment || run.llmOverallRaw
         ? `
-    <div class="section llm-overall">
-      <h2>LLM overall assessment</h2>
-      <div class="llm-output">${run.llmOverallAssessment
+    <div class="panel panel-llm">
+      <div class="panel-header">
+        <h2 class="panel-title">LLM overall assessment</h2>
+      </div>
+      <div class="panel-body">
+        <div class="llm-output">${run.llmOverallAssessment
             ? renderLlmOutputToHtml(run.llmOverallAssessment)
             : '<div class="llm-prose">' +
                 escapeHtml(stripTrailingSeverityAndScore(run.llmOverallRaw ?? "")).replace(/\n/g, "<br>") +
                 "</div>"}</div>
-    </div>
-    `
+      </div>
+    </div>`
         : "";
     return `<!DOCTYPE html>
 <html lang="en" data-theme="${theme}">
@@ -104,54 +107,113 @@ function buildHtml(run, title, darkMode, css, script) {
   <meta name="twitter:description" content="${escapeHtml(cleanliness.label)}: ${escapeHtml(cleanliness.description)}" />
   <style>${css}</style>
 </head>
-<body>
+<body class="dashboard-page">
   ${!hasLlm ? `<div class="no-llm-banner"><p class="no-llm-cta">Analysis run without LLM — for full results, run with LLM</p></div>` : ""}
-  <div class="container">
-    <p class="hero-caption">Technical Debt Cleanliness Score</p>
-    <div class="hero tier-${cleanliness.tier}">
-      <div class="score-badge" aria-label="Score ${cleanliness.tier} of 5">${scoreBadgeSvg}</div>
-      <div class="score-label">${escapeHtml(cleanliness.label)}</div>
-      <p class="score-desc">${escapeHtml(cleanliness.description)}</p>
-      <p class="report-meta">${escapeHtml(run.repoPath)} · ${run.completedAt ?? run.startedAt}</p>
+  <header class="dashboard-header">
+    <div class="dashboard-header-left">
+      <h1 class="dashboard-title">${escapeHtml(title)}</h1>
+      <span class="dashboard-meta">${escapeHtml(run.repoPath)}</span>
+    </div>
+    <div class="dashboard-header-right">
+      <div class="dashboard-score tier-${cleanliness.tier}" aria-label="Score ${cleanliness.tier} of 5">
+        <span class="dashboard-score-value">${cleanliness.tier}</span>
+        <span class="dashboard-score-of">/ 5</span>
+        <span class="dashboard-score-label">${escapeHtml(cleanliness.label)}</span>
+      </div>
+      <span class="dashboard-date">${run.completedAt ?? run.startedAt}</span>
     </div>
+  </header>
 
-    <div class="summary-cards">
-      <div class="card"><div class="value">${run.fileMetrics.length}</div><div class="label">Files</div></div>
-      <div class="card"><div class="value">${run.debtItems.length}</div><div class="label">Debt items</div></div>
-      <div class="card"><div class="value">${highCriticalCount}</div><div class="label">High / Critical</div></div>
-      <div class="card"><div class="value">${hotspotCount}</div><div class="label">Hotspots</div></div>
+  <main class="dashboard-main">
+    <div class="dashboard-grid dashboard-grid-stats">
+      <div class="panel stat-panel">
+        <div class="panel-body">
+          <div class="stat-value">${run.fileMetrics.length}</div>
+          <div class="stat-label">Files analyzed</div>
+        </div>
+      </div>
+      <div class="panel stat-panel">
+        <div class="panel-body">
+          <div class="stat-value">${run.debtItems.length}</div>
+          <div class="stat-label">Debt items</div>
+        </div>
+      </div>
+      <div class="panel stat-panel stat-panel-warn">
+        <div class="panel-body">
+          <div class="stat-value">${highCriticalCount}</div>
+          <div class="stat-label">High / Critical</div>
+        </div>
+      </div>
+      <div class="panel stat-panel">
+        <div class="panel-body">
+          <div class="stat-value">${hotspotCount}</div>
+          <div class="stat-label">Hotspots</div>
+        </div>
+      </div>
     </div>
 
-    ${llmOverallSection}
+    <div class="dashboard-grid">
+      <div class="panel panel-score tier-${cleanliness.tier}">
+        <div class="panel-header">
+          <h2 class="panel-title">Cleanliness score</h2>
+        </div>
+        <div class="panel-body panel-body-center">
+          <div class="score-badge" aria-hidden="true">${scoreBadgeSvg}</div>
+          <p class="score-desc">${escapeHtml(cleanliness.description)}</p>
+        </div>
+      </div>
+    </div>
+
+    ${llmPanelHtml}
 
-    <div class="section">
-      <h2>Files by debt</h2>
-      <p class="section-desc">Size = complexity + churn. Color = LLM severity per file (when LLM used). Click for details.</p>
-      <div class="legend">
-        <span><span class="swatch swatch-crit"></span> Critical</span>
-        <span><span class="swatch swatch-high"></span> High</span>
-        <span><span class="swatch swatch-med"></span> Medium</span>
-        <span><span class="swatch swatch-low"></span> Low</span>
-        <span><span class="swatch swatch-none"></span> No debt</span>
+    <div class="panel">
+      <div class="panel-header">
+        <h2 class="panel-title">Files by debt</h2>
+        <p class="panel-desc">Size = complexity + churn. Color = LLM severity. Click for details.</p>
+      </div>
+      <div class="panel-body">
+        <div class="legend">
+          <span><span class="swatch swatch-crit"></span> Critical</span>
+          <span><span class="swatch swatch-high"></span> High</span>
+          <span><span class="swatch swatch-med"></span> Medium</span>
+          <span><span class="swatch swatch-low"></span> Low</span>
+          <span><span class="swatch swatch-none"></span> No debt</span>
+        </div>
+        <div id="treemap"></div>
       </div>
-      <div id="treemap"></div>
     </div>
 
-    <div class="section">
-      <h2>Prioritized recommendations</h2>
-      <p class="section-desc">Focus on high-impact items first.</p>
-      <div class="priority-matrix">
-        <div class="quadrant"><h4>High impact, easier</h4><p>High severity in smaller files.</p><ul id="q1"></ul></div>
-        <div class="quadrant"><h4>High impact, harder</h4><p>Critical or hotspot files.</p><ul id="q2"></ul></div>
+    <div class="dashboard-grid dashboard-grid-half">
+      <div class="panel">
+        <div class="panel-header">
+          <h2 class="panel-title">High impact, easier</h2>
+          <p class="panel-desc">High severity in smaller files.</p>
+        </div>
+        <div class="panel-body">
+          <ul id="q1" class="priority-list"></ul>
+        </div>
+      </div>
+      <div class="panel">
+        <div class="panel-header">
+          <h2 class="panel-title">High impact, harder</h2>
+          <p class="panel-desc">Critical or hotspot files.</p>
+        </div>
+        <div class="panel-body">
+          <ul id="q2" class="priority-list"></ul>
+        </div>
       </div>
     </div>
 
-    <div class="section">
-      <h2>All debt items</h2>
-      <p class="section-desc">Static (analysis) and LLM ratings shown side by side. Click a row for details.</p>
-      <ul class="debt-list" id="debtList"></ul>
+    <div class="panel">
+      <div class="panel-header">
+        <h2 class="panel-title">All debt items</h2>
+        <p class="panel-desc">Static and LLM ratings. Click a row for details.</p>
+      </div>
+      <div class="panel-body">
+        <ul class="debt-list" id="debtList"></ul>
+      </div>
     </div>
-  </div>
+  </main>
 
   <div id="detail">
     <div class="panel">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tech-debt-visualizer",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Language-agnostic CLI that analyzes repos and generates interactive technical debt visualizations with AI-powered insights",
   "type": "module",
   "main": "dist/index.js",