tech-debt-visualizer 0.1.0

package/dist/llm.js

@@ -0,0 +1,227 @@
+/**
+ * LLM integration: debt explanations, per-file cleanliness, and overall assessment.
+ * Supports OpenAI, OpenRouter (OpenAI-compatible), and Google Gemini.
+ */
+const OPENAI_DEFAULT_MODEL = "gpt-4o-mini";
+const OPENROUTER_DEFAULT_MODEL = "google/gemini-2.0-flash-001";
+const GEMINI_DEFAULT_MODEL = "gemini-1.5-flash";
+const DEFAULT_MAX_TOKENS = 300;
+const DEFAULT_MAX_TOKENS_OVERALL = 500;
+const OPENROUTER_BASE = "https://openrouter.ai/api/v1";
+const GEMINI_BASE = "https://generativelanguage.googleapis.com/v1beta";
+/** Extract first markdown code block and the prose before it. */
+function parseCodeBlockAndProse(response) {
+    const match = response.match(/^(.*?)(?:```(?:\w*)\n?([\s\S]*?)```|$)/);
+    if (!match)
+        return { prose: response.trim() };
+    const prose = match[1].trim();
+    const code = match[2]?.trim();
+    return { prose, code: code || undefined };
+}
+/** Resolve provider and auth from config + env. OpenRouter and Gemini take precedence when their keys are set. */
+export function resolveLLMConfig(config = {}) {
+    const openRouterKey = config.apiKey ?? process.env.OPENROUTER_API_KEY;
+    const geminiKey = config.apiKey ?? process.env.GEMINI_API_KEY ?? process.env.GOOGLE_GENAI_API_KEY;
+    const openaiKey = config.apiKey ?? process.env.OPENAI_API_KEY ?? process.env.ANTHROPIC_API_KEY;
+    if (openRouterKey) {
+        return {
+            provider: "openrouter",
+            apiKey: openRouterKey,
+            baseURL: config.baseURL ?? process.env.OPENROUTER_BASE_URL ?? OPENROUTER_BASE,
+            model: config.model ?? process.env.OPENROUTER_MODEL ?? OPENROUTER_DEFAULT_MODEL,
+        };
+    }
+    if (geminiKey) {
+        return {
+            provider: "gemini",
+            apiKey: geminiKey,
+            baseURL: GEMINI_BASE,
+            model: config.model ?? process.env.GEMINI_MODEL ?? GEMINI_DEFAULT_MODEL,
+        };
+    }
+    if (openaiKey) {
+        return {
+            provider: "openai",
+            apiKey: openaiKey,
+            baseURL: config.baseURL ?? process.env.OPENAI_BASE_URL ?? "",
+            model: config.model ?? process.env.OPENAI_MODEL ?? OPENAI_DEFAULT_MODEL,
+        };
+    }
+    return null;
+}
+async function chat(prompt, opts) {
+    const provider = opts.provider ?? (opts.baseURL?.includes("openrouter") ? "openrouter" : "openai");
+    if (provider === "gemini") {
+        return geminiCompletion(prompt, { apiKey: opts.apiKey, model: opts.model, maxTokens: opts.maxTokens });
+    }
+    return openAICompatibleCompletion(prompt, opts);
+}
+async function openAICompatibleCompletion(prompt, opts) {
+    try {
+        const url = opts.baseURL
+            ? `${opts.baseURL.replace(/\/$/, "")}/chat/completions`
+            : "https://api.openai.com/v1/chat/completions";
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${opts.apiKey}`,
+            },
+            body: JSON.stringify({
+                model: opts.model,
+                messages: [{ role: "user", content: prompt }],
+                max_tokens: opts.maxTokens,
+            }),
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        const text = data.choices?.[0]?.message?.content?.trim();
+        return text || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function geminiCompletion(prompt, opts) {
+    try {
+        const modelId = opts.model.replace(/^models\//, "");
+        const url = `${GEMINI_BASE}/models/${modelId}:generateContent?key=${encodeURIComponent(opts.apiKey)}`;
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                contents: [{ parts: [{ text: prompt }] }],
+                generationConfig: {
+                    maxOutputTokens: opts.maxTokens,
+                    temperature: 0.2,
+                },
+            }),
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        const text = data.candidates?.[0]?.content?.parts?.[0]?.text?.trim();
+        return text || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function enrichDebtWithInsights(items, fileContents, config = {}) {
+    const resolved = resolveLLMConfig(config);
+    if (!resolved)
+        return items;
+    const { provider, apiKey, baseURL, model } = resolved;
+    const maxTokens = config.maxTokens ?? DEFAULT_MAX_TOKENS;
+    const enriched = [];
+    const batchSize = 5;
+    for (let i = 0; i < items.length; i += batchSize) {
+        const batch = items.slice(i, i + batchSize);
+        const results = await Promise.allSettled(batch.map((item) => explainDebtItem(item, fileContents.get(item.file) ?? "", {
+            apiKey,
+            baseURL,
+            model,
+            maxTokens,
+            provider,
+        })));
+        for (let j = 0; j < batch.length; j++) {
+            const item = batch[j];
+            const result = results[j];
+            if (result?.status === "fulfilled" && result.value) {
+                const v = result.value;
+                enriched.push({
+                    ...item,
+                    insight: v.insight,
+                    suggestedCode: v.suggestedCode,
+                });
+            }
+            else {
+                enriched.push(item);
+            }
+        }
+    }
+    return enriched;
+}
+async function explainDebtItem(item, fileContent, opts) {
+    const snippet = item.line
+        ? fileContent.split("\n").slice(Math.max(0, item.line - 3), (item.endLine ?? item.line) + 2).join("\n")
+        : fileContent.slice(0, 1500);
+    const prompt = `You are a senior engineer reviewing technical debt. For this item:
+
+1) In 1-2 sentences: why it matters for maintainability or risk, and what to do.
+2) If a concrete code simplification or refactor is possible (e.g. reduce branching, extract function, simplify condition), provide ONLY the refactored/simplified code in a markdown code block. Use the same language as the snippet. If no code change is needed or the fix is trivial (e.g. "add a comment"), omit the code block.
+
+Debt: ${item.title}
+Category: ${item.category}
+Description: ${item.description}
+${item.metrics ? `Metrics: ${JSON.stringify(item.metrics)}` : ""}
+
+Relevant code:
+\`\`\`
+${snippet}
+\`\`\`
+
+Reply format: Short explanation first, then optionally a code block with the suggested refactor. No other preamble.`;
+    const raw = await chat(prompt, { ...opts, maxTokens: 500 });
+    if (!raw)
+        return null;
+    const { prose, code } = parseCodeBlockAndProse(raw);
+    return { insight: prose || item.description, suggestedCode: code };
+}
+/** Per-file: LLM assesses cleanliness and optionally suggests a concrete code simplification. */
+export async function assessFileCleanliness(filePath, content, metrics, config = {}) {
+    const resolved = resolveLLMConfig(config);
+    if (!resolved)
+        return null;
+    const snippet = content.length > 4000 ? content.slice(0, 4000) + "\n\n[... truncated]" : content;
+    const prompt = `You are a senior engineer assessing code cleanliness. For this file:
+
+1) In 1-2 sentences: how clean and maintainable is it, and one concrete improvement (or "Looks good" if fine).
+2) If one specific code simplification or streamlining is possible (e.g. simplify a function, reduce nesting, extract a helper), provide ONLY that refactored snippet in a markdown code block. Same language as the file. If no clear code change applies, omit the code block.
+
+File: ${filePath}
+Metrics: complexity ${metrics.cyclomaticComplexity ?? "?"}, lines ${metrics.lineCount}, ${metrics.hasDocumentation ? "has docs" : "no module docs"}${metrics.hotspotScore != null ? `, hotspot ${metrics.hotspotScore.toFixed(2)}` : ""}.
+
+Code:
+\`\`\`
+${snippet}
+\`\`\`
+
+Reply: short assessment first, then optionally a code block with the suggested refactor. No preamble.`;
+    const raw = await chat(prompt, {
+        ...resolved,
+        maxTokens: config.maxTokens ?? 400,
+    });
+    if (!raw)
+        return null;
+    const { prose, code } = parseCodeBlockAndProse(raw);
+    return { assessment: prose, suggestedCode: code };
+}
+/** Overall: LLM assesses the whole codebase cleanliness in a short paragraph. */
+export async function assessOverallCleanliness(run, config = {}) {
+    const resolved = resolveLLMConfig(config);
+    if (!resolved)
+        return null;
+    const fileCount = run.fileMetrics.length;
+    const debtCount = run.debtItems.length;
+    const criticalHigh = run.debtItems.filter((d) => d.severity === "critical" || d.severity === "high").length;
+    const hotspots = run.fileMetrics.filter((m) => (m.hotspotScore ?? 0) > 0.3).length;
+    const topFiles = run.fileMetrics
+        .sort((a, b) => (b.hotspotScore ?? 0) - (a.hotspotScore ?? 0))
+        .slice(0, 12)
+        .map((m) => m.file);
+    const prompt = `You are a senior engineer giving a brief overall assessment of a codebase's technical debt and cleanliness.
+
+Summary:
+- ${fileCount} files analyzed
+- ${debtCount} debt items (${criticalHigh} critical/high)
+- ${hotspots} hotspot files (high churn + complexity)
+- Top files by risk: ${topFiles.join(", ")}
+
+In one short paragraph (3-5 sentences), assess overall cleanliness: main strengths or concerns, and the single most important thing to improve. Be direct and actionable. No preamble.`;
+    return chat(prompt, {
+        ...resolved,
+        maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS_OVERALL,
+    });
+}

package/dist/reports/html.d.ts

@@ -0,0 +1,7 @@
+import type { AnalysisRun } from "../types.js";
+export interface HtmlReportOptions {
+    outputPath: string;
+    title?: string;
+    darkMode?: boolean;
+}
+export declare function generateHtmlReport(run: AnalysisRun, options: HtmlReportOptions): Promise<void>;

package/dist/reports/html.js

@@ -0,0 +1,434 @@
+import { writeFile } from "node:fs/promises";
+import { getCleanlinessTier } from "../cleanliness-score.js";
+function getDebtScore(run) {
+    const items = run.debtItems;
+    if (items.length === 0)
+        return 0;
+    const severityWeight = { low: 1, medium: 2, high: 3, critical: 4 };
+    const sum = items.reduce((a, b) => a + (severityWeight[b.severity] ?? 0) * b.confidence, 0);
+    return Math.min(100, Math.round((sum / items.length) * 25));
+}
+export async function generateHtmlReport(run, options) {
+    const { outputPath, title = "Technical Debt Report", darkMode = true } = options;
+    const html = buildHtml(run, title, darkMode);
+    await writeFile(outputPath, html, "utf-8");
+}
+function buildHtml(run, title, darkMode) {
+    const theme = darkMode ? "dark" : "light";
+    const debtScore = getDebtScore(run);
+    const cleanliness = getCleanlinessTier(debtScore);
+    const dataJson = JSON.stringify({
+        fileMetrics: run.fileMetrics,
+        debtItems: run.debtItems,
+        debtTrend: run.debtTrend ?? [],
+        llmOverallAssessment: run.llmOverallAssessment ?? null,
+        summary: {
+            filesAnalyzed: run.fileMetrics.length,
+            debtCount: run.debtItems.length,
+            debtScore,
+            cleanlinessTier: cleanliness.tier,
+            cleanlinessLabel: cleanliness.label,
+            cleanlinessDescription: cleanliness.description,
+            repoPath: run.repoPath,
+            completedAt: run.completedAt ?? run.startedAt,
+        },
+    });
+    return `<!DOCTYPE html>
+<html lang="en" data-theme="${theme}">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${escapeHtml(title)}</title>
+  <script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js"></script>
+  <style>
+    :root {
+      --bg: #0f0f12;
+      --surface: #1a1a1f;
+      --border: #2a2a32;
+      --text: #e4e4e7;
+      --text-muted: #71717a;
+      --accent: #6366f1;
+      --accent-dim: #4f46e5;
+      --green: #22c55e;
+      --yellow: #eab308;
+      --red: #ef4444;
+      --gradient: linear-gradient(135deg, #6366f1 0%, #8b5cf6 50%, #a855f7 100%);
+    }
+    [data-theme="light"] {
+      --bg: #fafafa;
+      --surface: #fff;
+      --border: #e4e4e7;
+      --text: #18181b;
+      --text-muted: #71717a;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      font-family: 'Inter', 'SF Pro Display', -apple-system, BlinkMacSystemFont, sans-serif;
+      background: var(--bg);
+      color: var(--text);
+      min-height: 100vh;
+      letter-spacing: -0.01em;
+    }
+    .container { max-width: 1100px; margin: 0 auto; padding: 2.5rem 2rem; }
+    .hero-caption { font-size: 0.7rem; text-transform: uppercase; letter-spacing: 0.14em; color: var(--text-muted); margin: 0 0 0.75rem; font-weight: 600; }
+    .hero {
+      display: flex;
+      align-items: stretch;
+      gap: 0;
+      margin-bottom: 2.5rem;
+      border-radius: 16px;
+      overflow: hidden;
+      background: var(--surface);
+      border: 1px solid var(--border);
+    }
+    .hero-grade {
+      width: 140px;
+      flex-shrink: 0;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      padding: 2rem 1.5rem;
+      background: var(--tier-bg);
+      border-right: 1px solid var(--border);
+    }
+    .hero-grade .num { font-size: 3rem; font-weight: 800; line-height: 1; color: var(--tier-fg); letter-spacing: -0.03em; }
+    .hero-grade .of { font-size: 0.75rem; color: var(--tier-fg); opacity: 0.7; margin-top: 0.25rem; text-transform: uppercase; letter-spacing: 0.1em; }
+    .hero-body { flex: 1; padding: 2rem 2.25rem; min-width: 0; }
+    .hero-body .score-label { font-size: 1.35rem; font-weight: 700; color: var(--text); margin: 0 0 0.35rem; letter-spacing: -0.02em; }
+    .hero-body .score-desc { font-size: 0.9rem; color: var(--text-muted); line-height: 1.45; margin: 0; }
+    .hero-body .report-meta { font-size: 0.8rem; color: var(--text-muted); margin-top: 1.25rem; }
+    .hero.tier-1 { --tier-bg: #1c1917; --tier-fg: #f87171; }
+    .hero.tier-2 { --tier-bg: #1c1917; --tier-fg: #fb923c; }
+    .hero.tier-3 { --tier-bg: #1c1917; --tier-fg: #facc15; }
+    .hero.tier-4 { --tier-bg: #0f172a; --tier-fg: #38bdf8; }
+    .hero.tier-5 { --tier-bg: #052e16; --tier-fg: #4ade80; }
+    [data-theme="light"] .hero.tier-1 { --tier-bg: #fef2f2; --tier-fg: #dc2626; }
+    [data-theme="light"] .hero.tier-2 { --tier-bg: #fff7ed; --tier-fg: #ea580c; }
+    [data-theme="light"] .hero.tier-3 { --tier-bg: #fefce8; --tier-fg: #ca8a04; }
+    [data-theme="light"] .hero.tier-4 { --tier-bg: #f0f9ff; --tier-fg: #0284c7; }
+    [data-theme="light"] .hero.tier-5 { --tier-bg: #f0fdf4; --tier-fg: #16a34a; }
+    .summary-cards {
+      display: grid;
+      grid-template-columns: repeat(4, 1fr);
+      gap: 1rem;
+      margin-bottom: 2.5rem;
+    }
+    @media (max-width: 640px) { .summary-cards { grid-template-columns: repeat(2, 1fr); } }
+    .card {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 12px;
+      padding: 1.25rem 1.35rem;
+      transition: border-color 0.2s;
+    }
+    .card:hover { border-color: var(--text-muted); }
+    .card .value { font-size: 1.65rem; font-weight: 700; color: var(--text); letter-spacing: -0.02em; }
+    .card .label { font-size: 0.72rem; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.06em; margin-top: 0.2rem; }
+    .section {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 12px;
+      padding: 1.5rem;
+      margin-bottom: 1.5rem;
+    }
+    .section h2 { font-size: 1.1rem; margin: 0 0 1rem; color: var(--text-muted); font-weight: 600; }
+    #treemap {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 4px;
+      min-height: 280px;
+    }
+    .treemap-cell {
+      border-radius: 6px;
+      display: flex;
+      align-items: flex-end;
+      padding: 6px 8px;
+      font-size: 0.7rem;
+      cursor: pointer;
+      transition: transform 0.15s, filter 0.15s;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+    .treemap-cell:hover { transform: scale(1.03); filter: brightness(1.1); }
+    .treemap-cell[data-severity="critical"] { background: linear-gradient(180deg, #ef4444 0%, #b91c1c 100%); color: #fff; }
+    .treemap-cell[data-severity="high"]    { background: linear-gradient(180deg, #f59e0b 0%, #d97706 100%); color: #fff; }
+    .treemap-cell[data-severity="medium"]  { background: linear-gradient(180deg, #eab308 0%, #ca8a04 100%); color: #1a1a1f; }
+    .treemap-cell[data-severity="low"]     { background: linear-gradient(180deg, #22c55e 0%, #16a34a 100%); color: #fff; }
+    .treemap-cell[data-severity="none"]    { background: var(--border); color: var(--text-muted); }
+    #trendChart { max-height: 220px; }
+    .debt-list { list-style: none; padding: 0; margin: 0; }
+    .debt-list li {
+      border-bottom: 1px solid var(--border);
+      padding: 0.85rem 0;
+      cursor: pointer;
+      transition: background 0.15s;
+    }
+    .debt-list li:last-child { border-bottom: none; }
+    .debt-list li:hover { background: rgba(99, 102, 241, 0.08); }
+    .debt-list .title { font-weight: 600; margin-bottom: 0.25rem; }
+    .debt-list .meta { font-size: 0.8rem; color: var(--text-muted); }
+    .debt-list .insight { font-size: 0.85rem; color: var(--text-muted); margin-top: 0.35rem; line-height: 1.4; }
+    .badge { display: inline-block; padding: 0.2em 0.5em; border-radius: 4px; font-size: 0.7rem; font-weight: 600; }
+    .badge-critical { background: #ef4444; color: #fff; }
+    .badge-high { background: #f59e0b; color: #fff; }
+    .badge-medium { background: #eab308; color: #1a1a1f; }
+    .badge-low { background: #22c55e; color: #fff; }
+    #detail {
+      position: fixed;
+      inset: 0;
+      background: rgba(0,0,0,0.6);
+      display: none;
+      align-items: center;
+      justify-content: center;
+      z-index: 100;
+      padding: 2rem;
+    }
+    #detail.show { display: flex; }
+    #detail .panel {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 16px;
+      max-width: 520px;
+      width: 100%;
+      max-height: 85vh;
+      overflow: auto;
+      padding: 1.5rem;
+    }
+    #detail .panel h3 { margin: 0 0 0.5rem; }
+    #detail .panel .file { font-family: monospace; font-size: 0.85rem; color: var(--accent); }
+    #detail .panel .explanation { margin-top: 1rem; line-height: 1.5; color: var(--text-muted); }
+    #detail .panel .close-hint { margin-top: 1rem; font-size: 0.75rem; color: var(--text-muted); opacity: 0.8; }
+    #detail .panel .file-assessment { margin-top: 1rem; padding-top: 1rem; border-top: 1px solid var(--border); font-size: 0.9rem; color: var(--text-muted); line-height: 1.5; }
+    #detail .panel .file-assessment strong { color: var(--text); font-size: 0.8rem; text-transform: uppercase; letter-spacing: 0.05em; }
+    #detail .panel .suggested-code { margin-top: 1rem; padding: 0.75rem; background: var(--bg); border: 1px solid var(--border); border-radius: 8px; font-size: 0.8rem; overflow-x: auto; }
+    #detail .panel .suggested-code pre { margin: 0; white-space: pre-wrap; }
+    .llm-overall .llm-overall-text { margin: 0; color: var(--text); line-height: 1.6; }
+    .priority-matrix { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin-top: 1rem; }
+    .priority-matrix .quadrant { padding: 1rem; border-radius: 8px; border: 1px solid var(--border); }
+    .priority-matrix .quadrant h4 { margin: 0 0 0.5rem; font-size: 0.9rem; }
+    .priority-matrix .quadrant p { margin: 0; font-size: 0.8rem; color: var(--text-muted); }
+    .glossary {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 12px;
+      padding: 1.25rem 1.5rem;
+      margin-bottom: 1.5rem;
+    }
+    .glossary h2 { font-size: 0.95rem; margin: 0 0 0.75rem; color: var(--text-muted); font-weight: 600; }
+    .glossary dl { margin: 0; font-size: 0.875rem; line-height: 1.6; }
+    .glossary dt { font-weight: 600; color: var(--text); margin-top: 0.5rem; }
+    .glossary dt:first-child { margin-top: 0; }
+    .glossary dd { margin: 0.2rem 0 0 1rem; color: var(--text-muted); }
+    .section-desc { font-size: 0.875rem; color: var(--text-muted); margin: -0.5rem 0 1rem; line-height: 1.45; }
+    .legend { display: flex; flex-wrap: wrap; gap: 1rem; align-items: center; margin-bottom: 1rem; font-size: 0.8rem; color: var(--text-muted); }
+    .legend span { display: inline-flex; align-items: center; gap: 0.35rem; }
+    .legend .swatch { width: 12px; height: 12px; border-radius: 3px; }
+    .legend .swatch-crit { background: linear-gradient(135deg, #ef4444, #b91c1c); }
+    .legend .swatch-high { background: linear-gradient(135deg, #f59e0b, #d97706); }
+    .legend .swatch-med { background: linear-gradient(135deg, #eab308, #ca8a04); }
+    .legend .swatch-low { background: linear-gradient(135deg, #22c55e, #16a34a); }
+    .legend .swatch-none { background: var(--border); }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <p class="hero-caption">Technical Debt Cleanliness Score</p>
+    <div class="hero tier-${cleanliness.tier}">
+      <div class="hero-grade">
+        <span class="num">${cleanliness.tier}</span>
+        <span class="of">of 5</span>
+      </div>
+      <div class="hero-body">
+        <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>
+      </div>
+    </div>
+
+    <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">${run.debtItems.filter(d => d.severity === 'high' || d.severity === 'critical').length}</div><div class="label">High / Critical</div></div>
+      <div class="card"><div class="value">${run.fileMetrics.filter(m => (m.hotspotScore ?? 0) > 0.3).length}</div><div class="label">Hotspots</div></div>
+    </div>
+
+    ${run.llmOverallAssessment ? `
+    <div class="section llm-overall">
+      <h2>LLM overall assessment</h2>
+      <p class="llm-overall-text">${escapeHtml(run.llmOverallAssessment)}</p>
+    </div>
+    ` : ""}
+
+    <div class="glossary">
+      <h2>Understanding this report</h2>
+      <dl>
+        <dt>Debt score (0–100)</dt>
+        <dd>Combined severity and confidence of all issues. Lower is better. &lt;40 = healthy, 40–70 = address soon, 70+ = high priority.</dd>
+        <dt>Severity</dt>
+        <dd><strong>Critical</strong> = fix first. <strong>High</strong> = plan soon. <strong>Medium/Low</strong> = backlog.</dd>
+        <dt>Cyclomatic complexity</dt>
+        <dd>Decision paths in code (if/else, loops). &gt;10 high, &gt;20 critical.</dd>
+        <dt>Hotspot</dt>
+        <dd>Files that change often and have high complexity—highest refactor risk.</dd>
+        <dt>Trend chart</dt>
+        <dd>Heuristic from recent commits; shows churn pattern, not full history.</dd>
+      </dl>
+    </div>
+
+    <div class="section">
+      <h2>Debt distribution by file</h2>
+      <p class="section-desc">Each block is a file. <strong>Size</strong> = complexity + churn (larger = heavier). <strong>Color</strong> = worst severity in that file. Click a block to see 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>
+      <div id="treemap"></div>
+    </div>
+
+    <div class="section">
+      <h2>Debt trend (recent commits)</h2>
+      <p class="section-desc">Estimated activity per commit (files changed). Rising pattern may indicate growing churn; not a full historical debt metric.</p>
+      <canvas id="trendChart"></canvas>
+    </div>
+
+    <div class="section">
+      <h2>Prioritized recommendations</h2>
+      <p class="section-desc">Focus on high-impact items first. Easy wins = high severity but smaller files; harder = critical or hotspot files that need planning.</p>
+      <div class="priority-matrix">
+        <div class="quadrant"><h4>High impact, easier</h4><p>High severity in smaller or less complex files. Good first targets.</p><ul id="q1"></ul></div>
+        <div class="quadrant"><h4>High impact, harder</h4><p>Critical or hotspot files. Plan refactors and tests.</p><ul id="q2"></ul></div>
+      </div>
+    </div>
+
+    <div class="section">
+      <h2>All debt items</h2>
+      <p class="section-desc">Full list by severity. Click a row to see the detail panel.</p>
+      <ul class="debt-list" id="debtList"></ul>
+    </div>
+  </div>
+
+  <div id="detail"><div class="panel"><h3 id="detailTitle"></h3><div class="file" id="detailFile"></div><div class="explanation" id="detailExplanation"></div><div class="suggested-code" id="detailSuggestedCode"></div><div class="file-assessment" id="detailFileAssessment"></div><p class="close-hint">Click outside to close</p></div></div>
+
+  <script>
+    const DATA = ${dataJson};
+
+    function escapeHtml(s) {
+      const div = document.createElement('div');
+      div.textContent = s;
+      return div.innerHTML;
+    }
+
+    // Treemap: file blocks by debt weight
+    const fileScores = DATA.fileMetrics.map(m => ({
+      file: m.file,
+      score: (m.cyclomaticComplexity ?? 0) * 2 + (m.hotspotScore ?? 0) * 50 + (m.lineCount ?? 0) / 10,
+      complexity: m.cyclomaticComplexity ?? 0,
+      hotspot: m.hotspotScore ?? 0,
+    })).filter(x => x.score > 0).sort((a,b) => b.score - a.score).slice(0, 60);
+    const maxScore = Math.max(...fileScores.map(x => x.score), 1);
+    const debtByFile = new Map();
+    DATA.debtItems.forEach(d => {
+      const arr = debtByFile.get(d.file) || [];
+      arr.push(d);
+      debtByFile.set(d.file, arr);
+    });
+    const treemap = document.getElementById('treemap');
+    fileScores.forEach(({ file, score }) => {
+      const items = debtByFile.get(file) || [];
+      const severity = items.length ? items.reduce((a,b) => (a === 'critical' || b.severity === 'critical' ? 'critical' : b.severity === 'high' ? 'high' : b.severity), 'low') : 'none';
+      const cell = document.createElement('div');
+      cell.className = 'treemap-cell';
+      cell.dataset.severity = severity;
+      cell.style.flex = String(score / maxScore * 100) + ' 1 80px';
+      cell.style.minWidth = '80px';
+      cell.title = file;
+      cell.textContent = file.split('/').pop() || file;
+      cell.addEventListener('click', () => showDetail(file, items));
+      treemap.appendChild(cell);
+    });
+
+    // Trend chart
+    const ctx = document.getElementById('trendChart').getContext('2d');
+    new Chart(ctx, {
+      type: 'line',
+      data: {
+        labels: (DATA.debtTrend || []).map(t => t.commit),
+        datasets: [{
+          label: 'Debt score',
+          data: (DATA.debtTrend || []).map(t => t.score),
+          borderColor: '#6366f1',
+          backgroundColor: 'rgba(99, 102, 241, 0.1)',
+          fill: true,
+          tension: 0.3,
+        }]
+      },
+      options: {
+        responsive: true,
+        plugins: { legend: { display: false } },
+        scales: {
+          y: { beginAtZero: true, grid: { color: 'var(--border)' }, ticks: { color: 'var(--text-muted)' } },
+          x: { grid: { color: 'var(--border)' }, ticks: { color: 'var(--text-muted)' } }
+        }
+      }
+    });
+
+    // Priority quadrants
+    const highImpact = DATA.debtItems.filter(d => d.severity === 'high' || d.severity === 'critical').slice(0, 5);
+    document.getElementById('q1').innerHTML = highImpact.slice(0, 3).map(d => '<li style="font-size:0.8rem">' + escapeHtml(d.file) + '</li>').join('');
+    document.getElementById('q2').innerHTML = highImpact.slice(3, 6).map(d => '<li style="font-size:0.8rem">' + escapeHtml(d.file) + '</li>').join('');
+
+    // Debt list
+    const list = document.getElementById('debtList');
+    const sev = { critical: 4, high: 3, medium: 2, low: 1 };
+    DATA.debtItems.sort((a,b) => (sev[b.severity] || 0) - (sev[a.severity] || 0)).forEach(d => {
+      const li = document.createElement('li');
+      li.innerHTML = '<span class="title">' + escapeHtml(d.title) + '</span> <span class="badge badge-' + d.severity + '">' + d.severity + '</span>' + (d.suggestedCode ? ' <span class="badge" style="background:var(--accent);color:#fff">refactor</span>' : '') + '<br><span class="meta">' + escapeHtml(d.file) + (d.line ? ':' + d.line : '') + '</span>' + (d.insight ? '<div class="insight">' + escapeHtml(d.insight) + '</div>' : '');
+      li.addEventListener('click', () => showDetail(d.file, [d]));
+      list.appendChild(li);
+    });
+
+    function showDetail(file, items) {
+      const panel = document.getElementById('detail');
+      const item = items.length ? items[0] : null;
+      document.getElementById('detailTitle').textContent = item ? item.title : 'No debt items';
+      document.getElementById('detailFile').textContent = file;
+      document.getElementById('detailExplanation').textContent = item && item.insight ? item.insight : (item ? item.description : '');
+      const codeEl = document.getElementById('detailSuggestedCode');
+      if (item && item.suggestedCode) {
+        codeEl.style.display = 'block';
+        codeEl.innerHTML = '<strong>Suggested refactor</strong><pre>' + escapeHtml(item.suggestedCode) + '</pre>';
+      } else {
+        codeEl.style.display = 'none';
+        codeEl.textContent = '';
+      }
+      const fileMetric = DATA.fileMetrics.find(m => m.file === file);
+      const fileAssessEl = document.getElementById('detailFileAssessment');
+      if (fileMetric && (fileMetric.llmAssessment || fileMetric.llmSuggestedCode)) {
+        fileAssessEl.style.display = 'block';
+        let html = '<strong>LLM file assessment</strong><br>' + (fileMetric.llmAssessment ? escapeHtml(fileMetric.llmAssessment) : '');
+        if (fileMetric.llmSuggestedCode) html += '<br><br><strong>Suggested refactor</strong><pre style="margin:0.5rem 0 0;padding:0.5rem;background:var(--bg);border-radius:6px;font-size:0.8rem;overflow-x:auto">' + escapeHtml(fileMetric.llmSuggestedCode) + '</pre>';
+        fileAssessEl.innerHTML = html;
+      } else {
+        fileAssessEl.style.display = 'none';
+        fileAssessEl.textContent = '';
+      }
+      panel.classList.add('show');
+      panel.onclick = e => { if (e.target === panel) panel.classList.remove('show'); };
+    }
+  </script>
+</body>
+</html>`;
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}

package/dist/reports/json.d.ts

@@ -0,0 +1,2 @@
+import type { AnalysisRun } from "../types.js";
+export declare function generateJsonReport(run: AnalysisRun): string;