tech-debt-visualizer 0.2.21 → 0.2.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +48 -37
  2. package/dist/cli.js +34 -12
  3. package/dist/reports/assets/report.css +2 -0
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,26 +1,51 @@
1
1
  # Technical Debt Visualizer
2
2
 
3
+ **[tech-debt-visualizer](https://www.npmjs.com/package/tech-debt-visualizer)** on npm
4
+
3
5
  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.
4
6
 
5
- ![Node 18+](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)
6
- ![Languages](https://img.shields.io/badge/languages-JS%20%7C%20TS%20%7C%20Python-green?style=flat-square)
7
- ![License](https://img.shields.io/badge/license-GPL--3.0-blue?style=flat-square)
7
+ ![npm version](https://img.shields.io/npm/v/tech-debt-visualizer)
8
+ ![npm downloads](https://img.shields.io/npm/dm/tech-debt-visualizer)
9
+ ![Node version](https://img.shields.io/node/v/tech-debt-visualizer)
10
+ ![License](https://img.shields.io/badge/license-GPL--3.0-blue)
11
+ ![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)
8
12
 
9
13
  ---
10
14
 
11
- ## Quick start
15
+ ## From the get-go
16
+
17
+ **Option A — No install (run from any folder):**
18
+
19
+ ```bash
20
+ npx tech-debt-visualizer analyze .
21
+ ```
22
+
23
+ **Option B — Install once, then run:**
12
24
 
13
25
  ```bash
14
- git clone <this-repo>
15
- cd tech-debt-visualizer
16
- npm install && npm run build
17
- node dist/cli.js analyze . --format cli
26
+ npm install -g tech-debt-visualizer
27
+ tech-debt-visualizer analyze .
18
28
  ```
19
29
 
20
- To try the **HTML dashboard**:
21
- `node dist/cli.js analyze . --format html -o report.html` then open `report.html`.
30
+ That's the command: **`tech-debt-visualizer analyze .`** (the `.` is "this folder"). You get a terminal report: cleanliness tier (1–5), debt items, hotspots, and a "what to fix" list. No config required. Node 18+.
22
31
 
23
- To use **AI insights** (explanations + optional code refactors): set `GEMINI_API_KEY` or `OPENAI_API_KEY` and run the same commands without `--no-llm`.
32
+ - **HTML report?** Add `-f html -o report.html`, then open the file.
33
+ - **No API key?** Add `--no-llm` for metrics only (no AI).
34
+
35
+ More options: run **`tech-debt-visualizer analyze --help`** (or with `npx` if you didn't install globally).
36
+
37
+ ---
38
+
39
+ ## How to run it
40
+
41
+ | What you want | Command |
42
+ |----------------|--------|
43
+ | **Terminal report** | `tech-debt-visualizer analyze .` (or `npx tech-debt-visualizer analyze .` if not installed) |
44
+ | **HTML report** | `tech-debt-visualizer analyze . -f html -o report.html` |
45
+ | **No AI (no API key)** | `tech-debt-visualizer analyze . --no-llm` |
46
+ | **From this repo (dev)** | `npm run build` then `npm run analyze` |
47
+
48
+ Use **`tech-debt-visualizer`** (not `tech-debt`); `npx tech-debt` is a different package.
24
49
 
25
50
  ---
26
51
 
@@ -60,44 +85,30 @@ So: **static metrics + git → score & tier → optional LLM explanations and co
60
85
 
61
86
  ---
62
87
 
63
- ## Install & run
64
-
65
- | How you run it | Command |
66
- |----------------|--------|
67
- | **From this repo** | `node dist/cli.js analyze [path]` (after `npm run build`) |
68
- | **Global (after publish)** | `npm install -g tech-debt-visualizer` then `tech-debt analyze [path]` |
69
- | **No install (after publish)** | `npx tech-debt-visualizer analyze [path]` |
70
-
71
- Use **`tech-debt-visualizer`** in the command (not `tech-debt`); `npx tech-debt` runs a different npm package. From this repo you can also run `npm run analyze` or `node dist/cli.js analyze .`.
72
-
73
- Requires **Node 18+**.
74
-
75
- ---
76
-
77
88
  ## Options
78
89
 
79
90
  | Option | Meaning |
80
91
  |--------|--------|
81
92
  | `-f, --format` | `cli` (default), `html`, `json`, or `markdown` |
82
- | `-o, --output` | Output path (e.g. `report.html` for HTML) |
83
- | `--no-llm` | Skip all LLM calls (no API key needed) |
84
- | `--llm` | Enable LLM (default). Use with `--llm-key` and/or `--llm-model` |
93
+ | `-o, --output` | Output file path (for html/json/markdown) |
94
+ | `--no-llm` | Skip AI insights (no API key needed) |
85
95
  | `--llm-key <key>` | API key (overrides env / `.env`) |
86
96
  | `--llm-model <model>` | Model name (e.g. `gemini-1.5-flash`, `gpt-4o-mini`) |
87
- | `--ci` | Terse output; exit code 1 if debt score &gt; 60 |
97
+ | `--ci` | CI mode: terse output; exit 1 if debt is high |
88
98
 
89
99
  Examples:
90
100
 
91
101
  ```bash
92
- node dist/cli.js analyze . -f html -o report.html
93
- node dist/cli.js analyze ./src -f json -o debt.json
94
- node dist/cli.js analyze . --ci
95
- # With LLM key and model on the command line:
96
- node dist/cli.js analyze . --llm-key YOUR_GEMINI_KEY --llm-model gemini-1.5-flash
97
- # Or use a .env file in the current directory (GEMINI_API_KEY=...)
98
- node dist/cli.js analyze .
102
+ npx tech-debt-visualizer analyze .
103
+ npx tech-debt-visualizer analyze . -f html -o report.html
104
+ npx tech-debt-visualizer analyze ./src -f json -o debt.json
105
+ npx tech-debt-visualizer analyze . --no-llm
106
+ npx tech-debt-visualizer analyze . --ci
107
+ npx tech-debt-visualizer analyze . --llm-key YOUR_KEY --llm-model gemini-1.5-flash
99
108
  ```
100
109
 
110
+ Full list: `npx tech-debt-visualizer analyze --help`
111
+
101
112
  ---
102
113
 
103
114
  ## LLM (optional)
@@ -161,7 +172,7 @@ src/
161
172
 
162
173
  ---
163
174
 
164
- ## Publishing (maintainers)
175
+ ## Publishing
165
176
 
166
177
  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).
167
178
 
package/dist/cli.js CHANGED
@@ -3,8 +3,10 @@
3
3
  * CLI entry: colorful terminal output, progress bars, actionable insights.
4
4
  * Loads .env from cwd first; supports --llm-key and --llm-model.
5
5
  */
6
+ import { readFileSync } from "node:fs";
6
7
  import { readFile } from "node:fs/promises";
7
- import { join } from "node:path";
8
+ import { dirname, join } from "node:path";
9
+ import { fileURLToPath } from "node:url";
8
10
  import { loadEnv } from "./load-env.js";
9
11
  import { Command } from "commander";
10
12
  import chalk from "chalk";
@@ -17,24 +19,44 @@ import { generateHtmlReport } from "./reports/html.js";
17
19
  import { generateJsonReport } from "./reports/json.js";
18
20
  import { generateMarkdownReport } from "./reports/markdown.js";
19
21
  import { SEVERITY_ORDER } from "./types.js";
22
+ function getVersion() {
23
+ try {
24
+ const __dirname = dirname(fileURLToPath(import.meta.url));
25
+ const pkgPath = join(__dirname, "..", "package.json");
26
+ const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
27
+ return (pkg && pkg.version) || "0.0.0";
28
+ }
29
+ catch {
30
+ return "0.0.0";
31
+ }
32
+ }
20
33
  const program = new Command();
21
34
  program
22
- .name("tech-debt")
23
- .description("Analyze repositories and visualize technical debt with AI-powered insights")
24
- .version("0.1.2");
35
+ .name("tech-debt-visualizer")
36
+ .description("Analyze a repo and get a cleanliness score, debt breakdown, and optional AI insights. No install required.")
37
+ .version(getVersion());
25
38
  program
26
39
  .command("analyze")
27
- .description("Analyze a repository and output report")
28
- .argument("[path]", "Repository path", ".")
29
- .option("-o, --output <path>", "Output file path (default: report.html or stdout for CLI)")
40
+ .description("Analyze a folder (default: current directory) and print or save a report")
41
+ .argument("[path]", "Path to the repo or folder to analyze", ".")
30
42
  .option("-f, --format <type>", "Output format: cli | html | json | markdown", "cli")
31
- .option("--no-llm", "Skip LLM-powered insights")
32
- .option("--llm", "Enable LLM (default). Use with --llm-key and/or --llm-model")
43
+ .option("-o, --output <path>", "Write output to this file (for html/json/markdown)")
44
+ .option("--no-llm", "Skip AI insights (no API key needed; use this for a quick run)")
45
+ .option("--llm", "Enable AI insights (default when an API key is set)")
33
46
  .option("--llm-key <key>", "API key (overrides env: GEMINI_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY)")
34
- .option("--llm-endpoint <url>", "OpenAI-compatible API base URL (e.g. https://api.openai.com/v1 or proxy)")
47
+ .option("--llm-endpoint <url>", "OpenAI-compatible API base URL")
35
48
  .option("--llm-model <model>", "Model name (e.g. gpt-4o-mini, gemini-2.5-flash)")
36
49
  .option("--llm-max-tokens <n>", "Max tokens per response", (v) => parseInt(v, 10))
37
- .option("--ci", "CI mode: minimal output, exit with non-zero if debt score is high")
50
+ .option("--ci", "CI mode: terse output; exit 1 if debt is high")
51
+ .addHelpText("after", `
52
+ Quick start:
53
+ npx tech-debt-visualizer analyze . No install: analyze current folder → terminal report
54
+ tech-debt-visualizer analyze . Same, if you ran: npm install -g tech-debt-visualizer
55
+ tech-debt-visualizer analyze . -f html -o report.html Save interactive HTML report
56
+ tech-debt-visualizer analyze . --no-llm Skip AI (no API key needed)
57
+
58
+ Requires Node 18+. For AI insights, set GEMINI_API_KEY or OPENAI_API_KEY (or use --llm-key).
59
+ `)
38
60
  .action(async (path, opts) => {
39
61
  const repoPath = join(process.cwd(), path);
40
62
  const format = (opts.format ?? "cli");
@@ -274,7 +296,7 @@ function printCliReport(run, ci) {
274
296
  process.stdout.write(chalk.dim(" No debt items. Keep it up.\n"));
275
297
  }
276
298
  process.stdout.write("\n");
277
- process.stdout.write(chalk.dim(" Run with --format html -o report.html for the interactive dashboard.\n\n"));
299
+ process.stdout.write(chalk.dim(" Tip: npx tech-debt-visualizer analyze . -f html -o report.html → interactive dashboard.\n\n"));
278
300
  }
279
301
  function severityOrder(s) {
280
302
  return SEVERITY_ORDER[s] ?? 0;
package/dist/reports/assets/report.css CHANGED
@@ -829,6 +829,8 @@ body.dashboard-page {
829
829
  grid-template-columns: repeat(auto-fill, minmax(72px, 1fr));
830
830
  gap: 0.4rem;
831
831
  min-height: 80px;
832
+ max-height: 10.5rem; /* ~2 rows of cells (72px + gap) * 2 */
833
+ overflow-y: auto;
832
834
  padding: 0.15rem 0;
833
835
  }
834
836
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tech-debt-visualizer",
3
- "version": "0.2.21",
3
+ "version": "0.2.22",
4
4
  "description": "Language-agnostic CLI that analyzes repos and generates interactive technical debt visualizations with AI-powered insights",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",