tech-debt-visualizer 0.1.2 → 0.1.4

package/README.md

@@ -79,6 +79,9 @@ Requires **Node 18+**.
 | `-f, --format` | `cli` (default), `html`, `json`, or `markdown` |
 | `-o, --output` | Output path (e.g. `report.html` for HTML) |
 | `--no-llm` | Skip all LLM calls (no API key needed) |
+| `--llm` | Enable LLM (default). Use with `--llm-key` and/or `--llm-model` |
+| `--llm-key <key>` | API key (overrides env / `.env`) |
+| `--llm-model <model>` | Model name (e.g. `gemini-1.5-flash`, `gpt-4o-mini`) |
 | `--ci` | Terse output; exit code 1 if debt score &gt; 60 |
 
 Examples:
@@ -87,6 +90,10 @@ Examples:
 node dist/cli.js analyze . -f html -o report.html
 node dist/cli.js analyze ./src -f json -o debt.json
 node dist/cli.js analyze . --ci
+# With LLM key and model on the command line:
+node dist/cli.js analyze . --llm-key YOUR_GEMINI_KEY --llm-model gemini-1.5-flash
+# Or use a .env file in the current directory (GEMINI_API_KEY=...)
+node dist/cli.js analyze .
 ```
 
 ---
@@ -95,6 +102,8 @@ node dist/cli.js analyze . --ci
 
 The tool can call an LLM to get **explanations** and **concrete code refactor suggestions**. You only need one provider; the first one with a key wins.
 
+**Ways to pass the API key:** (1) Put `GEMINI_API_KEY=your_key` (or `OPENAI_API_KEY`, etc.) in a **`.env` file** in the directory you run the command from (current working directory). (2) **Export** in the same shell: `export GEMINI_API_KEY=your_key`. (3) **CLI flag**: `--llm-key your_key`. You can also set **model** via `--llm-model gemini-1.5-flash` (or another model name).
+
 | Provider | Env var(s) | Optional env |
 |----------|------------|---------------|
 | **OpenRouter** | `OPENROUTER_API_KEY` | `OPENROUTER_MODEL` (default: `google/gemini-2.0-flash-001`) |

package/dist/cli.d.ts

@@ -1,5 +1,2 @@
 #!/usr/bin/env node
-/**
- * CLI entry: colorful terminal output, progress bars, actionable insights.
- */
-import "dotenv/config";
+export {};

package/dist/cli.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 /**
  * CLI entry: colorful terminal output, progress bars, actionable insights.
+ * Loads .env from cwd first; supports --llm-key and --llm-model.
  */
-import "dotenv/config";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadEnv } from "./load-env.js";
 import { Command } from "commander";
 import chalk from "chalk";
 import cliProgress from "cli-progress";
-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, resolveLLMConfig, suggestNextSteps, } from "./llm.js";
@@ -18,7 +19,7 @@ const program = new Command();
 program
     .name("tech-debt")
     .description("Analyze repositories and visualize technical debt with AI-powered insights")
-    .version("0.1.0");
+    .version("0.1.2");
 program
     .command("analyze")
     .description("Analyze a repository and output report")
@@ -26,6 +27,9 @@ program
     .option("-o, --output <path>", "Output file path (default: report.html or stdout for CLI)")
     .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("--ci", "CI mode: minimal output, exit with non-zero if debt score is high")
     .action(async (path, opts) => {
     const repoPath = join(process.cwd(), path);
@@ -57,11 +61,13 @@ program
                 // ignore
             }
         }
+        const llmConfigOverrides = { apiKey: opts.llmKey, model: opts.llmModel };
         if (useLlm) {
-            const llmConfig = resolveLLMConfig();
+            const llmConfig = resolveLLMConfig(llmConfigOverrides);
             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" +
+                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" +
                     "  Skipping AI insights for this run.\n\n"));
             }
             else {
@@ -69,11 +75,12 @@ program
                 const allFilePaths = run.fileMetrics.map((m) => m.file);
                 const maxFiles = 80;
                 const filesToAssess = run.fileMetrics.slice(0, maxFiles);
+                const config = { ...llmConfigOverrides };
                 for (const m of filesToAssess) {
                     const content = fileContents.get(m.file);
                     if (!content)
                         continue;
-                    const result = await assessFileCleanliness(m.file, content, m, {}, { filePaths: allFilePaths });
+                    const result = await assessFileCleanliness(m.file, content, m, config, { filePaths: allFilePaths });
                     if (result) {
                         const idx = run.fileMetrics.findIndex((x) => x.file === m.file);
                         if (idx >= 0)
@@ -87,15 +94,15 @@ program
                 progress.update(4, { task: "LLM: debt item insights..." });
                 let debtItems = run.debtItems;
                 if (debtItems.length > 0) {
-                    debtItems = await enrichDebtWithInsights(debtItems.slice(0, 25), fileContents);
+                    debtItems = await enrichDebtWithInsights(debtItems.slice(0, 25), fileContents, config);
                     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);
+                const overall = await assessOverallCleanliness(run, config);
                 if (overall)
                     run.llmOverallAssessment = overall;
-                const nextSteps = await suggestNextSteps(run);
+                const nextSteps = await suggestNextSteps(run, config);
                 if (nextSteps?.length)
                     run.llmNextSteps = nextSteps;
             }
@@ -133,8 +140,7 @@ 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"));
+                process.stdout.write(chalk.dim("  To get AI insights: set GEMINI_API_KEY (or OPENAI_API_KEY) or use --llm-key <key>. Run without --no-llm.\n\n"));
             }
             if (opts.ci && getDebtScore(run) > 60)
                 process.exit(1);
@@ -270,12 +276,19 @@ function severityColor(score) {
 }
 function cleanlinessTierColor(tier) {
     switch (tier) {
-        case 5: return chalk.green.bold;
-        case 4: return chalk.cyan.bold;
-        case 3: return chalk.yellow.bold;
-        case 2: return chalk.hex("#f97316").bold;
-        case 1: return chalk.red.bold;
-        default: return chalk.white.bold;
+        case 5:
+            return chalk.green.bold;
+        case 4:
+            return chalk.cyan.bold;
+        case 3:
+            return chalk.yellow.bold;
+        case 2:
+            return chalk.hex("#f97316").bold;
+        case 1:
+            return chalk.red.bold;
+        default:
+            return chalk.white.bold;
     }
 }
-program.parse();
+// Load .env from cwd first, then run the CLI
+loadEnv().then(() => program.parse());

package/dist/load-env.d.ts

@@ -0,0 +1 @@
+export declare function loadEnv(): Promise<void>;

package/dist/load-env.js

@@ -0,0 +1,32 @@
+/**
+ * Load .env from current working directory. Uses dotenv if installed, else parses manually.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+export async function loadEnv() {
+    const envPath = join(process.cwd(), ".env");
+    try {
+        const dotenv = await import("dotenv");
+        dotenv.config({ path: envPath });
+        return;
+    }
+    catch {
+        // dotenv not installed
+    }
+    if (!existsSync(envPath))
+        return;
+    const content = readFileSync(envPath, "utf-8");
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = trimmed.slice(0, eq).trim();
+        let value = trimmed.slice(eq + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))
+            value = value.slice(1, -1);
+        process.env[key] = value;
+    }
+}

package/dist/reports/html.js

@@ -17,10 +17,11 @@ function buildHtml(run, title, darkMode) {
     const theme = darkMode ? "dark" : "light";
     const debtScore = getDebtScore(run);
     const cleanliness = getCleanlinessTier(debtScore);
+    const hasLlm = !!(run.llmOverallAssessment || (run.llmNextSteps && run.llmNextSteps.length));
     const dataJson = JSON.stringify({
         fileMetrics: run.fileMetrics,
         debtItems: run.debtItems,
-        debtTrend: run.debtTrend ?? [],
+        hasLlm,
         llmOverallAssessment: run.llmOverallAssessment ?? null,
         llmNextSteps: run.llmNextSteps ?? null,
         summary: {
@@ -40,7 +41,6 @@ function buildHtml(run, title, darkMode) {
   <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;
@@ -72,34 +72,34 @@ function buildHtml(run, title, darkMode) {
       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;
+    .no-llm-banner {
+      width: 100%;
       background: var(--surface);
-      border: 1px solid var(--border);
+      border-bottom: 2px solid var(--border);
+      padding: 0.75rem 1.5rem;
+      text-align: center;
     }
-    .hero-grade {
-      width: 140px;
-      flex-shrink: 0;
-      display: flex;
-      flex-direction: column;
-      align-items: center;
-      justify-content: center;
-      padding: 2rem 1.5rem;
+    .no-llm-banner .no-llm-cta { font-size: 1rem; font-weight: 600; color: var(--text); margin: 0; }
+    .hero-caption { font-size: 0.7rem; text-transform: uppercase; letter-spacing: 0.1em; color: var(--text-muted); margin: 0 0 1rem; font-weight: 600; text-align: center; }
+    .hero {
+      text-align: center;
+      margin-bottom: 2rem;
+    }
+    .score-badge {
+      display: inline-block;
+      width: 120px;
+      padding: 1rem 0.5rem 0.85rem;
       background: var(--tier-bg);
-      border-right: 1px solid var(--border);
+      color: var(--tier-fg);
+      border: 2px solid var(--tier-fg);
+      border-radius: 8px;
+      margin-bottom: 0.75rem;
     }
-    .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; }
+    .score-badge .num { display: block; font-size: 3rem; font-weight: 700; line-height: 1; letter-spacing: -0.03em; text-align: center; }
+    .score-badge .of { display: block; font-size: 0.75rem; font-weight: 600; text-align: center; text-transform: uppercase; letter-spacing: 0.08em; margin-top: 0.25rem; opacity: 0.9; }
+    .hero .score-label { font-size: 1.25rem; font-weight: 700; color: var(--text); margin: 0 0 0.25rem; letter-spacing: -0.01em; }
+    .hero .score-desc { font-size: 0.9rem; color: var(--text-muted); line-height: 1.5; margin: 0 0 0.5rem; max-width: 380px; margin-left: auto; margin-right: auto; }
+    .hero .report-meta { font-size: 0.8rem; color: var(--text-muted); }
     .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; }
@@ -138,28 +138,29 @@ function buildHtml(run, title, darkMode) {
     #treemap {
       display: flex;
       flex-wrap: wrap;
-      gap: 4px;
-      min-height: 280px;
+      gap: 8px;
+      min-height: 200px;
+      padding: 0.5rem 0;
     }
     .treemap-cell {
-      border-radius: 6px;
+      border-radius: 8px;
       display: flex;
       align-items: flex-end;
-      padding: 6px 8px;
-      font-size: 0.7rem;
+      min-width: 72px;
+      padding: 8px 10px;
+      font-size: 0.72rem;
       cursor: pointer;
-      transition: transform 0.15s, filter 0.15s;
+      transition: transform 0.15s, filter 0.15s, box-shadow 0.15s;
       overflow: hidden;
       text-overflow: ellipsis;
       white-space: nowrap;
     }
-    .treemap-cell:hover { transform: scale(1.03); filter: brightness(1.1); }
+    .treemap-cell:hover { transform: scale(1.04); filter: brightness(1.1); box-shadow: 0 4px 12px rgba(0,0,0,0.2); }
     .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);
@@ -206,23 +207,15 @@ function buildHtml(run, title, darkMode) {
     #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; }
+    .llm-overall { border-left: 4px solid var(--accent); }
+    .llm-overall h2 { color: var(--accent); }
+    .llm-overall .llm-overall-text { margin: 0; color: var(--text); line-height: 1.6; font-size: 1rem; }
+    .llm-next-steps h2 { color: var(--accent); }
+    .llm-next-steps ul { margin: 0; padding-left: 1.25rem; 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; }
@@ -235,18 +228,21 @@ function buildHtml(run, title, darkMode) {
   </style>
 </head>
 <body>
+  ${!hasLlm ? `
+  <div class="no-llm-banner">
+    <p class="no-llm-cta">Analysis run without LLM — for better 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="hero-grade">
+      <div class="score-badge">
         <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 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 class="summary-cards">
@@ -271,25 +267,9 @@ function buildHtml(run, title, darkMode) {
     </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>
+      <h2>Files by debt</h2>
+      <p class="section-desc">Size = complexity + churn. Color = worst severity. 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>
@@ -300,12 +280,6 @@ function buildHtml(run, title, darkMode) {
       <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>
@@ -355,38 +329,13 @@ function buildHtml(run, title, darkMode) {
       cell.className = 'treemap-cell';
       cell.dataset.severity = severity;
       cell.style.flex = String(score / maxScore * 100) + ' 1 80px';
-      cell.style.minWidth = '80px';
+      cell.style.minWidth = '72px';
       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('');

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "tech-debt-visualizer",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Language-agnostic CLI that analyzes repos and generates interactive technical debt visualizations with AI-powered insights",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "tech-debt": "dist/cli.js"
+    "tech-debt": "dist/cli.js",
+    "tech-debt-visualizer": "dist/cli.js"
   },
   "scripts": {
     "build": "tsc",