🩺 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