tech-debt-visualizer 0.1.0 → 0.1.2

package/README.md

@@ -35,7 +35,7 @@ The tool runs a fixed pipeline so you know exactly what you’re getting.
    Pluggable analyzers (today: JavaScript/TypeScript and Python) parse each file with **tree-sitter**, then:
    - Count **cyclomatic complexity** (if/else, loops, switch, ternaries, `&&`/`||`).
    - Count effective lines and check for **module-level docs** (JSDoc, docstrings).
-   - Emit **debt items** (e.g. “High cyclomatic complexity”, “Missing documentation”, “Large file”) with severity and confidence.
+   - Emit **debt items** (e.g. “High cyclomatic complexity”, “Missing documentation”, “Large file”, “TODO/FIXME/HACK/XXX markers”) with severity and confidence.
 
 3. **Enrich with git**  
    Uses `git log` (e.g. last 90 days) to compute per-file **churn** and **commit count**. Combines that with complexity into a **hotspot score**: files that change often and are complex are treated as higher risk. A simple **debt trend** over recent commits is also derived (heuristic, not full historical analysis).
@@ -43,11 +43,13 @@ The tool runs a fixed pipeline so you know exactly what you’re getting.
 4. **Score and tier**  
    A single **debt score** (0–100) is computed from severity and confidence of all debt items. That score is mapped to a **Cleanliness tier** (1–5), e.g. “Thoughtful Prompter (3/5)” or “Pure Coder (5/5)”, shown at the top of the CLI and report.
 
+   **How the score is calculated:** Each debt item has a severity (low=1, medium=2, high=3, critical=4) and a confidence (0–1). The score is the weighted average of (severity × confidence) across all items, scaled by 25 and capped at 100: more or worse items → higher score (worse cleanliness).
+
 5. **Optional LLM pass**  
    If an API key is set and you don’t use `--no-llm`, the tool:
-   - Asks the LLM to assess **per-file cleanliness** for the top ~15 hotspot files (and optionally suggest a **concrete code refactor** in a code block).
+   - Asks the LLM to assess **per-file cleanliness** for each analyzed file (up to 80) with repo context for cross-file suggestions (and optionally suggest a **concrete code refactor** in a code block).
    - Asks the LLM to explain **each debt item** (why it matters, what to do) and optionally suggest a **simplified/refactored code snippet**.
-   - Asks the LLM for one **overall codebase assessment** (a short paragraph).
+   - Asks the LLM for one **overall codebase assessment** (a short paragraph) and optional **prioritized next steps** (3–5 bullets).
 
    Responses are parsed: prose goes into insights/assessments; any markdown code block is stored as **suggested refactor** and shown in CLI and HTML.
 

package/dist/analyzers/base.d.ts

@@ -8,6 +8,11 @@ import type { DebtCategory, DebtItem, Severity } from "../types.js";
 export declare function countComplexity(node: Parser.SyntaxNode): number;
 /** Count lines in source (excluding empty and comment-only). */
 export declare function effectiveLines(source: string): number;
+/** Find TODO/FIXME/HACK/XXX markers (e.g. in comments). Returns 1-based line numbers and tag. */
+export declare function findTodoFixmeHack(source: string): {
+    line: number;
+    tag: string;
+}[];
 export declare function createDebtItem(file: string, category: DebtCategory, title: string, description: string, opts?: {
     line?: number;
     endLine?: number;
@@ -15,4 +20,11 @@ export declare function createDebtItem(file: string, category: DebtCategory, tit
     confidence?: number;
     metrics?: Record<string, number | string>;
 }): DebtItem;
+/** Cyclomatic complexity → severity: low 15–24, medium 25–39, high 40–59, critical ≥ 60. */
+export declare const CYCLOMATIC_THRESHOLDS: {
+    readonly low: 15;
+    readonly medium: 25;
+    readonly high: 40;
+    readonly critical: 60;
+};
 export declare function inferSeverity(complexity: number): Severity;

package/dist/analyzers/base.js

@@ -42,6 +42,17 @@ export function effectiveLines(source) {
         return t.length > 0 && !t.startsWith("//") && !t.startsWith("#") && !t.startsWith("/*") && !t.startsWith("*");
     }).length;
 }
+const TODO_FIXME_RE = /\b(TODO|FIXME|HACK|XXX)\b/i;
+/** Find TODO/FIXME/HACK/XXX markers (e.g. in comments). Returns 1-based line numbers and tag. */
+export function findTodoFixmeHack(source) {
+    const out = [];
+    source.split("\n").forEach((line, i) => {
+        const m = line.match(TODO_FIXME_RE);
+        if (m)
+            out.push({ line: i + 1, tag: m[1].toUpperCase() });
+    });
+    return out;
+}
 export function createDebtItem(file, category, title, description, opts = {}) {
     const id = `${file}:${opts.line ?? 0}:${category}:${title.slice(0, 30)}`.replace(/\s/g, "_");
     return {
@@ -57,12 +68,16 @@ export function createDebtItem(file, category, title, description, opts = {}) {
         metrics: opts.metrics,
     };
 }
+/** Cyclomatic complexity → severity: low 15–24, medium 25–39, high 40–59, critical ≥ 60. */
+export const CYCLOMATIC_THRESHOLDS = { low: 15, medium: 25, high: 40, critical: 60 };
 export function inferSeverity(complexity) {
-    if (complexity >= 20)
+    if (complexity >= CYCLOMATIC_THRESHOLDS.critical)
         return "critical";
-    if (complexity >= 10)
+    if (complexity >= CYCLOMATIC_THRESHOLDS.high)
         return "high";
-    if (complexity >= 5)
+    if (complexity >= CYCLOMATIC_THRESHOLDS.medium)
         return "medium";
+    if (complexity >= CYCLOMATIC_THRESHOLDS.low)
+        return "low";
     return "low";
 }

package/dist/analyzers/javascript.js

@@ -5,7 +5,7 @@
 import Parser from "tree-sitter";
 import JavaScript from "tree-sitter-javascript";
 import TypeScript from "tree-sitter-typescript";
-import { countComplexity, createDebtItem, effectiveLines, inferSeverity, } from "./base.js";
+import { countComplexity, createDebtItem, effectiveLines, findTodoFixmeHack, inferSeverity, } from "./base.js";
 const LANG_JS = "javascript";
 const LANG_TS = "typescript";
 const JS_EXT = /\.(?:js|jsx|mjs|cjs)$/i;
@@ -56,7 +56,7 @@ export const javascriptAnalyzer = {
                     hasDocumentation,
                 };
                 metrics.push(fileMetric);
-                if (complexity >= 5) {
+                if (complexity >= 15) {
                     debtItems.push(createDebtItem(path, "complexity", `High cyclomatic complexity (${complexity})`, `This file has ${complexity} decision points, which makes it harder to test and maintain.`, {
                         severity: inferSeverity(complexity),
                         confidence: 0.85,
@@ -73,6 +73,17 @@ export const javascriptAnalyzer = {
                 if (!hasDocumentation && lineCount > 50) {
                     debtItems.push(createDebtItem(path, "documentation", "Missing module-level documentation", "No JSDoc or file-level comment found. Document purpose and usage for maintainability.", { confidence: 0.7 }));
                 }
+                const todoMarkers = findTodoFixmeHack(content);
+                if (todoMarkers.length > 0) {
+                    const severity = todoMarkers.length >= 6 ? "high" : todoMarkers.length >= 3 ? "medium" : "low";
+                    const first = todoMarkers[0];
+                    debtItems.push(createDebtItem(path, "other", `${todoMarkers.length} TODO/FIXME/HACK/XXX marker(s)`, `Address or track these in issues: ${todoMarkers.map((m) => `${m.tag} L${m.line}`).join(", ")}.`, {
+                        line: first.line,
+                        severity,
+                        confidence: 0.75,
+                        metrics: { count: todoMarkers.length },
+                    }));
+                }
             }
             catch (e) {
                 errors.push({ file: path, message: e instanceof Error ? e.message : String(e) });

package/dist/analyzers/python.js

@@ -4,7 +4,7 @@
  */
 import Parser from "tree-sitter";
 import Python from "tree-sitter-python";
-import { countComplexity, createDebtItem, effectiveLines, inferSeverity, } from "./base.js";
+import { countComplexity, createDebtItem, effectiveLines, findTodoFixmeHack, inferSeverity, } from "./base.js";
 const PY_EXT = /\.py$/i;
 function getParser() {
     const P = new Parser();
@@ -44,7 +44,7 @@ export const pythonAnalyzer = {
                     hasDocumentation,
                 };
                 metrics.push(fileMetric);
-                if (complexity >= 5) {
+                if (complexity >= 15) {
                     debtItems.push(createDebtItem(path, "complexity", `High cyclomatic complexity (${complexity})`, `This module has ${complexity} decision points. Consider simplifying conditionals or extracting functions.`, {
                         severity: inferSeverity(complexity),
                         confidence: 0.85,
@@ -61,6 +61,17 @@ export const pythonAnalyzer = {
                 if (!hasDocumentation && lineCount > 30) {
                     debtItems.push(createDebtItem(path, "documentation", "Missing module docstring", "No module-level docstring found. Add a docstring describing the module's purpose.", { confidence: 0.7 }));
                 }
+                const todoMarkers = findTodoFixmeHack(content);
+                if (todoMarkers.length > 0) {
+                    const severity = todoMarkers.length >= 6 ? "high" : todoMarkers.length >= 3 ? "medium" : "low";
+                    const first = todoMarkers[0];
+                    debtItems.push(createDebtItem(path, "other", `${todoMarkers.length} TODO/FIXME/HACK/XXX marker(s)`, `Address or track these in issues: ${todoMarkers.map((m) => `${m.tag} L${m.line}`).join(", ")}.`, {
+                        line: first.line,
+                        severity,
+                        confidence: 0.75,
+                        metrics: { count: todoMarkers.length },
+                    }));
+                }
             }
             catch (e) {
                 errors.push({ file: path, message: e instanceof Error ? e.message : String(e) });

package/dist/cli.d.ts

@@ -2,4 +2,4 @@
 /**
  * CLI entry: colorful terminal output, progress bars, actionable insights.
  */
-export {};
+import "dotenv/config";

package/dist/cli.js

@@ -2,6 +2,7 @@
 /**
  * CLI entry: colorful terminal output, progress bars, actionable insights.
  */
+import "dotenv/config";
 import { Command } from "commander";
 import chalk from "chalk";
 import cliProgress from "cli-progress";
@@ -9,7 +10,7 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { getCleanlinessTier } from "./cleanliness-score.js";
 import { runAnalysis } from "./engine.js";
-import { assessFileCleanliness, assessOverallCleanliness, enrichDebtWithInsights, } from "./llm.js";
+import { assessFileCleanliness, assessOverallCleanliness, enrichDebtWithInsights, resolveLLMConfig, suggestNextSteps, } from "./llm.js";
 import { generateHtmlReport } from "./reports/html.js";
 import { generateJsonReport } from "./reports/json.js";
 import { generateMarkdownReport } from "./reports/markdown.js";
@@ -57,36 +58,47 @@ program
             }
         }
         if (useLlm) {
-            progress.update(3, { task: "LLM: per-file cleanliness..." });
-            const filesToAssess = run.fileMetrics
-                .sort((a, b) => (b.hotspotScore ?? 0) - (a.hotspotScore ?? 0))
-                .slice(0, 15);
-            for (const m of filesToAssess) {
-                const content = fileContents.get(m.file);
-                if (!content)
-                    continue;
-                const result = await assessFileCleanliness(m.file, content, m);
-                if (result) {
-                    const idx = run.fileMetrics.findIndex((x) => x.file === m.file);
-                    if (idx >= 0)
-                        run.fileMetrics[idx] = {
-                            ...run.fileMetrics[idx],
-                            llmAssessment: result.assessment,
-                            llmSuggestedCode: result.suggestedCode,
-                        };
-                }
+            const llmConfig = resolveLLMConfig();
+            if (!llmConfig) {
+                process.stderr.write(chalk.yellow("  No LLM API key found. Set one of: GEMINI_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY.\n" +
+                    "  Example: export GEMINI_API_KEY=your_key_here\n" +
+                    "  Skipping AI insights for this run.\n\n"));
             }
-            progress.update(4, { task: "LLM: debt item insights..." });
-            let debtItems = run.debtItems;
-            if (debtItems.length > 0) {
-                debtItems = await enrichDebtWithInsights(debtItems.slice(0, 25), fileContents);
-                const byId = new Map(debtItems.map((d) => [d.id, d]));
-                run.debtItems = run.debtItems.map((d) => byId.get(d.id) ?? d);
+            else {
+                progress.update(3, { task: "LLM: per-file cleanliness..." });
+                const allFilePaths = run.fileMetrics.map((m) => m.file);
+                const maxFiles = 80;
+                const filesToAssess = run.fileMetrics.slice(0, maxFiles);
+                for (const m of filesToAssess) {
+                    const content = fileContents.get(m.file);
+                    if (!content)
+                        continue;
+                    const result = await assessFileCleanliness(m.file, content, m, {}, { filePaths: allFilePaths });
+                    if (result) {
+                        const idx = run.fileMetrics.findIndex((x) => x.file === m.file);
+                        if (idx >= 0)
+                            run.fileMetrics[idx] = {
+                                ...run.fileMetrics[idx],
+                                llmAssessment: result.assessment,
+                                llmSuggestedCode: result.suggestedCode,
+                            };
+                    }
+                }
+                progress.update(4, { task: "LLM: debt item insights..." });
+                let debtItems = run.debtItems;
+                if (debtItems.length > 0) {
+                    debtItems = await enrichDebtWithInsights(debtItems.slice(0, 25), fileContents);
+                    const byId = new Map(debtItems.map((d) => [d.id, d]));
+                    run.debtItems = run.debtItems.map((d) => byId.get(d.id) ?? d);
+                }
+                progress.update(5, { task: "LLM: overall assessment..." });
+                const overall = await assessOverallCleanliness(run);
+                if (overall)
+                    run.llmOverallAssessment = overall;
+                const nextSteps = await suggestNextSteps(run);
+                if (nextSteps?.length)
+                    run.llmNextSteps = nextSteps;
             }
-            progress.update(5, { task: "LLM: overall assessment..." });
-            const overall = await assessOverallCleanliness(run);
-            if (overall)
-                run.llmOverallAssessment = overall;
         }
         progress.update(totalSteps, { task: "Done" });
         progress.stop();
@@ -120,6 +132,10 @@ program
         }
         else {
             printCliReport(run, opts.ci ?? false);
+            if (!run.llmOverallAssessment) {
+                process.stdout.write(chalk.dim("  To get AI insights, per-file optimization suggestions, and refactor recommendations:\n" +
+                    "  set GEMINI_API_KEY or OPENAI_API_KEY and run without --no-llm.\n\n"));
+            }
             if (opts.ci && getDebtScore(run) > 60)
                 process.exit(1);
         }
@@ -156,7 +172,8 @@ function printCliReport(run, ci) {
     if (run.debtTrend && run.debtTrend.length > 0) {
         process.stdout.write(`  Recent commits: ${chalk.cyan(String(run.debtTrend.length))}\n`);
     }
-    process.stdout.write(`  Debt score:     ${severityColor(score)} / 100\n\n`);
+    process.stdout.write(`  Debt score:     ${severityColor(score)} / 100\n`);
+    process.stdout.write(chalk.dim("  (weighted average of debt item severity × confidence, 0–100)\n\n"));
     const bySeverity = { critical: 0, high: 0, medium: 0, low: 0 };
     for (const d of debtItems) {
         bySeverity[d.severity]++;
@@ -206,6 +223,29 @@ function printCliReport(run, ci) {
         for (const e of errors.slice(0, 5)) {
             process.stdout.write(chalk.dim(`  ${e.file}: ${e.message}\n`));
         }
+        process.stdout.write("\n");
+    }
+    process.stdout.write(chalk.bold("  What to fix\n"));
+    process.stdout.write(chalk.dim("  " + "—".repeat(50) + "\n"));
+    const severityLabel = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+    const fixList = debtItems
+        .sort((a, b) => severityOrder(b.severity) - severityOrder(a.severity))
+        .slice(0, 12)
+        .map((d) => `  • [${severityLabel(d.severity)}] ${d.title} — ${d.file}${d.line != null ? `:${d.line}` : ""}`);
+    if (fixList.length > 0) {
+        fixList.forEach((line) => process.stdout.write(line + "\n"));
+    }
+    else {
+        process.stdout.write(chalk.dim("  No debt items. Keep it up.\n"));
+    }
+    process.stdout.write("\n");
+    if (run.llmNextSteps && run.llmNextSteps.length > 0) {
+        process.stdout.write(chalk.bold.cyan("  Recommended next steps (AI)\n"));
+        process.stdout.write(chalk.dim("  " + "—".repeat(50) + "\n"));
+        for (const step of run.llmNextSteps) {
+            process.stdout.write(chalk.cyan("  • ") + step + "\n");
+        }
+        process.stdout.write("\n");
     }
     process.stdout.write(chalk.dim("  Run with --format html -o report.html for the interactive dashboard.\n\n"));
 }

package/dist/llm.d.ts

@@ -19,10 +19,17 @@ export declare function resolveLLMConfig(config?: LLMConfig): {
     model: string;
 } | null;
 export declare function enrichDebtWithInsights(items: DebtItem[], fileContents: Map<string, string>, config?: LLMConfig): Promise<DebtItem[]>;
-/** Per-file: LLM assesses cleanliness and optionally suggests a concrete code simplification. */
-export declare function assessFileCleanliness(filePath: string, content: string, metrics: FileMetrics, config?: LLMConfig): Promise<{
+/** Context about the rest of the repo for cross-file optimization suggestions. */
+export interface RepoContext {
+    /** All analyzed file paths in this run (including the current file). */
+    filePaths: string[];
+}
+/** Per-file: LLM assesses cleanliness and suggests optimizations with cross-file context. */
+export declare function assessFileCleanliness(filePath: string, content: string, metrics: FileMetrics, config?: LLMConfig, repoContext?: RepoContext): Promise<{
     assessment: string;
     suggestedCode?: string;
 } | null>;
 /** Overall: LLM assesses the whole codebase cleanliness in a short paragraph. */
 export declare function assessOverallCleanliness(run: AnalysisRun, config?: LLMConfig): Promise<string | null>;
+/** LLM suggests 3–5 prioritized next steps (actionable bullets). */
+export declare function suggestNextSteps(run: AnalysisRun, config?: LLMConfig): Promise<string[] | null>;

package/dist/llm.js

@@ -169,17 +169,21 @@ Reply format: Short explanation first, then optionally a code block with the sug
     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 = {}) {
+/** Per-file: LLM assesses cleanliness and suggests optimizations with cross-file context. */
+export async function assessFileCleanliness(filePath, content, metrics, config = {}, repoContext) {
     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.
+    const otherFiles = repoContext?.filePaths?.filter((p) => p !== filePath).slice(0, 80) ?? [];
+    const repoContextBlock = otherFiles.length > 0
+        ? `\nRepository context (other files in this run): ${otherFiles.join(", ")}.\nWhen suggesting optimizations, you may reference other files (e.g. extract to a shared module, reuse from another file, or move code between files). Explain why each suggestion helps.\n`
+        : "";
+    const prompt = `You are a senior engineer assessing code cleanliness and possible optimizations for this file.
 
+1) In 1-3 sentences: how clean and maintainable is it, and one or two concrete improvements (or "Looks good" if fine). Explain why each improvement matters.
+2) If one specific optimization is possible (e.g. simplify a function, reduce nesting, extract a helper, or a cross-file refactor like moving code to a shared module), provide ONLY that refactored snippet in a markdown code block. Same language as the file. Briefly say why it helps. If no clear code change applies, omit the code block.
+${repoContextBlock}
 File: ${filePath}
 Metrics: complexity ${metrics.cyclomaticComplexity ?? "?"}, lines ${metrics.lineCount}, ${metrics.hasDocumentation ? "has docs" : "no module docs"}${metrics.hotspotScore != null ? `, hotspot ${metrics.hotspotScore.toFixed(2)}` : ""}.
 
@@ -188,10 +192,10 @@ Code:
 ${snippet}
 \`\`\`
 
-Reply: short assessment first, then optionally a code block with the suggested refactor. No preamble.`;
+Reply: short assessment first (with brief "why"), then optionally a code block with the suggested refactor. No preamble.`;
     const raw = await chat(prompt, {
         ...resolved,
-        maxTokens: config.maxTokens ?? 400,
+        maxTokens: config.maxTokens ?? 500,
     });
     if (!raw)
         return null;
@@ -225,3 +229,38 @@ In one short paragraph (3-5 sentences), assess overall cleanliness: main strengt
         maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS_OVERALL,
     });
 }
+/** LLM suggests 3–5 prioritized next steps (actionable bullets). */
+export async function suggestNextSteps(run, config = {}) {
+    const resolved = resolveLLMConfig(config);
+    if (!resolved)
+        return null;
+    const fileCount = run.fileMetrics.length;
+    const debtCount = run.debtItems.length;
+    const bySeverity = run.debtItems.reduce((acc, d) => {
+        acc[d.severity] = (acc[d.severity] ?? 0) + 1;
+        return acc;
+    }, {});
+    const severityOrd = (s) => ({ critical: 4, high: 3, medium: 2, low: 1 }[s] ?? 0);
+    const topItems = run.debtItems
+        .sort((a, b) => severityOrd(b.severity) - severityOrd(a.severity))
+        .slice(0, 15)
+        .map((d) => `${d.severity}: ${d.title} (${d.file}${d.line ? `:${d.line}` : ""})`);
+    const prompt = `You are a senior engineer. Given this technical debt summary, suggest 3–5 concrete, prioritized next steps the team should take to reduce debt. Be specific (files, types of fixes). Output ONLY a short bullet list: one action per line, starting each line with "- " or "• ". No preamble or explanation.
+
+Summary: ${fileCount} files, ${debtCount} debt items. By severity: ${JSON.stringify(bySeverity)}.
+Sample items: ${topItems.join("; ")}
+
+List 3–5 next steps:`;
+    const raw = await chat(prompt, {
+        ...resolved,
+        maxTokens: 300,
+    });
+    if (!raw)
+        return null;
+    const bullets = raw
+        .split(/\n/)
+        .map((s) => s.replace(/^[\s\-•*]+\s*/, "").trim())
+        .filter((s) => s.length > 0)
+        .slice(0, 5);
+    return bullets.length > 0 ? bullets : null;
+}

package/dist/reports/html.js

@@ -22,6 +22,7 @@ function buildHtml(run, title, darkMode) {
         debtItems: run.debtItems,
         debtTrend: run.debtTrend ?? [],
         llmOverallAssessment: run.llmOverallAssessment ?? null,
+        llmNextSteps: run.llmNextSteps ?? null,
         summary: {
             filesAnalyzed: run.fileMetrics.length,
             debtCount: run.debtItems.length,
@@ -261,6 +262,14 @@ function buildHtml(run, title, darkMode) {
       <p class="llm-overall-text">${escapeHtml(run.llmOverallAssessment)}</p>
     </div>
     ` : ""}
+    ${run.llmNextSteps?.length ? `
+    <div class="section llm-next-steps">
+      <h2>Recommended next steps (AI)</h2>
+      <ul>
+        ${run.llmNextSteps.map((s) => `<li>${escapeHtml(s)}</li>`).join("\n        ")}
+      </ul>
+    </div>
+    ` : ""}
 
     <div class="glossary">
       <h2>Understanding this report</h2>

package/dist/reports/json.js

@@ -14,6 +14,7 @@ export function generateJsonReport(run) {
         debtTrend: run.debtTrend,
         errors: run.errors,
         llmOverallAssessment: run.llmOverallAssessment ?? undefined,
+        llmNextSteps: run.llmNextSteps ?? undefined,
     };
     return JSON.stringify(payload, null, 2);
 }

package/dist/reports/markdown.js

@@ -60,5 +60,24 @@ export function generateMarkdownReport(run) {
         }
         lines.push("");
     }
+    if (run.debtItems.length > 0) {
+        lines.push("## What to fix");
+        lines.push("");
+        const top = run.debtItems
+            .sort((a, b) => ({ critical: 4, high: 3, medium: 2, low: 1 }[b.severity] ?? 0) - ({ critical: 4, high: 3, medium: 2, low: 1 }[a.severity] ?? 0))
+            .slice(0, 12);
+        for (const d of top) {
+            lines.push(`- **[${d.severity}]** ${d.title} — \`${d.file}${d.line != null ? `:${d.line}` : ""}\``);
+        }
+        lines.push("");
+    }
+    if (run.llmNextSteps?.length) {
+        lines.push("## Recommended next steps (AI)");
+        lines.push("");
+        for (const step of run.llmNextSteps) {
+            lines.push(`- ${step}`);
+        }
+        lines.push("");
+    }
     return lines.join("\n");
 }

package/dist/types.d.ts

@@ -88,6 +88,8 @@ export interface AnalysisRun {
     }>;
     /** LLM-generated overall codebase cleanliness assessment (when LLM attached) */
     llmOverallAssessment?: string;
+    /** LLM-generated prioritized next steps (when LLM attached) */
+    llmNextSteps?: string[];
 }
 /** Pluggable analyzer: given file paths and content, returns metrics + debt items */
 export interface IAnalyzer {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tech-debt-visualizer",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Language-agnostic CLI that analyzes repos and generates interactive technical debt visualizations with AI-powered insights",
   "type": "module",
   "main": "dist/index.js",
@@ -30,6 +30,7 @@
     "README.md"
   ],
   "dependencies": {
+    "dotenv": "^16.4.5",
     "chalk": "^5.3.0",
     "cli-progress": "^3.12.0",
     "commander": "^12.1.0",