tech-debt-visualizer 0.1.0

package/dist/cli.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+/**
+ * CLI entry: colorful terminal output, progress bars, actionable insights.
+ */
+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, } from "./llm.js";
+import { generateHtmlReport } from "./reports/html.js";
+import { generateJsonReport } from "./reports/json.js";
+import { generateMarkdownReport } from "./reports/markdown.js";
+const program = new Command();
+program
+    .name("tech-debt")
+    .description("Analyze repositories and visualize technical debt with AI-powered insights")
+    .version("0.1.0");
+program
+    .command("analyze")
+    .description("Analyze a repository and output report")
+    .argument("[path]", "Repository path", ".")
+    .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("--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 progress = new cliProgress.SingleBar({
+        format: chalk.cyan(" {bar} ") + "| {task} | {value}/{total}",
+        barCompleteChar: "█",
+        barIncompleteChar: "░",
+    }, cliProgress.Presets.shades_classic);
+    try {
+        process.stderr.write(chalk.bold.blue("\n  Technical Debt Visualizer\n\n"));
+        progress.start(totalSteps, 0, { task: "Discovering files..." });
+        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"));
+            }
+            catch {
+                // ignore
+            }
+        }
+        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,
+                        };
+                }
+            }
+            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;
+        }
+        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`));
+        }
+        else if (format === "json") {
+            const out = outputPath ?? undefined;
+            const json = generateJsonReport(run);
+            if (out) {
+                const { writeFile } = await import("node:fs/promises");
+                await writeFile(out, json, "utf-8");
+                process.stdout.write(chalk.green(`\n  JSON written to ${out}\n\n`));
+            }
+            else {
+                process.stdout.write(json + "\n");
+            }
+        }
+        else if (format === "markdown") {
+            const out = outputPath ?? undefined;
+            const md = generateMarkdownReport(run);
+            if (out) {
+                const { writeFile } = await import("node:fs/promises");
+                await writeFile(out, md, "utf-8");
+                process.stdout.write(chalk.green(`\n  Markdown written to ${out}\n\n`));
+            }
+            else {
+                process.stdout.write(md + "\n");
+            }
+        }
+        else {
+            printCliReport(run, opts.ci ?? false);
+            if (opts.ci && getDebtScore(run) > 60)
+                process.exit(1);
+        }
+    }
+    catch (e) {
+        progress.stop();
+        process.stderr.write(chalk.red("\n  Error: " + (e instanceof Error ? e.message : String(e)) + "\n\n"));
+        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);
+    const cleanliness = getCleanlinessTier(score);
+    process.stdout.write("\n");
+    process.stdout.write(chalk.bold.dim("  Technical Debt Cleanliness Score\n"));
+    process.stdout.write("  " + "—".repeat(52) + "\n");
+    const tierColor = cleanlinessTierColor(cleanliness.tier);
+    process.stdout.write(tierColor(`  ${cleanliness.label} (${cleanliness.tier}/5)\n`));
+    process.stdout.write(tierColor(`  ${cleanliness.description}\n`));
+    process.stdout.write("  " + "—".repeat(52) + "\n\n");
+    process.stdout.write(chalk.bold("  Summary\n"));
+    process.stdout.write(chalk.dim("  " + "—".repeat(50) + "\n"));
+    process.stdout.write(`  Files analyzed: ${chalk.cyan(String(fileMetrics.length))}\n`);
+    process.stdout.write(`  Debt items:     ${chalk.yellow(String(debtItems.length))}\n`);
+    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`);
+    const bySeverity = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const d of debtItems) {
+        bySeverity[d.severity]++;
+    }
+    process.stdout.write(chalk.bold("  By severity\n"));
+    process.stdout.write(`  Critical: ${chalk.red(String(bySeverity.critical))}  High: ${chalk.yellow(String(bySeverity.high))}  Medium: ${chalk.hex("#b8860b")(String(bySeverity.medium))}  Low: ${chalk.gray(String(bySeverity.low))}\n\n`);
+    if (run.llmOverallAssessment) {
+        process.stdout.write(chalk.bold("  LLM overall assessment\n"));
+        process.stdout.write(chalk.dim("  " + "—".repeat(50) + "\n"));
+        process.stdout.write(chalk.cyan("  " + run.llmOverallAssessment.replace(/\n/g, "\n  ") + "\n\n"));
+    }
+    const hotspots = fileMetrics
+        .filter((m) => (m.hotspotScore ?? 0) > 0.3)
+        .sort((a, b) => (b.hotspotScore ?? 0) - (a.hotspotScore ?? 0))
+        .slice(0, 5);
+    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`);
+            if (h.llmAssessment)
+                process.stdout.write(chalk.dim(`    ${h.llmAssessment.replace(/\n/g, "\n    ")}\n`));
+            if (h.llmSuggestedCode) {
+                process.stdout.write(chalk.cyan("    Suggested refactor:\n"));
+                process.stdout.write(chalk.dim(h.llmSuggestedCode.split("\n").map((l) => "    " + l).join("\n") + "\n"));
+            }
+        }
+        process.stdout.write("\n");
+    }
+    process.stdout.write(chalk.bold("  Top debt items\n"));
+    const top = debtItems
+        .sort((a, b) => severityOrder(b.severity) - severityOrder(a.severity))
+        .slice(0, 10);
+    for (const d of top) {
+        const sev = chalkSeverity(d.severity);
+        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`));
+        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"));
+        }
+        process.stdout.write("\n");
+    }
+    if (errors.length > 0 && !ci) {
+        process.stdout.write(chalk.bold.yellow("  Parse errors\n"));
+        for (const e of errors.slice(0, 5)) {
+            process.stdout.write(chalk.dim(`  ${e.file}: ${e.message}\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;
+}
+function chalkSeverity(s) {
+    const map = {
+        critical: chalk.red("◆ Critical"),
+        high: chalk.yellow("◇ High"),
+        medium: chalk.hex("#b8860b")("▸ Medium"),
+        low: chalk.gray("▹ Low"),
+    };
+    return map[s] ?? s;
+}
+function severityColor(score) {
+    if (score >= 70)
+        return chalk.red(String(score));
+    if (score >= 40)
+        return chalk.yellow(String(score));
+    return chalk.green(String(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;
+    }
+}
+program.parse();

package/dist/discover.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Discover source files in a repository by extension and optional globs.
+ */
+import type { IAnalyzer } from "./types.js";
+export declare function discoverFiles(repoPath: string, analyzers: IAnalyzer[], options?: {
+    maxFiles?: number;
+}): Promise<Map<string, string>>;

package/dist/discover.js

@@ -0,0 +1,70 @@
+/**
+ * Discover source files in a repository by extension and optional globs.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+const DEFAULT_IGNORE = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "out",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "vendor",
+    "coverage",
+    ".next",
+    ".nuxt",
+    ".cache",
+]);
+export async function discoverFiles(repoPath, analyzers, options = {}) {
+    const { maxFiles = 2000 } = options;
+    const extensions = new Set();
+    for (const a of analyzers) {
+        for (const lang of a.languages) {
+            if (lang === "javascript" || lang === "typescript") {
+                extensions.add(".js").add(".jsx").add(".ts").add(".tsx").add(".mjs").add(".cjs");
+            }
+            else if (lang === "python") {
+                extensions.add(".py");
+            }
+        }
+    }
+    const result = new Map();
+    await walk(repoPath, repoPath, extensions, result, maxFiles);
+    return result;
+}
+async function walk(root, dir, extensions, result, maxFiles) {
+    if (result.size >= maxFiles)
+        return;
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const ent of entries) {
+        if (result.size >= maxFiles)
+            break;
+        const full = join(dir, ent.name);
+        const rel = full.slice(root.length).replace(/^[/\\]/, "");
+        if (ent.isDirectory()) {
+            if (DEFAULT_IGNORE.has(ent.name) || ent.name.startsWith("."))
+                continue;
+            await walk(root, full, extensions, result, maxFiles);
+            continue;
+        }
+        const ext = ent.name.includes(".") ? "." + ent.name.split(".").pop().toLowerCase() : "";
+        if (!extensions.has(ext))
+            continue;
+        try {
+            const content = await readFile(full, "utf-8");
+            result.set(rel, content);
+        }
+        catch {
+            // skip binary or unreadable
+        }
+    }
+}

package/dist/engine.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Analysis engine: discover files, run pluggable analyzers, merge git stats,
+ * compute hotspots and confidence, and produce a single AnalysisRun.
+ */
+import type { AnalysisRun } from "./types.js";
+export interface EngineOptions {
+    repoPath: string;
+    analyzerNames?: string[];
+    maxFiles?: number;
+    gitDays?: number;
+}
+export declare function runAnalysis(options: EngineOptions): Promise<AnalysisRun>;

package/dist/engine.js

@@ -0,0 +1,76 @@
+/**
+ * Analysis engine: discover files, run pluggable analyzers, merge git stats,
+ * compute hotspots and confidence, and produce a single AnalysisRun.
+ */
+import { computeHotspotScore, getDebtTrend, getGitStats, } from "./git-analyzer.js";
+import { discoverFiles } from "./discover.js";
+import { analyzers } from "./analyzers/index.js";
+export async function runAnalysis(options) {
+    const { repoPath, analyzerNames, maxFiles = 1500, gitDays = 90, } = options;
+    const selectedAnalyzers = analyzerNames?.length
+        ? analyzers.filter((a) => analyzerNames.includes(a.name))
+        : analyzers;
+    const files = await discoverFiles(repoPath, selectedAnalyzers, { maxFiles });
+    if (files.size === 0) {
+        return {
+            repoPath,
+            startedAt: new Date().toISOString(),
+            analyzers: selectedAnalyzers.map((a) => a.name),
+            fileMetrics: [],
+            debtItems: [],
+            errors: [{ file: "", message: "No matching source files found." }],
+        };
+    }
+    const [gitStats, debtTrend] = await Promise.all([
+        getGitStats(repoPath, { days: gitDays }),
+        getDebtTrend(repoPath, 15),
+    ]);
+    const allMetrics = [];
+    const allDebt = [];
+    const allErrors = [];
+    for (const analyzer of selectedAnalyzers) {
+        const toAnalyze = new Map();
+        for (const [path, content] of files) {
+            if (analyzer.canAnalyze(path))
+                toAnalyze.set(path, content);
+        }
+        if (toAnalyze.size === 0)
+            continue;
+        const result = await analyzer.analyze(toAnalyze, { repoPath });
+        allMetrics.push(...result.metrics);
+        allDebt.push(...result.debtItems);
+        allErrors.push(...result.errors);
+    }
+    enrichWithGit(gitStats, allMetrics);
+    const run = {
+        repoPath,
+        startedAt: new Date().toISOString(),
+        completedAt: new Date().toISOString(),
+        analyzers: selectedAnalyzers.map((a) => a.name),
+        fileMetrics: allMetrics,
+        debtItems: allDebt,
+        debtTrend,
+        errors: allErrors,
+    };
+    return run;
+}
+function enrichWithGit(gitStats, metrics) {
+    let maxChange = 0, maxChurn = 0, maxComplexity = 0;
+    for (const m of metrics) {
+        const g = gitStats.byFile.get(m.file);
+        if (g) {
+            m.changeCount = g.commits;
+            m.churn = g.churn;
+            maxChange = Math.max(maxChange, g.commits);
+            maxChurn = Math.max(maxChurn, g.churn);
+        }
+        const c = m.cyclomaticComplexity ?? 0;
+        maxComplexity = Math.max(maxComplexity, c);
+    }
+    for (const m of metrics) {
+        const change = m.changeCount ?? 0;
+        const churn = m.churn ?? 0;
+        const complexity = m.cyclomaticComplexity ?? 0;
+        m.hotspotScore = computeHotspotScore(change, churn, complexity, maxChange, maxChurn, maxComplexity);
+    }
+}

package/dist/git-analyzer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Git history analyzer: churn, hotspots, and change patterns.
+ * Used to enrich file metrics with change frequency and debt trends.
+ */
+export interface GitStats {
+    byFile: Map<string, {
+        commits: number;
+        churn: number;
+        lastChange: string;
+    }>;
+    recentCommits: number;
+    defaultBranch?: string;
+}
+export declare function getGitStats(repoPath: string, options?: {
+    days?: number;
+    maxFiles?: number;
+}): Promise<GitStats>;
+/**
+ * Compute hotspot score: files that change often AND are complex are riskier.
+ * Normalize so we can combine with static metrics.
+ */
+export declare function computeHotspotScore(changeCount: number, churn: number, complexity: number, maxChange: number, maxChurn: number, maxComplexity: number): number;
+export declare function getDebtTrend(repoPath: string, sampleCommits?: number): Promise<Array<{
+    commit: string;
+    date: string;
+    score: number;
+}>>;

package/dist/git-analyzer.js

@@ -0,0 +1,133 @@
+/**
+ * Git history analyzer: churn, hotspots, and change patterns.
+ * Used to enrich file metrics with change frequency and debt trends.
+ */
+import { simpleGit } from "simple-git";
+const DEFAULT_DAYS = 90;
+const DEFAULT_MAX_FILES = 5000;
+export async function getGitStats(repoPath, options = {}) {
+    const { days = DEFAULT_DAYS, maxFiles = DEFAULT_MAX_FILES } = options;
+    const git = simpleGit(repoPath);
+    const since = new Date();
+    since.setDate(since.getDate() - days);
+    const byFile = new Map();
+    try {
+        // Get file names only (repeated per commit) so we can count commits per file
+        const nameOnly = await git.raw([
+            "log",
+            `--since=${since.toISOString()}`,
+            "--name-only",
+            "--format=",
+        ]);
+        const fileCommits = new Map();
+        for (const line of nameOnly.split("\n")) {
+            const f = line.trim().replace(/^\.\//, "");
+            if (!f || f.includes("=>"))
+                continue;
+            fileCommits.set(f, (fileCommits.get(f) ?? 0) + 1);
+        }
+        // Get churn (additions + deletions) per file via --numstat
+        const numstat = await git.raw([
+            "log",
+            `--since=${since.toISOString()}`,
+            "--numstat",
+            "--format=",
+        ]);
+        const fileChurn = new Map();
+        const fileLastChange = new Map();
+        const logWithDate = await git.log({ "--since": since.toISOString() });
+        for (const entry of logWithDate.all) {
+            const names = await getFilesInCommit(git, entry.hash);
+            for (const f of names) {
+                const norm = f.replace(/^\.\//, "");
+                fileLastChange.set(norm, entry.date);
+            }
+        }
+        for (const line of numstat.split("\n")) {
+            const parts = line.trim().split(/\s+/);
+            if (parts.length >= 3) {
+                const add = parseInt(parts[0], 10) || 0;
+                const del = parseInt(parts[1], 10) || 0;
+                const path = parts.slice(2).join(" ").replace(/^\.\//, "");
+                if (path && !path.includes("=>"))
+                    fileChurn.set(path, (fileChurn.get(path) ?? 0) + add + del);
+            }
+        }
+        const sorted = [...fileCommits.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, maxFiles);
+        for (const [file, commits] of sorted) {
+            byFile.set(file, {
+                commits,
+                churn: fileChurn.get(file) ?? commits,
+                lastChange: fileLastChange.get(file) ?? "",
+            });
+        }
+    }
+    catch {
+        // Not a git repo or no history
+    }
+    let defaultBranch;
+    try {
+        defaultBranch = (await git.branch()).current;
+    }
+    catch {
+        // ignore
+    }
+    let recentCommits = 0;
+    try {
+        recentCommits = (await git.log({ "--since": since.toISOString() })).total;
+    }
+    catch {
+        // ignore
+    }
+    return {
+        byFile,
+        recentCommits,
+        defaultBranch,
+    };
+}
+async function getFilesInCommit(git, hash) {
+    try {
+        const diff = await git.show([hash, "--name-only", "--format="]);
+        return diff.split("\n").filter(Boolean).map((f) => f.trim());
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Compute hotspot score: files that change often AND are complex are riskier.
+ * Normalize so we can combine with static metrics.
+ */
+export function computeHotspotScore(changeCount, churn, complexity, maxChange, maxChurn, maxComplexity) {
+    if (maxChange === 0 && maxChurn === 0 && maxComplexity === 0)
+        return 0;
+    const changeNorm = maxChange > 0 ? changeCount / maxChange : 0;
+    const churnNorm = maxChurn > 0 ? churn / maxChurn : 0;
+    const complexityNorm = maxComplexity > 0 ? complexity / maxComplexity : 0;
+    // Weight: complexity and churn matter most
+    return (complexityNorm * 0.5 + (changeNorm + churnNorm) * 0.25);
+}
+export async function getDebtTrend(repoPath, sampleCommits = 20) {
+    const git = simpleGit(repoPath);
+    const result = [];
+    try {
+        const log = await git.log({ max: sampleCommits });
+        for (const entry of log.all) {
+            // Placeholder: real trend would run analysis at each commit (expensive).
+            // We use a simple heuristic: more files changed = potential debt churn.
+            const names = await getFilesInCommit(git, entry.hash);
+            const score = Math.min(100, names.length * 2 + 10);
+            result.push({
+                commit: entry.hash.slice(0, 7),
+                date: entry.date,
+                score,
+            });
+        }
+    }
+    catch {
+        // ignore
+    }
+    return result.reverse();
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { runAnalysis } from "./engine.js";
+export { analyzers } from "./analyzers/index.js";
+export type { AnalysisRun, DebtItem, FileMetrics, IAnalyzer, CliOptions, ReportOptions, } from "./types.js";
+export { generateHtmlReport } from "./reports/html.js";
+export { generateJsonReport } from "./reports/json.js";
+export { generateMarkdownReport } from "./reports/markdown.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { runAnalysis } from "./engine.js";
+export { analyzers } from "./analyzers/index.js";
+export { generateHtmlReport } from "./reports/html.js";
+export { generateJsonReport } from "./reports/json.js";
+export { generateMarkdownReport } from "./reports/markdown.js";

package/dist/llm.d.ts

@@ -0,0 +1,28 @@
+/**
+ * LLM integration: debt explanations, per-file cleanliness, and overall assessment.
+ * Supports OpenAI, OpenRouter (OpenAI-compatible), and Google Gemini.
+ */
+import type { DebtItem, FileMetrics } from "./types.js";
+import type { AnalysisRun } from "./types.js";
+export interface LLMConfig {
+    apiKey?: string;
+    baseURL?: string;
+    model?: string;
+    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. */
+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[]>;
+/** 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<{
+    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>;