tech-debt-visualizer 0.1.2 → 0.1.3

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/package.json

@@ -1,11 +1,12 @@
 {
   "name": "tech-debt-visualizer",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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",