tech-debt-visualizer 0.1.6 → 0.2.1

package/dist/cli.js

@@ -10,11 +10,13 @@ import { Command } from "commander";
 import chalk from "chalk";
 import cliProgress from "cli-progress";
 import { getCleanlinessTier } from "./cleanliness-score.js";
+import { getDebtScore } from "./debt-score.js";
 import { runAnalysis } from "./engine.js";
-import { assessFileCleanliness, assessOverallCleanliness, enrichDebtWithInsights, resolveLLMConfig, suggestNextSteps, } from "./llm.js";
+import { assessFileCleanliness, assessOverallCleanliness, resolveLLMConfig, } from "./llm.js";
 import { generateHtmlReport } from "./reports/html.js";
 import { generateJsonReport } from "./reports/json.js";
 import { generateMarkdownReport } from "./reports/markdown.js";
+import { SEVERITY_ORDER } from "./types.js";
 const program = new Command();
 program
     .name("tech-debt")
@@ -28,31 +30,36 @@ 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-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);
     const format = (opts.format ?? "cli");
     const useLlm = opts.llm !== false;
     const outputPath = opts.output ?? (format === "html" ? "tech-debt-report.html" : undefined);
-    const totalSteps = useLlm ? 6 : 4;
+    const llmConfigOverrides = {
+        apiKey: opts.llmKey,
+        baseURL: opts.llmEndpoint,
+        model: opts.llmModel,
+        ...(opts.llmMaxTokens != null && opts.llmMaxTokens > 0 ? { maxTokens: opts.llmMaxTokens } : {}),
+    };
     const progress = new cliProgress.SingleBar({
-        format: chalk.cyan(" {bar} ") + "| {task} | {value}/{total}",
+        format: chalk.cyan(" {bar} ") + "| {percentage}% | {value}/{total} | {task}",
         barCompleteChar: "█",
         barIncompleteChar: "░",
     }, cliProgress.Presets.shades_classic);
+    let run;
+    const fileContents = new Map();
     try {
         process.stderr.write(chalk.bold.blue("\n  Technical Debt Visualizer\n\n"));
-        progress.start(totalSteps, 0, { task: "Discovering files..." });
+        const discoverySteps = useLlm ? 2 : 4;
+        progress.start(discoverySteps, 0, { task: "Discovering files..." });
+        run = await runAnalysis({ repoPath, maxFiles: 1500, gitDays: 90 });
         progress.update(1, { task: "Discovering files..." });
-        const run = await runAnalysis({
-            repoPath,
-            maxFiles: 1500,
-            gitDays: 90,
-        });
         progress.update(2, { task: "Analyzing..." });
-        const fileContents = new Map();
         for (const f of run.fileMetrics.map((m) => m.file)) {
             try {
                 fileContents.set(f, await readFile(join(repoPath, f), "utf-8"));
@@ -61,54 +68,77 @@ program
                 // ignore
             }
         }
-        const llmConfigOverrides = { apiKey: opts.llmKey, model: opts.llmModel };
-        if (useLlm) {
+        if (!useLlm) {
+            progress.update(4, { task: "Done" });
+            progress.stop();
+        }
+        else {
+            progress.stop();
+            const maxFiles = 80;
+            const filesToAssess = run.fileMetrics.slice(0, maxFiles);
+            const totalSteps = 2 + filesToAssess.length + 1;
+            progress.start(totalSteps, 2, {
+                task: filesToAssess.length > 0 ? `LLM: file 0/${filesToAssess.length}` : "LLM: overall...",
+            });
             const llmConfig = resolveLLMConfig(llmConfigOverrides);
             if (!llmConfig) {
-                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" +
+                progress.update(totalSteps, { task: "Skipping LLM (no key)" });
+                progress.stop();
+                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 {
-                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);
+                run.llmAttempted = true;
                 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, config, { 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,
-                            };
+                const allFilePaths = run.fileMetrics.map((m) => m.file);
+                const FILE_BATCH_SIZE = 10;
+                for (let i = 0; i < filesToAssess.length; i += FILE_BATCH_SIZE) {
+                    const batch = filesToAssess.slice(i, i + FILE_BATCH_SIZE);
+                    const completedBefore = i;
+                    const results = await Promise.allSettled(batch.map((m) => {
+                        const content = fileContents.get(m.file);
+                        if (!content)
+                            return Promise.resolve(null);
+                        return assessFileCleanliness(m.file, content, m, config, { filePaths: allFilePaths });
+                    }));
+                    for (let j = 0; j < batch.length; j++) {
+                        const result = results[j];
+                        if (result?.status === "fulfilled" && result.value) {
+                            const m = batch[j];
+                            const idx = run.fileMetrics.findIndex((x) => x.file === m.file);
+                            if (idx >= 0)
+                                run.fileMetrics[idx] = {
+                                    ...run.fileMetrics[idx],
+                                    llmAssessment: result.value.assessment,
+                                    llmSuggestedCode: result.value.suggestedCode,
+                                    llmFileScore: result.value.fileScore,
+                                    llmSeverity: result.value.severity,
+                                    llmRawAssessment: result.value.raw,
+                                };
+                        }
                     }
+                    const completedFiles = Math.min(completedBefore + batch.length, filesToAssess.length);
+                    progress.update(2 + completedFiles, {
+                        task: `LLM: file ${completedFiles}/${filesToAssess.length}`,
+                    });
                 }
-                progress.update(4, { task: "LLM: debt item insights..." });
-                let debtItems = run.debtItems;
-                if (debtItems.length > 0) {
-                    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 overallStep = 2 + filesToAssess.length;
+                progress.update(overallStep, { task: "LLM: overall assessment..." });
                 const overall = await assessOverallCleanliness(run, config);
-                if (overall)
-                    run.llmOverallAssessment = overall;
-                const nextSteps = await suggestNextSteps(run, config);
-                if (nextSteps?.length)
-                    run.llmNextSteps = nextSteps;
+                if (overall) {
+                    run.llmOverallAssessment = overall.assessment;
+                    if (overall.score != null)
+                        run.llmOverallScore = overall.score;
+                    if (overall.severity)
+                        run.llmOverallSeverity = overall.severity;
+                    run.llmOverallRaw = overall.raw;
+                }
+                progress.update(totalSteps, { task: "Done" });
+                progress.stop();
             }
         }
-        progress.update(totalSteps, { task: "Done" });
-        progress.stop();
         if (format === "html" && outputPath) {
             await generateHtmlReport(run, { outputPath, title: "Technical Debt Report", darkMode: true });
             process.stdout.write(chalk.green(`\n  Report written to ${outputPath}\n\n`));
@@ -140,7 +170,12 @@ program
         else {
             printCliReport(run, opts.ci ?? false);
             if (!run.llmOverallAssessment) {
-                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 (run.llmAttempted) {
+                    process.stdout.write(chalk.dim("  LLM was used but returned no insights. Check [LLM] errors above or verify your API key.\n\n"));
+                }
+                else {
+                    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);
@@ -152,14 +187,6 @@ program
         process.exit(1);
     }
 });
-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));
-}
 function printCliReport(run, ci) {
     const { debtItems, fileMetrics, errors } = run;
     const score = getDebtScore(run);
@@ -198,7 +225,10 @@ function printCliReport(run, ci) {
     if (hotspots.length > 0) {
         process.stdout.write(chalk.bold("  Hotspot files (high churn + complexity)\n"));
         for (const h of hotspots) {
-            process.stdout.write(`  ${chalk.red("●")} ${h.file} ${chalk.dim(`(score ${(h.hotspotScore ?? 0).toFixed(2)})`)}\n`);
+            const hotspotInfo = `(score ${(h.hotspotScore ?? 0).toFixed(2)})`;
+            const llmInfo = h.llmFileScore != null ? ` LLM debt ${h.llmFileScore}/100` : "";
+            const llmSev = h.llmSeverity ? ` LLM severity ${h.llmSeverity}` : "";
+            process.stdout.write(`  ${chalk.red("●")} ${h.file} ${chalk.dim(hotspotInfo + llmInfo + llmSev)}\n`);
             if (h.llmAssessment)
                 process.stdout.write(chalk.dim(`    ${h.llmAssessment.replace(/\n/g, "\n    ")}\n`));
             if (h.llmSuggestedCode) {
@@ -217,7 +247,7 @@ function printCliReport(run, ci) {
         process.stdout.write(`  ${sev} ${d.title}\n`);
         process.stdout.write(chalk.dim(`    ${d.file}${d.line ? `:${d.line}` : ""}\n`));
         if (d.insight)
-            process.stdout.write(chalk.dim(`    ${d.insight.slice(0, 120)}${d.insight.length > 120 ? "…" : ""}\n`));
+            process.stdout.write(chalk.dim(`    ${d.insight.replace(/\n/g, "\n    ")}\n`));
         if (d.suggestedCode) {
             process.stdout.write(chalk.cyan("    Suggested refactor:\n"));
             process.stdout.write(chalk.dim(d.suggestedCode.split("\n").map((l) => "    " + l).join("\n") + "\n"));
@@ -245,18 +275,10 @@ function printCliReport(run, ci) {
         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"));
 }
 function severityOrder(s) {
-    return { critical: 4, high: 3, medium: 2, low: 1 }[s] ?? 0;
+    return SEVERITY_ORDER[s] ?? 0;
 }
 function chalkSeverity(s) {
     const map = {

package/dist/debt-score.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Technical debt score 0–100 (higher = more debt).
+ * When LLM is used, the overall score is taken from LLM only so it matches per-file and overall LLM scores.
+ */
+import type { AnalysisRun } from "./types.js";
+/**
+ * Debt score 0–100. Uses a single consistent source when LLM is available so overall and file scores match:
+ * - If LLM overall score is set: use it as-is.
+ * - Else if any file has LLM file score: use average of those.
+ * - Else: static score from debt items.
+ */
+export declare function getDebtScore(run: AnalysisRun): number;

package/dist/debt-score.js

@@ -0,0 +1,32 @@
+/**
+ * Technical debt score 0–100 (higher = more debt).
+ * When LLM is used, the overall score is taken from LLM only so it matches per-file and overall LLM scores.
+ */
+/** Compute static score from debt items (severity × confidence). Used when no LLM scores exist. */
+function getStaticDebtScore(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));
+}
+/**
+ * Debt score 0–100. Uses a single consistent source when LLM is available so overall and file scores match:
+ * - If LLM overall score is set: use it as-is.
+ * - Else if any file has LLM file score: use average of those.
+ * - Else: static score from debt items.
+ */
+export function getDebtScore(run) {
+    if (run.llmOverallScore != null) {
+        return Math.min(100, Math.max(0, Math.round(run.llmOverallScore)));
+    }
+    const fileScores = run.fileMetrics
+        .map((m) => m.llmFileScore)
+        .filter((s) => typeof s === "number");
+    if (fileScores.length > 0) {
+        const avg = fileScores.reduce((a, b) => a + b, 0) / fileScores.length;
+        return Math.min(100, Math.max(0, Math.round(avg)));
+    }
+    return getStaticDebtScore(run);
+}

package/dist/llm.d.ts

@@ -1,35 +1,49 @@
 /**
  * LLM integration: debt explanations, per-file cleanliness, and overall assessment.
  * Supports OpenAI, OpenRouter (OpenAI-compatible), and Google Gemini.
+ *
+ * No time limits: requests run until the API returns. Truncation is only from token limits.
+ * Override with LLMConfig.maxTokens or --llm-max-tokens. Defaults are generous to avoid cut-off:
+ * - Debt item insights (explainDebtItem): config.maxTokens ?? DEFAULT_MAX_TOKENS (2048)
+ * - Per-file assessment (assessFileCleanliness): config.maxTokens ?? DEFAULT_MAX_TOKENS_FILE (8192)
+ * - Overall assessment (assessOverallCleanliness): config.maxTokens ?? DEFAULT_MAX_TOKENS_OVERALL (8192)
+ * - enrichDebtWithInsights: passes config.maxTokens ?? DEFAULT_MAX_TOKENS to each item
  */
-import type { DebtItem, FileMetrics } from "./types.js";
-import type { AnalysisRun } from "./types.js";
+import type { AnalysisRun, DebtItem, FileMetrics, LlmFileSeverity } from "./types.js";
 export interface LLMConfig {
     apiKey?: string;
     baseURL?: string;
     model?: string;
+    /** Overrides default token limits for LLM responses (used where applicable). */
     maxTokens?: number;
 }
 export type LLMProvider = "openai" | "openrouter" | "gemini";
-/** Resolve provider and auth from config + env. OpenRouter and Gemini take precedence when their keys are set. */
+/** 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;
     baseURL: string;
     model: string;
 } | null;
-export declare function enrichDebtWithInsights(items: DebtItem[], fileContents: Map<string, string>, config?: LLMConfig): Promise<DebtItem[]>;
+/** Optional progress callback: (completedBatches, totalBatches) after each batch. */
+export declare function enrichDebtWithInsights(items: DebtItem[], fileContents: Map<string, string>, config?: LLMConfig, onProgress?: (completed: number, total: number) => void): Promise<DebtItem[]>;
 /** 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. */
+/** Per-file: LLM gives a short summary, a 0–100 debt score, and optionally one refactor. One request per file; call in parallel from CLI. */
 export declare function assessFileCleanliness(filePath: string, content: string, metrics: FileMetrics, config?: LLMConfig, repoContext?: RepoContext): Promise<{
     assessment: string;
     suggestedCode?: string;
+    fileScore?: number;
+    severity?: LlmFileSeverity;
+    raw: string;
+} | null>;
+/** Overall: LLM assesses the whole codebase and optionally a 0–100 debt score. */
+export declare function assessOverallCleanliness(run: AnalysisRun, config?: LLMConfig): Promise<{
+    assessment: string;
+    score?: number;
+    severity?: LlmFileSeverity;
+    raw: 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>;