tech-debt-visualizer 0.1.0

package/LICENSE

@@ -0,0 +1,26 @@
+Technical Debt Visualizer
+Copyright (c) 2025. All rights reserved.
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program. If not, see <https://www.gnu.org/licenses/>.
+
+---
+
+DUAL LICENSING
+
+This project is offered under the GNU GPL v3 (above) for open-source use. If you
+need to use this software in a proprietary or commercial context without the
+obligations of the GPL (e.g., without disclosing source code or licensing
+derivative works under the GPL), a separate commercial license is available
+from the copyright holder. Contact the copyright holder for terms.
+
+Full text of GPL-3.0: https://www.gnu.org/licenses/gpl-3.0.html

package/README.md

@@ -0,0 +1,166 @@
+# Technical Debt Visualizer
+
+Analyze a repo and get a **cleanliness score**, **debt breakdown**, and optional **AI explanations and refactor suggestions**—in the terminal or as an interactive HTML report.
+
+![Node 18+](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)
+![Languages](https://img.shields.io/badge/languages-JS%20%7C%20TS%20%7C%20Python-green?style=flat-square)
+![License](https://img.shields.io/badge/license-GPL--3.0-blue?style=flat-square)
+
+---
+
+## Quick start
+
+```bash
+git clone <this-repo>
+cd tech-debt-visualizer
+npm install && npm run build
+node dist/cli.js analyze . --format cli
+```
+
+To try the **HTML dashboard**:  
+`node dist/cli.js analyze . --format html -o report.html` then open `report.html`.
+
+To use **AI insights** (explanations + optional code refactors): set `GEMINI_API_KEY` or `OPENAI_API_KEY` and run the same commands without `--no-llm`.
+
+---
+
+## How it works
+
+The tool runs a fixed pipeline so you know exactly what you’re getting.
+
+1. **Discover files**  
+   Walks the repo (respecting common ignores like `node_modules`, `.git`, `dist`) and collects source files by extension: `.js`, `.ts`, `.jsx`, `.tsx`, `.py`, etc.
+
+2. **Run language analyzers**  
+   Pluggable analyzers (today: JavaScript/TypeScript and Python) parse each file with **tree-sitter**, then:
+   - Count **cyclomatic complexity** (if/else, loops, switch, ternaries, `&&`/`||`).
+   - Count effective lines and check for **module-level docs** (JSDoc, docstrings).
+   - Emit **debt items** (e.g. “High cyclomatic complexity”, “Missing documentation”, “Large file”) with severity and confidence.
+
+3. **Enrich with git**  
+   Uses `git log` (e.g. last 90 days) to compute per-file **churn** and **commit count**. Combines that with complexity into a **hotspot score**: files that change often and are complex are treated as higher risk. A simple **debt trend** over recent commits is also derived (heuristic, not full historical analysis).
+
+4. **Score and tier**  
+   A single **debt score** (0–100) is computed from severity and confidence of all debt items. That score is mapped to a **Cleanliness tier** (1–5), e.g. “Thoughtful Prompter (3/5)” or “Pure Coder (5/5)”, shown at the top of the CLI and report.
+
+5. **Optional LLM pass**  
+   If an API key is set and you don’t use `--no-llm`, the tool:
+   - Asks the LLM to assess **per-file cleanliness** for the top ~15 hotspot files (and optionally suggest a **concrete code refactor** in a code block).
+   - Asks the LLM to explain **each debt item** (why it matters, what to do) and optionally suggest a **simplified/refactored code snippet**.
+   - Asks the LLM for one **overall codebase assessment** (a short paragraph).
+
+   Responses are parsed: prose goes into insights/assessments; any markdown code block is stored as **suggested refactor** and shown in CLI and HTML.
+
+6. **Output**  
+   Results are printed in the terminal (CLI) and/or written as **HTML** (treemap, trend chart, drill-down), **JSON**, or **Markdown** for CI or tooling.
+
+So: **static metrics + git → score & tier → optional LLM explanations and code suggestions → your chosen output format.**
+
+---
+
+## Install & run
+
+| How you run it | Command |
+|----------------|--------|
+| **From this repo** | `node dist/cli.js analyze [path]` (after `npm run build`) |
+| **Global (after publish)** | `npm install -g tech-debt-visualizer` then `tech-debt analyze [path]` |
+| **No install (after publish)** | `npx tech-debt-visualizer analyze [path]` |
+
+Requires **Node 18+**.
+
+---
+
+## Options
+
+| Option | Meaning |
+|--------|--------|
+| `-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) |
+| `--ci` | Terse output; exit code 1 if debt score &gt; 60 |
+
+Examples:
+
+```bash
+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
+```
+
+---
+
+## LLM (optional)
+
+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.
+
+| Provider | Env var(s) | Optional env |
+|----------|------------|---------------|
+| **OpenRouter** | `OPENROUTER_API_KEY` | `OPENROUTER_MODEL` (default: `google/gemini-2.0-flash-001`) |
+| **Gemini** | `GEMINI_API_KEY` or `GOOGLE_GENAI_API_KEY` | `GEMINI_MODEL` (default: `gemini-1.5-flash`) |
+| **OpenAI** | `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` | `OPENAI_BASE_URL`, `OPENAI_MODEL` (default: `gpt-4o-mini`) |
+
+With a key set, the CLI and HTML report will include:
+
+- **Overall assessment** — One short paragraph on the codebase.
+- **Per-file** — For hotspot files: short assessment and, when the LLM suggests one, a **suggested refactor** code block.
+- **Per debt item** — Why it matters, what to do, and when applicable a **suggested refactor** code block (parsed from the LLM response).
+
+Use `--no-llm` to run with no API calls.
+
+---
+
+## What we measure
+
+- **Cyclomatic complexity** — Decision points in the AST (if/for/while/switch/ternary/&&/||). Higher values suggest harder testing and refactors.
+- **Documentation** — Presence of module-level JSDoc or docstrings.
+- **Hotspots** — Files with high git churn *and* high complexity (riskiest to change).
+- **Debt trend** — Simple heuristic over recent commits (files touched); not a full historical debt metric.
+- **Cleanliness tier** — Score 0–100 mapped to a 1–5 label (e.g. “Pure Coder (5/5)” for low debt).
+
+---
+
+## Contributing
+
+We’d love **issues** and **contributions**.
+Please read **[CONTRIBUTING.md](CONTRIBUTING.md)** before sending a pull request.
+
+- **Bugs or confusing behavior?** Open an issue and describe what you ran and what you expected.
+- **Feature ideas?** Open an issue with a short use case; we’re happy to discuss.
+- **Want to add a language?** Implement the `IAnalyzer` interface in `src/analyzers/` (see `javascript.ts` / `python.ts`), register it in `src/analyzers/index.ts`, and add the right file extensions in `src/discover.ts`. PRs welcome.
+- **Code or docs?** Open a PR. You must agree to our **[Contributor License Agreement (CLA)](CLA.md)** before we can merge; the PR template includes a checkbox for this.
+
+---
+
+## Repo layout
+
+```
+src/
+  cli.ts           # Entrypoint, progress, output
+  engine.ts       # Runs discovery → analyzers → git → optional LLM
+  discover.ts     # File discovery by extension
+  git-analyzer.ts # Churn, hotspots, trend from git log
+  llm.ts          # LLM calls (OpenAI/OpenRouter/Gemini), prompts, code-block parsing
+  cleanliness-score.ts  # Score → tier (1–5)
+  types.ts        # DebtItem, FileMetrics, AnalysisRun, IAnalyzer
+  analyzers/      # Per-language: tree-sitter parse, complexity, debt items
+  reports/        # HTML, JSON, Markdown
+```
+
+---
+
+## Publishing (maintainers)
+
+To publish this package to npm: see **[docs/PUBLISHING.md](docs/PUBLISHING.md)** for step-by-step instructions (login, build, publish, scoped name if needed).
+
+## License
+
+**Dual licensing.**
+
+- **GPL-3.0 (open source):** You may use, modify, and distribute this software under the [GNU General Public License v3](https://www.gnu.org/licenses/gpl-3.0.html). You must comply with the GPL (e.g., disclose source for derivatives, same license).
+- **Commercial license:** If you need to use this in proprietary or commercial software without GPL obligations, a separate commercial license is available from the copyright holder. Contact the copyright holder for terms.
+
+See [LICENSE](LICENSE) for the GPL-3.0 text and dual-licensing note.
+
+---
+
+*This project is an independent initiative and is not affiliated with, endorsed by, or operated by any formed legal entity.*

package/dist/analyzers/base.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Base utilities for AST-based analyzers: complexity from tree-sitter trees,
+ * and shared file discovery.
+ */
+import Parser from "tree-sitter";
+import type { DebtCategory, DebtItem, Severity } from "../types.js";
+/** Recursively count complexity from tree (cyclomatic: decision points only). */
+export declare function countComplexity(node: Parser.SyntaxNode): number;
+/** Count lines in source (excluding empty and comment-only). */
+export declare function effectiveLines(source: string): number;
+export declare function createDebtItem(file: string, category: DebtCategory, title: string, description: string, opts?: {
+    line?: number;
+    endLine?: number;
+    severity?: Severity;
+    confidence?: number;
+    metrics?: Record<string, number | string>;
+}): DebtItem;
+export declare function inferSeverity(complexity: number): Severity;

package/dist/analyzers/base.js

@@ -0,0 +1,68 @@
+/**
+ * Base utilities for AST-based analyzers: complexity from tree-sitter trees,
+ * and shared file discovery.
+ */
+/** Tree-sitter node types that add cyclomatic complexity (decision points only). */
+const COMPLEXITY_NODE_TYPES = new Set([
+    "if_statement",
+    "else_clause",
+    "elif_clause",
+    "for_statement",
+    "while_statement",
+    "switch_statement",
+    "case_clause",
+    "catch_clause",
+    "except_clause",
+    "conditional_expression",
+]);
+/** Recursively count complexity from tree (cyclomatic: decision points only). */
+export function countComplexity(node) {
+    let n = 0;
+    const type = node.type;
+    if (COMPLEXITY_NODE_TYPES.has(type))
+        n++;
+    if (type === "binary_expression") {
+        const text = node.text;
+        if (text.includes("&&") || text.includes("||"))
+            n++;
+    }
+    for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (child)
+            n += countComplexity(child);
+    }
+    return n;
+}
+/** Count lines in source (excluding empty and comment-only). */
+export function effectiveLines(source) {
+    return source
+        .split("\n")
+        .filter((line) => {
+        const t = line.trim();
+        return t.length > 0 && !t.startsWith("//") && !t.startsWith("#") && !t.startsWith("/*") && !t.startsWith("*");
+    }).length;
+}
+export function createDebtItem(file, category, title, description, opts = {}) {
+    const id = `${file}:${opts.line ?? 0}:${category}:${title.slice(0, 30)}`.replace(/\s/g, "_");
+    return {
+        id,
+        file,
+        line: opts.line,
+        endLine: opts.endLine,
+        category,
+        severity: opts.severity ?? "medium",
+        title,
+        description,
+        confidence: opts.confidence ?? 0.8,
+        metrics: opts.metrics,
+    };
+}
+export function inferSeverity(complexity) {
+    if (complexity >= 20)
+        return "critical";
+    if (complexity >= 10)
+        return "high";
+    if (complexity >= 5)
+        return "medium";
+    return "low";
+}

package/dist/analyzers/index.d.ts

@@ -0,0 +1,4 @@
+import type { IAnalyzer } from "../types.js";
+export declare const analyzers: IAnalyzer[];
+export { javascriptAnalyzer } from "./javascript.js";
+export { pythonAnalyzer } from "./python.js";

package/dist/analyzers/index.js

@@ -0,0 +1,5 @@
+import { javascriptAnalyzer } from "./javascript.js";
+import { pythonAnalyzer } from "./python.js";
+export const analyzers = [javascriptAnalyzer, pythonAnalyzer];
+export { javascriptAnalyzer } from "./javascript.js";
+export { pythonAnalyzer } from "./python.js";

package/dist/analyzers/javascript.d.ts

@@ -0,0 +1,13 @@
+/**
+ * JavaScript/TypeScript analyzer using tree-sitter.
+ * Metrics: cyclomatic complexity, line count, basic duplication heuristic, documentation.
+ */
+import type { AnalyzerResult } from "../types.js";
+export declare const javascriptAnalyzer: {
+    name: string;
+    languages: string[];
+    canAnalyze(filePath: string): boolean;
+    analyze(files: Map<string, string>, _options?: {
+        repoPath?: string;
+    }): Promise<AnalyzerResult>;
+};

package/dist/analyzers/javascript.js

@@ -0,0 +1,89 @@
+/**
+ * JavaScript/TypeScript analyzer using tree-sitter.
+ * Metrics: cyclomatic complexity, line count, basic duplication heuristic, documentation.
+ */
+import Parser from "tree-sitter";
+import JavaScript from "tree-sitter-javascript";
+import TypeScript from "tree-sitter-typescript";
+import { countComplexity, createDebtItem, effectiveLines, inferSeverity, } from "./base.js";
+const LANG_JS = "javascript";
+const LANG_TS = "typescript";
+const JS_EXT = /\.(?:js|jsx|mjs|cjs)$/i;
+const TS_EXT = /\.(?:ts|tsx)$/i;
+function getParser(filePath) {
+    const P = new Parser();
+    const TS = TypeScript;
+    if (filePath.endsWith(".tsx") && TS.tsx) {
+        P.setLanguage(TS.tsx);
+    }
+    else if (TS_EXT.test(filePath) && TS.typescript) {
+        P.setLanguage(TS.typescript);
+    }
+    else {
+        const J = JavaScript;
+        P.setLanguage((J.default ?? JavaScript));
+    }
+    return P;
+}
+function languageForPath(filePath) {
+    return TS_EXT.test(filePath) ? LANG_TS : LANG_JS;
+}
+export const javascriptAnalyzer = {
+    name: "javascript",
+    languages: [LANG_JS, LANG_TS],
+    canAnalyze(filePath) {
+        return JS_EXT.test(filePath) || TS_EXT.test(filePath);
+    },
+    async analyze(files, _options) {
+        const metrics = [];
+        const debtItems = [];
+        const errors = [];
+        for (const [path, content] of files) {
+            const lang = languageForPath(path);
+            const parser = getParser(path);
+            try {
+                const tree = parser.parse(content);
+                const root = tree.rootNode;
+                const complexity = root ? countComplexity(root) : 0;
+                const lineCount = effectiveLines(content);
+                const hasDocumentation = /^\s*(\/\*\*[\s\S]*?\*\/|\/\/\s*@file|\/\*\*)/m.test(content);
+                const fileMetric = {
+                    file: path,
+                    language: lang,
+                    cyclomaticComplexity: complexity,
+                    cognitiveComplexity: complexity,
+                    lineCount,
+                    hasDocumentation,
+                };
+                metrics.push(fileMetric);
+                if (complexity >= 5) {
+                    debtItems.push(createDebtItem(path, "complexity", `High cyclomatic complexity (${complexity})`, `This file has ${complexity} decision points, which makes it harder to test and maintain.`, {
+                        severity: inferSeverity(complexity),
+                        confidence: 0.85,
+                        metrics: { cyclomaticComplexity: complexity },
+                    }));
+                }
+                if (lineCount > 300) {
+                    debtItems.push(createDebtItem(path, "complexity", "Large file", `File has ${lineCount} effective lines. Consider splitting into smaller modules.`, {
+                        severity: lineCount > 500 ? "high" : "medium",
+                        confidence: 0.75,
+                        metrics: { lineCount },
+                    }));
+                }
+                if (!hasDocumentation && lineCount > 50) {
+                    debtItems.push(createDebtItem(path, "documentation", "Missing module-level documentation", "No JSDoc or file-level comment found. Document purpose and usage for maintainability.", { confidence: 0.7 }));
+                }
+            }
+            catch (e) {
+                errors.push({ file: path, message: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        return {
+            language: "javascript",
+            files: [...files.keys()],
+            metrics,
+            debtItems,
+            errors,
+        };
+    },
+};

package/dist/analyzers/python.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Python analyzer using tree-sitter.
+ * Metrics: cyclomatic complexity, line count, docstring presence.
+ */
+import type { AnalyzerResult } from "../types.js";
+export declare const pythonAnalyzer: {
+    name: string;
+    languages: string[];
+    canAnalyze(filePath: string): boolean;
+    analyze(files: Map<string, string>, _options?: {
+        repoPath?: string;
+    }): Promise<AnalyzerResult>;
+};

package/dist/analyzers/python.js

@@ -0,0 +1,77 @@
+/**
+ * Python analyzer using tree-sitter.
+ * Metrics: cyclomatic complexity, line count, docstring presence.
+ */
+import Parser from "tree-sitter";
+import Python from "tree-sitter-python";
+import { countComplexity, createDebtItem, effectiveLines, inferSeverity, } from "./base.js";
+const PY_EXT = /\.py$/i;
+function getParser() {
+    const P = new Parser();
+    P.setLanguage(Python);
+    return P;
+}
+function hasModuleDocstring(content) {
+    const trimmed = content.trimStart();
+    return (trimmed.startsWith('"""') ||
+        trimmed.startsWith("'''") ||
+        /^\s*#.*\n(\s*#.*\n)*/.test(content));
+}
+export const pythonAnalyzer = {
+    name: "python",
+    languages: ["python"],
+    canAnalyze(filePath) {
+        return PY_EXT.test(filePath);
+    },
+    async analyze(files, _options) {
+        const metrics = [];
+        const debtItems = [];
+        const errors = [];
+        const parser = getParser();
+        for (const [path, content] of files) {
+            try {
+                const tree = parser.parse(content);
+                const root = tree.rootNode;
+                const complexity = root ? countComplexity(root) : 0;
+                const lineCount = effectiveLines(content);
+                const hasDocumentation = hasModuleDocstring(content);
+                const fileMetric = {
+                    file: path,
+                    language: "python",
+                    cyclomaticComplexity: complexity,
+                    cognitiveComplexity: complexity,
+                    lineCount,
+                    hasDocumentation,
+                };
+                metrics.push(fileMetric);
+                if (complexity >= 5) {
+                    debtItems.push(createDebtItem(path, "complexity", `High cyclomatic complexity (${complexity})`, `This module has ${complexity} decision points. Consider simplifying conditionals or extracting functions.`, {
+                        severity: inferSeverity(complexity),
+                        confidence: 0.85,
+                        metrics: { cyclomaticComplexity: complexity },
+                    }));
+                }
+                if (lineCount > 250) {
+                    debtItems.push(createDebtItem(path, "complexity", "Large module", `File has ${lineCount} effective lines. Consider splitting into smaller modules or packages.`, {
+                        severity: lineCount > 400 ? "high" : "medium",
+                        confidence: 0.75,
+                        metrics: { lineCount },
+                    }));
+                }
+                if (!hasDocumentation && lineCount > 30) {
+                    debtItems.push(createDebtItem(path, "documentation", "Missing module docstring", "No module-level docstring found. Add a docstring describing the module's purpose.", { confidence: 0.7 }));
+                }
+            }
+            catch (e) {
+                errors.push({ file: path, message: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        return {
+            language: "python",
+            files: [...files.keys()],
+            metrics,
+            debtItems,
+            errors,
+        };
+    },
+};

package/dist/cleanliness-score.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Technical Debt Cleanliness Score: map debt score (0-100) to one of five tiers.
+ * Lower debt score = higher tier (cleaner code).
+ */
+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;

package/dist/cleanliness-score.js

@@ -0,0 +1,24 @@
+/**
+ * Technical Debt Cleanliness Score: map debt score (0-100) to one of five tiers.
+ * Lower debt score = higher tier (cleaner code).
+ */
+const TIERS = [
+    { tier: 1, label: "Prompt Roulette Champion", description: "100% vibes, 0% understanding" },
+    { tier: 2, label: "Vibe Coding Hero", description: '"Just make it work" smashes accept button' },
+    { tier: 3, label: "Thoughtful Prompter", description: "AI helps, human decides" },
+    { 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)));
+    if (clamped <= 20)
+        return TIERS[4]; // 5/5
+    if (clamped <= 40)
+        return TIERS[3]; // 4/5
+    if (clamped <= 60)
+        return TIERS[2]; // 3/5
+    if (clamped <= 80)
+        return TIERS[1]; // 2/5
+    return TIERS[0]; // 1/5
+}

package/dist/cli.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+/**
+ * CLI entry: colorful terminal output, progress bars, actionable insights.
+ */
+export {};