tech-debt-visualizer 0.2.18 → 0.2.20

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} (${Math.round(score)}/100)\n`));
+    process.stdout.write(tierColor(`  ${cleanliness.label} (${cleanliness.tier} out of 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,7 @@ 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(`  Score:         ${tierColor(`${cleanliness.tier} out of 5`)}\n\n`);
     const bySeverity = { critical: 0, high: 0, medium: 0, low: 0 };
     for (const d of debtItems) {
         bySeverity[d.severity]++;

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,
@@ -330,7 +330,7 @@ Top risk files (by hotspot): ${topFiles.join(", ")}
 Output only:
 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 100" */
+  gap: 0.4rem; /* space between number and "out of 5" */
   margin-bottom: 0.5rem;
 }
 

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,9 +46,9 @@ function adjustHexBrightness(hex, factor) {
 }
 function buildHtml(run, title, darkMode, css, script) {
     const theme = darkMode ? "dark" : "light";
-    const debtScore = getDebtScore(run);
-    const scoreNum = Math.round(Math.max(0, Math.min(100, debtScore)));
-    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,
@@ -60,7 +60,7 @@ 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,
@@ -78,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)} — ${scoreNum}/100 ${escapeHtml(cleanliness.label)}" />
+  <meta property="og:title" content="${escapeHtml(title)} — ${cleanliness.tier} out of 5 ${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)} — ${scoreNum}/100" />
+  <meta name="twitter:title" content="${escapeHtml(title)} — ${cleanliness.tier} out of 5" />
   <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>
@@ -95,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 ${scoreNum} of 100">
-        <span class="dashboard-score-value">${scoreNum}</span>
-        <span class="dashboard-score-of">/ 100</span>
+      <div class="dashboard-score tier-${cleanliness.tier}" aria-label="Score ${cleanliness.tier} out of 5">
+        <span class="dashboard-score-value">${cleanliness.tier}</span>
+        <span class="dashboard-score-of"> out of 5</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>
@@ -114,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">${scoreNum}</span>
-              <span class="score-of">of 100</span>
+              <span class="score-num">${cleanliness.tier}</span>
+              <span class="score-of"> out of 5</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.18",
+  "version": "0.2.20",
   "description": "Language-agnostic CLI that analyzes repos and generates interactive technical debt visualizations with AI-powered insights",
   "type": "module",
   "main": "dist/index.js",