tech-debt-visualizer 0.2.17 → 0.2.19

package/dist/cleanliness-score.d.ts

@@ -1,11 +1,11 @@
 /**
- * Technical Debt Cleanliness Score: map debt score (0-100) to one of five tiers.
- * Lower debt score = higher tier (cleaner code).
+ * Technical Debt Cleanliness Score: map cleanliness score (0-100) to one of five tiers.
+ * Cleanliness: 0 = most debt, 100 = least debt. Tier 1 = worst, Tier 5 = best.
  */
 export interface CleanlinessTier {
     tier: 1 | 2 | 3 | 4 | 5;
     label: string;
     description: string;
 }
-/** Debt score 0-100 (higher = worse). Returns tier 1-5 (1 = worst, 5 = best). */
-export declare function getCleanlinessTier(debtScore: number): CleanlinessTier;
+/** Cleanliness score 0-100 (0 = worst, 100 = best). Returns tier 1-5: 1 = 0-20, 2 = 21-40, 3 = 41-60, 4 = 61-80, 5 = 81-100. */
+export declare function getCleanlinessTier(cleanlinessScore: number): CleanlinessTier;

package/dist/cleanliness-score.js

@@ -1,6 +1,6 @@
 /**
- * Technical Debt Cleanliness Score: map debt score (0-100) to one of five tiers.
- * Lower debt score = higher tier (cleaner code).
+ * Technical Debt Cleanliness Score: map cleanliness score (0-100) to one of five tiers.
+ * Cleanliness: 0 = most debt, 100 = least debt. Tier 1 = worst, Tier 5 = best.
  */
 const TIERS = [
     { tier: 1, label: "Prompt Roulette Champion", description: "100% vibes, 0% understanding" },
@@ -9,16 +9,16 @@ const TIERS = [
     { tier: 4, label: "Power Tool User", description: "AI is the nail gun" },
     { tier: 5, label: "Pure Coder", description: "Hand-crafted artisanal code, no AI needed" },
 ];
-/** Debt score 0-100 (higher = worse). Returns tier 1-5 (1 = worst, 5 = best). */
-export function getCleanlinessTier(debtScore) {
-    const clamped = Math.max(0, Math.min(100, Math.round(debtScore)));
+/** Cleanliness score 0-100 (0 = worst, 100 = best). Returns tier 1-5: 1 = 0-20, 2 = 21-40, 3 = 41-60, 4 = 61-80, 5 = 81-100. */
+export function getCleanlinessTier(cleanlinessScore) {
+    const clamped = Math.max(0, Math.min(100, Math.round(cleanlinessScore)));
     if (clamped <= 20)
-        return TIERS[4]; // 5/5
+        return TIERS[0]; // tier 1
     if (clamped <= 40)
-        return TIERS[3]; // 4/5
+        return TIERS[1]; // tier 2
     if (clamped <= 60)
-        return TIERS[2]; // 3/5
+        return TIERS[2]; // tier 3
     if (clamped <= 80)
-        return TIERS[1]; // 2/5
-    return TIERS[0]; // 1/5
+        return TIERS[3]; // tier 4
+    return TIERS[4]; // tier 5
 }

package/dist/cli.js

@@ -10,7 +10,7 @@ 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 { getCleanlinessScore, getDebtScore } from "./debt-score.js";
 import { runAnalysis } from "./engine.js";
 import { assessFileCleanliness, assessOverallCleanliness, resolveLLMConfig, } from "./llm.js";
 import { generateHtmlReport } from "./reports/html.js";
@@ -113,7 +113,7 @@ program
                                     ...run.fileMetrics[idx],
                                     llmAssessment: result.value.assessment,
                                     llmSuggestedCode: result.value.suggestedCode,
-                                    llmFileScore: result.value.fileScore,
+                                    llmFileScore: result.value.fileScore != null ? 100 - result.value.fileScore : undefined,
                                     llmSeverity: result.value.severity,
                                     llmRawAssessment: result.value.raw,
                                 };
@@ -130,7 +130,7 @@ program
                 if (overall) {
                     run.llmOverallAssessment = overall.assessment;
                     if (overall.score != null)
-                        run.llmOverallScore = overall.score;
+                        run.llmOverallScore = 100 - overall.score;
                     if (overall.severity)
                         run.llmOverallSeverity = overall.severity;
                     run.llmOverallRaw = overall.raw;
@@ -189,13 +189,13 @@ program
 });
 function printCliReport(run, ci) {
     const { debtItems, fileMetrics, errors } = run;
-    const score = getDebtScore(run);
-    const cleanliness = getCleanlinessTier(score);
+    const cleanlinessScore = getCleanlinessScore(run);
+    const cleanliness = getCleanlinessTier(cleanlinessScore);
     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.label} (${Math.round(cleanlinessScore)}/100, tier ${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"));
@@ -205,8 +205,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`);
-    process.stdout.write(chalk.dim("  (weighted average of debt item severity × confidence, 0–100)\n\n"));
+    process.stdout.write(`  Cleanliness:    ${cleanlinessColor(cleanlinessScore)} / 100 (tier ${cleanliness.tier}/5)\n`);
+    process.stdout.write(chalk.dim("  0 = most debt, 100 = least debt\n\n"));
     const bySeverity = { critical: 0, high: 0, medium: 0, low: 0 };
     for (const d of debtItems) {
         bySeverity[d.severity]++;
@@ -296,6 +296,14 @@ function severityColor(score) {
         return chalk.yellow(String(score));
     return chalk.green(String(score));
 }
+function cleanlinessColor(cleanlinessScore) {
+    const n = Math.round(cleanlinessScore);
+    if (n >= 70)
+        return chalk.green(String(n));
+    if (n >= 40)
+        return chalk.yellow(String(n));
+    return chalk.red(String(n));
+}
 function cleanlinessTierColor(tier) {
     switch (tier) {
         case 5:

package/dist/debt-score.d.ts

@@ -4,9 +4,9 @@
  */
 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.
+ * Debt score 0–100 (higher = more debt). Stored and computed internally; for display use getCleanlinessScore.
+ * When LLM is used, we store debt = 100 - llm_cleanliness so that this still returns "debt".
  */
 export declare function getDebtScore(run: AnalysisRun): number;
+/** Cleanliness score 0–100 (0 = most debt, 100 = least debt). Use this for display and tier. */
+export declare function getCleanlinessScore(run: AnalysisRun): number;

package/dist/debt-score.js

@@ -12,10 +12,8 @@ function getStaticDebtScore(run) {
     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.
+ * Debt score 0–100 (higher = more debt). Stored and computed internally; for display use getCleanlinessScore.
+ * When LLM is used, we store debt = 100 - llm_cleanliness so that this still returns "debt".
  */
 export function getDebtScore(run) {
     if (run.llmOverallScore != null) {
@@ -30,3 +28,7 @@ export function getDebtScore(run) {
     }
     return getStaticDebtScore(run);
 }
+/** Cleanliness score 0–100 (0 = most debt, 100 = least debt). Use this for display and tier. */
+export function getCleanlinessScore(run) {
+    return 100 - getDebtScore(run);
+}

package/dist/llm.js

@@ -292,7 +292,7 @@ ${snippet}
 Output only:
 1. A two- to four-sentence summary of the issues (how clean/maintainable, main concerns). No code block unless absolutely necessary to demonstrate.
 2. On the next line write only one word: critical, high, medium, low, or none (this file's technical debt severity; none = no significant debt).
-3. On the line after that write only a number 0-100 (100 = most technical debt).
+3. On the line after that write only a number 0-100 (0 = most debt, 100 = least debt / cleanest).
 No preamble.`;
     const raw = await chat(prompt, {
         ...resolved,
@@ -318,16 +318,19 @@ export async function assessOverallCleanliness(run, config = {}) {
     const debtCount = run.debtItems.length;
     const criticalHigh = run.debtItems.filter((d) => d.severity === "critical" || d.severity === "high").length;
     const hotspots = run.fileMetrics.filter((m) => (m.hotspotScore ?? 0) > 0.3).length;
+    const allFiles = run.fileMetrics.map((m) => m.file);
     const topFiles = run.fileMetrics
         .sort((a, b) => (b.hotspotScore ?? 0) - (a.hotspotScore ?? 0))
         .slice(0, 12)
         .map((m) => m.file);
-    const prompt = `Codebase summary: ${fileCount} files, ${debtCount} debt items (${criticalHigh} critical/high), ${hotspots} hotspots. Top risk files: ${topFiles.join(", ")}
+    const prompt = `Codebase summary: ${fileCount} files, ${debtCount} debt items (${criticalHigh} critical/high), ${hotspots} hotspots.
+All files in this codebase: ${allFiles.join(", ")}
+Top risk files (by hotspot): ${topFiles.join(", ")}
 
 Output only:
-1. A two- to four-sentence summary of the main issues (strengths, concerns, single most important improvement). No code block unless absolutely necessary to demonstrate.
+1. A single paragraph of 7–10 sentences that gives full context for the whole codebase. Cover ALL files: briefly note which files or areas are in good shape, which have issues, and how they fit together. Include strengths, main concerns, and the single most important improvement. Write for someone who needs to understand the entire codebase, not just the problematic parts. No code block unless absolutely necessary.
 2. On the next line write only one word: critical, high, medium, low, or none (overall codebase technical debt severity).
-3. On the line after that write only a number 0-100 (100 = most debt).
+3. On the line after that write only a number 0-100 (0 = most debt, 100 = least debt / cleanest).
 No preamble.`;
     const raw = await chat(prompt, {
         ...resolved,

package/dist/reports/assets/report.css

@@ -506,7 +506,7 @@ body.dashboard-page {
   display: flex;
   align-items: baseline;
   justify-content: center;
-  gap: 0.4rem; /* space between number and "of 5" */
+  gap: 0.4rem; /* space between number and "of 100" */
   margin-bottom: 0.5rem;
 }
 
@@ -584,18 +584,18 @@ body.dashboard-page {
 
 .panel-score-pop .score-num {
   font-family: "Inter", sans-serif;
-  font-size: 2.5rem;
+  font-size: 3.25rem;
   font-weight: 800;
   line-height: 1;
   background: linear-gradient(180deg, var(--accent-orange) 0%, var(--accent-red) 100%);
   -webkit-background-clip: text;
   -webkit-text-fill-color: transparent;
   background-clip: text;
-  filter: drop-shadow(0 0 16px rgba(255, 107, 53, 0.3));
+  filter: drop-shadow(0 0 20px rgba(255, 107, 53, 0.35));
 }
 
 .panel-score-pop .score-of {
-  font-size: 1rem;
+  font-size: 1.35rem;
   font-weight: 700;
   color: var(--text-muted);
 }
@@ -603,24 +603,24 @@ body.dashboard-page {
 .panel-score-pop .score-label {
   display: inline-block;
   background: linear-gradient(135deg, var(--accent-orange), var(--accent-red));
-  padding: 0.25rem 0.65rem;
+  padding: 0.45rem 1.1rem;
   border-radius: 50px;
   font-family: "Inter", sans-serif;
-  font-size: 0.7rem;
+  font-size: 1rem;
   font-weight: 700;
   letter-spacing: 0.5px;
   text-transform: uppercase;
-  box-shadow: 0 4px 12px rgba(255, 107, 53, 0.3);
-  margin-bottom: 0.2rem;
+  box-shadow: 0 6px 18px rgba(255, 107, 53, 0.35);
+  margin-bottom: 0.35rem;
   -webkit-text-fill-color: initial;
   color: #fff;
 }
 
 .panel-score-pop .score-desc {
-  font-size: 0.75rem;
+  font-size: 0.9rem;
   color: var(--text-muted);
   font-style: italic;
-  margin-bottom: 0.25rem;
+  margin-bottom: 0.35rem;
 }
 
 .panel-score-pop .score-stats {

package/dist/reports/html.js

@@ -2,7 +2,7 @@ import { readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getCleanlinessTier } from "../cleanliness-score.js";
-import { getDebtScore } from "../debt-score.js";
+import { getCleanlinessScore } from "../debt-score.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ASSETS_DIR = join(__dirname, "assets");
 export async function generateHtmlReport(run, options) {
@@ -46,8 +46,9 @@ function adjustHexBrightness(hex, factor) {
 }
 function buildHtml(run, title, darkMode, css, script) {
     const theme = darkMode ? "dark" : "light";
-    const debtScore = getDebtScore(run);
-    const cleanliness = getCleanlinessTier(debtScore);
+    const cleanlinessScore = getCleanlinessScore(run);
+    const scoreNum = Math.round(Math.max(0, Math.min(100, cleanlinessScore)));
+    const cleanliness = getCleanlinessTier(cleanlinessScore);
     const hasLlm = !!(run.llmOverallAssessment || run.llmOverallRaw);
     const dataJson = JSON.stringify({
         fileMetrics: run.fileMetrics,
@@ -59,7 +60,8 @@ function buildHtml(run, title, darkMode, css, script) {
         summary: {
             filesAnalyzed: run.fileMetrics.length,
             debtCount: run.debtItems.length,
-            debtScore,
+            debtScore: 100 - cleanlinessScore,
+            cleanlinessScore: scoreNum,
             cleanlinessTier: cleanliness.tier,
             cleanlinessLabel: cleanliness.label,
             cleanlinessDescription: cleanliness.description,
@@ -76,11 +78,11 @@ function buildHtml(run, title, darkMode, css, script) {
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>${escapeHtml(title)}</title>
-  <meta property="og:title" content="${escapeHtml(title)} — ${cleanliness.tier}/5 ${escapeHtml(cleanliness.label)}" />
+  <meta property="og:title" content="${escapeHtml(title)} — ${scoreNum}/100 ${escapeHtml(cleanliness.label)}" />
   <meta property="og:description" content="${escapeHtml(cleanliness.description)}" />
   <meta property="og:type" content="website" />
   <meta name="twitter:card" content="summary" />
-  <meta name="twitter:title" content="${escapeHtml(title)} — ${cleanliness.tier}/5" />
+  <meta name="twitter:title" content="${escapeHtml(title)} — ${scoreNum}/100" />
   <meta name="twitter:description" content="${escapeHtml(cleanliness.label)}: ${escapeHtml(cleanliness.description)}" />
   <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
   <style>${css}</style>
@@ -93,9 +95,9 @@ function buildHtml(run, title, darkMode, css, script) {
       <span class="dashboard-meta">${escapeHtml(run.repoPath)}</span>
     </div>
     <div class="dashboard-header-right">
-      <div class="dashboard-score tier-${cleanliness.tier}" aria-label="Score ${cleanliness.tier} of 5">
-        <span class="dashboard-score-value">${cleanliness.tier}</span>
-        <span class="dashboard-score-of">/ 5</span>
+      <div class="dashboard-score tier-${cleanliness.tier}" aria-label="Score ${scoreNum} of 100">
+        <span class="dashboard-score-value">${scoreNum}</span>
+        <span class="dashboard-score-of">/ 100</span>
         <span class="dashboard-score-label">${escapeHtml(cleanliness.label)}</span>
       </div>
       <button type="button" class="btn-ai-prompts btn-ai-prompts-header" id="btnAiPrompts">AI cleanup prompts</button>
@@ -112,8 +114,8 @@ function buildHtml(run, title, darkMode, css, script) {
           </div>
           <div class="panel-body panel-body-score">
             <div class="score-numeric">
-              <span class="score-num">${cleanliness.tier}</span>
-              <span class="score-of">of 5</span>
+              <span class="score-num">${scoreNum}</span>
+              <span class="score-of">of 100</span>
             </div>
             <p class="score-label">${escapeHtml(cleanliness.label)}</p>
             <p class="score-desc">${escapeHtml(cleanliness.description)}</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tech-debt-visualizer",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "description": "Language-agnostic CLI that analyzes repos and generates interactive technical debt visualizations with AI-powered insights",
   "type": "module",
   "main": "dist/index.js",