tech-debt-visualizer 0.1.0

package/dist/reports/json.js

@@ -0,0 +1,19 @@
+export function generateJsonReport(run) {
+    const payload = {
+        repoPath: run.repoPath,
+        startedAt: run.startedAt,
+        completedAt: run.completedAt,
+        analyzers: run.analyzers,
+        summary: {
+            filesAnalyzed: run.fileMetrics.length,
+            debtItemsCount: run.debtItems.length,
+            errorsCount: run.errors.length,
+        },
+        fileMetrics: run.fileMetrics,
+        debtItems: run.debtItems,
+        debtTrend: run.debtTrend,
+        errors: run.errors,
+        llmOverallAssessment: run.llmOverallAssessment ?? undefined,
+    };
+    return JSON.stringify(payload, null, 2);
+}

package/dist/reports/markdown.d.ts

@@ -0,0 +1,2 @@
+import type { AnalysisRun } from "../types.js";
+export declare function generateMarkdownReport(run: AnalysisRun): string;

package/dist/reports/markdown.js

@@ -0,0 +1,64 @@
+export function generateMarkdownReport(run) {
+    const lines = [];
+    lines.push("# Technical Debt Report");
+    lines.push("");
+    lines.push(`**Repository:** \`${run.repoPath}\``);
+    lines.push(`**Generated:** ${run.completedAt ?? run.startedAt}`);
+    lines.push("");
+    lines.push("## Summary");
+    lines.push("");
+    lines.push(`| Metric | Value |`);
+    lines.push(`|--------|-------|`);
+    lines.push(`| Files analyzed | ${run.fileMetrics.length} |`);
+    lines.push(`| Debt items | ${run.debtItems.length} |`);
+    lines.push(`| Parse errors | ${run.errors.length} |`);
+    lines.push("");
+    const bySeverity = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const d of run.debtItems) {
+        bySeverity[d.severity]++;
+    }
+    lines.push("## By severity");
+    lines.push("");
+    lines.push(`- **Critical:** ${bySeverity.critical}`);
+    lines.push(`- **High:** ${bySeverity.high}`);
+    lines.push(`- **Medium:** ${bySeverity.medium}`);
+    lines.push(`- **Low:** ${bySeverity.low}`);
+    lines.push("");
+    const hotspots = run.fileMetrics
+        .filter((m) => (m.hotspotScore ?? 0) > 0.2)
+        .sort((a, b) => (b.hotspotScore ?? 0) - (a.hotspotScore ?? 0))
+        .slice(0, 15);
+    if (hotspots.length > 0) {
+        lines.push("## Hotspot files");
+        lines.push("");
+        lines.push("| File | Hotspot score | Complexity | Churn |");
+        lines.push("|------|---------------|------------|-------|");
+        for (const h of hotspots) {
+            lines.push(`| \`${h.file}\` | ${(h.hotspotScore ?? 0).toFixed(2)} | ${h.cyclomaticComplexity ?? "-"} | ${h.churn ?? "-"} |`);
+        }
+        lines.push("");
+    }
+    lines.push("## Debt items");
+    lines.push("");
+    const byCategory = new Map();
+    for (const d of run.debtItems) {
+        const list = byCategory.get(d.category) ?? [];
+        list.push(d);
+        byCategory.set(d.category, list);
+    }
+    const order = ["complexity", "hotspot", "documentation", "duplication", "architecture", "dependencies", "other"];
+    for (const cat of order) {
+        const items = byCategory.get(cat);
+        if (!items?.length)
+            continue;
+        lines.push(`### ${cat}`);
+        lines.push("");
+        for (const d of items.slice(0, 20)) {
+            lines.push(`- **${d.title}** (\`${d.file}${d.line ? `:${d.line}` : ""}\`) — ${d.severity}`);
+            if (d.insight)
+                lines.push(`  - ${d.insight}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/dist/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Core types for the Technical Debt Visualizer.
+ * Language-agnostic debt items, metrics, and analyzer contracts.
+ */
+export type DebtCategory = "complexity" | "duplication" | "dependencies" | "test_coverage" | "documentation" | "architecture" | "hotspot" | "naming" | "other";
+export type Severity = "low" | "medium" | "high" | "critical";
+export interface DebtItem {
+    id: string;
+    file: string;
+    line?: number;
+    endLine?: number;
+    category: DebtCategory;
+    severity: Severity;
+    title: string;
+    description: string;
+    /** 0-1 confidence that this is real debt */
+    confidence: number;
+    /** LLM-generated explanation of why it matters and what to do */
+    insight?: string;
+    /** LLM-suggested simplified/refactored code snippet (when applicable) */
+    suggestedCode?: string;
+    /** Raw metrics that contributed (e.g. cyclomatic complexity value) */
+    metrics?: Record<string, number | string>;
+    /** Suggested fix or refactor (short text) */
+    recommendation?: string;
+}
+export interface FileMetrics {
+    file: string;
+    language: string;
+    /** Cyclomatic complexity (max or sum by scope) */
+    cyclomaticComplexity?: number;
+    /** Cognitive complexity style */
+    cognitiveComplexity?: number;
+    lineCount: number;
+    /** Approx. duplicate/similar blocks */
+    duplicateBlocks?: number;
+    /** Test coverage 0-1 if available */
+    coverage?: number;
+    /** Has docstring/JSDoc at module level */
+    hasDocumentation?: boolean;
+    /** Coupling / dependency count */
+    coupling?: number;
+    /** From git: number of commits touching this file in window */
+    changeCount?: number;
+    /** From git: lines changed in window */
+    churn?: number;
+    /** Computed: high churn + high complexity */
+    hotspotScore?: number;
+    /** LLM-generated short assessment of this file's cleanliness (when LLM attached) */
+    llmAssessment?: string;
+    /** LLM-suggested refactored code snippet for this file (when applicable) */
+    llmSuggestedCode?: string;
+}
+export interface GitBlameEntry {
+    file: string;
+    commits: number;
+    authors: number;
+    lastChange: string;
+    churn: number;
+}
+export interface AnalyzerResult {
+    language: string;
+    files: string[];
+    metrics: FileMetrics[];
+    debtItems: DebtItem[];
+    /** Errors during analysis (e.g. parse failures) */
+    errors: Array<{
+        file: string;
+        message: string;
+    }>;
+}
+export interface AnalysisRun {
+    repoPath: string;
+    startedAt: string;
+    completedAt?: string;
+    analyzers: string[];
+    fileMetrics: FileMetrics[];
+    debtItems: DebtItem[];
+    /** Time-series: debt score over recent commits (for trend) */
+    debtTrend?: Array<{
+        commit: string;
+        date: string;
+        score: number;
+    }>;
+    errors: Array<{
+        file: string;
+        message: string;
+    }>;
+    /** LLM-generated overall codebase cleanliness assessment (when LLM attached) */
+    llmOverallAssessment?: string;
+}
+/** Pluggable analyzer: given file paths and content, returns metrics + debt items */
+export interface IAnalyzer {
+    readonly name: string;
+    readonly languages: string[];
+    /** Check if this analyzer can handle the given file path */
+    canAnalyze(filePath: string): boolean;
+    /** Analyze files; content keyed by path */
+    analyze(files: Map<string, string>, options?: {
+        repoPath?: string;
+    }): Promise<AnalyzerResult>;
+}
+export interface ReportOptions {
+    outputPath: string;
+    format: "html" | "json" | "markdown";
+    title?: string;
+    darkMode?: boolean;
+}
+export interface CliOptions {
+    path: string;
+    output?: string;
+    format?: "html" | "json" | "markdown" | "cli";
+    languages?: string[];
+    noLlm?: boolean;
+    ci?: boolean;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Core types for the Technical Debt Visualizer.
+ * Language-agnostic debt items, metrics, and analyzer contracts.
+ */
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "tech-debt-visualizer",
+  "version": "0.1.0",
+  "description": "Language-agnostic CLI that analyzes repos and generates interactive technical debt visualizations with AI-powered insights",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "tech-debt": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "analyze": "node dist/cli.js analyze",
+    "dev": "tsx src/cli.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "technical-debt",
+    "code-quality",
+    "static-analysis",
+    "visualization"
+  ],
+  "author": "",
+  "license": "GPL-3.0-only",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "cli-progress": "^3.12.0",
+    "commander": "^12.1.0",
+    "simple-git": "^3.27.0",
+    "tree-sitter": "^0.21.1",
+    "tree-sitter-javascript": "^0.21.0",
+    "tree-sitter-typescript": "^0.21.0",
+    "tree-sitter-python": "^0.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}