🩺 ProjectDoctor

A production-quality CLI diagnostic tool that analyzes your JavaScript / Node.js codebase and reports its health — with zero external dependencies.

╭────────────────────────────────────────────╮
│  🩺  ProjectDoctor Report  my-app      │
│                                        │
│    Project Health:  ⚠ Needs Attention  │
╰────────────────────────────────────────────╯

📊  Project Stats
────────────────────────────────────────────
  Files                      182
  Source files               143
  Lines of code              21,943
  Largest file               src/api.js (612 lines)
  Dependencies               37
  Dev dependencies           14

🌱  Environment
────────────────────────────────────────────
  ✔  .env file found
  ✔  .env.example file found
  ⚠  Missing env variables: 1
     - DATABASE_URL
  ⚠  Potentially unused env variables: 3
     - OLD_API_KEY

🧠  Code Mood
────────────────────────────────────────────
  TODOs                      21
  FIXMEs                     4
  console.log calls          11
  HACK markers               2
  Mood                       😬 stressed

🚨  Possible Issues
────────────────────────────────────────────

  src/user.js
    - unused variable: tempUser (line 42)

  src/api.js
    - empty catch block (line 88)
    - duplicate import: 'lodash' (line 112)

📦  Dependencies
────────────────────────────────────────────
  Production dependencies    37
  Dev dependencies           14
  ⚠  Potentially outdated: 3
     - express (declared ^4.0.0, installed 3.5.0)
  ⚠  Possibly unused packages: lodash

---

✨ Features

Feature	Description
Project Stats	Total files, lines of code, largest file, dependency counts
Code Mood	Counts TODOs, FIXMEs, console.logs and assigns a mood
Environment Health	Detects missing / unused .env variables vs .env.example
Issue Finder	Finds empty catch blocks, duplicate imports, unused variables
Dependency Health	Detects outdated and potentially unused packages

---

🚀 Quick Start

Run instantly with npx — no installation required:

npx projectdoctor

Or install globally:

npm install -g projectdoctor
projectdoctor

---

📦 Requirements

• Node.js ≥ 18.0.0
• Zero runtime dependencies — works anywhere Node runs, npx works immediately

---

🧰 CLI Commands

# Full diagnosis (default)
projectdoctor

# Individual sections
projectdoctor stats       # 📊 Project file & line statistics
projectdoctor env         # 🌱 Environment variable health
projectdoctor mood        # 🧠 Code mood analysis
projectdoctor errors      # 🚨 Possible code issues
projectdoctor deps        # 📦 Dependency health

# Options
projectdoctor -d ./myapp  # Analyze a specific directory
projectdoctor --version   # Show version
projectdoctor --help      # Show help

---

🔍 What Gets Scanned

File extensions included: .js .jsx .mjs .ts .tsx .cjs

Directories ignored: node_modules, .git, dist, build, coverage, .next, .cache, .turbo, .vercel

---

🩺 Health Levels

Icon	Level	Condition
✔ Healthy	All clear	Score < 2
⚠ Needs Attention	Warning	Score 2–4
✖ Critical	Urgent	Score ≥ 5

Score is computed from: stressed mood (+2), missing env vars (+1 each), many file issues (+1–2), many outdated deps (+1).

---

🧠 Code Mood Scale

Mood	Marker Count	Meaning
😊 healthy	0–5	Clean codebase
😐 moderate	6–20	Some cleanup needed
😬 stressed	21+	Technical debt accumulating

Markers counted: TODO, FIXME, HACK, console.log/warn/error/debug

---

🌱 Environment Analysis

Compares .env against .env.example:

• Missing vars — keys in .env.example not present in .env
• Unused vars — keys in .env never referenced as process.env.KEY in source

---

🚨 Code Issues Detected

Issue	How
Empty catch blocks	Heuristic scan for catch {} with no body statements
console.log/warn/error	Regex across all source files
Duplicate imports	Tracks seen import/require module paths per file
Unused variables	const x = … declared once and never referenced again

These are fast heuristic checks, not a full AST parse. Use ESLint for exhaustive analysis.

---

📦 Dependency Analysis

• Outdated — compares declared semver range against the version installed in node_modules
• Unused — packages never imported or required in source (with a built-in allowlist for implicit deps like dotenv, cross-env, typescript)

---

🛠️ Debug Mode

DEBUG=1 projectdoctor

Prints full stack traces on unexpected errors.

---

📁 Project Structure

projectdoctor/
├── src/
│   ├── cli.js                  # CLI entry point & arg parsing
│   ├── index.js                # Report orchestration & section printers
│   ├── analyzers/
│   │   ├── stats.js            # File/line/dependency counts
│   │   ├── mood.js             # TODO/FIXME/console.log scanner
│   │   ├── env.js              # .env vs .env.example comparison
│   │   ├── errors.js           # Common code issue detector
│   │   └── deps.js             # Dependency health checker
│   └── utils/
│       ├── colors.js           # Zero-dep ANSI color helpers
│       ├── display.js          # Terminal output (sections, rows, boxes)
│       └── fs.js               # File system walking utilities
├── package.json
└── README.md

---

🤝 Contributing

1. Fork the repo
2. Create a feature branch: git checkout -b feat/my-feature
3. Commit: git commit -m 'feat: add X'
4. Push and open a Pull Request

---

📄 License

MIT © ProjectDoctor