🩺 proj-pulse

A health checkup for your project — one command to catch what's quietly rotting.

npx proj-pulse

What it checks

| Check | What it finds | |---|---| | 📦 Unused Dependencies | npm packages installed but never imported | | 🔐 Env Var Health | Missing keys, weak secrets, .env not in .gitignore | | 📝 Stale TODOs | TODO/FIXME comments older than 30 days | | 📁 Large Files | Source files over 500 KB that shouldn't be in git | | 🛡️ .gitignore Safety | Missing critical entries (node_modules, .env, etc.) |

Usage

npx proj-pulse "path/to/your/project"

Examples:

# Scan current folder
npx proj-pulse "./"

# Scan a specific project
npx proj-pulse "C:\Users\dev\my-app"
npx proj-pulse "/home/dev/my-app"

Example Output

  🩺 proj-pulse   Project Health Check

  Scanning: /Users/dev/my-app

  ✔  Unused Dependencies
     All 12 dependencies appear to be used.

  ⚠  Env Var Health
     2 env issues detected:
       · .env is NOT listed in .gitignore — risk of leaking secrets
       · Line 4: DB_PASSWORD — weak/short secret
     → Fix: Review your .env file and update insecure or missing values.

  ✖  Stale TODOs
     5 TODO/FIXME found, 3 older than 30 days:
       · [TODO] src/api/auth.js:42 — "refactor token handling" (87d old)
       · [FIXME] src/utils/parser.js:11 — "edge case for empty array" (63d old)
       · [HACK] src/db/index.js:7 — "replace with proper pool" (45d old)
     → Fix: Address or remove comments older than 30 days.

  ✔  Large Files
     No unexpectedly large source files found (threshold: 500 KB).

  ⚠  .gitignore Safety
     1 .gitignore issue found:
       · Missing: ".env"  (secrets / API keys)
     → Fix: Add missing entries to your .gitignore file.

──────────────────────────────────────────────────
  Summary

  ✔ Passed   2/5
  ⚠ Warnings 2/5
  ✖ Failed   1/5

  Health Score: 40%
──────────────────────────────────────────────────

Roadmap

• [ ] --fix flag to auto-resolve safe issues
• [ ] JSON output for CI integration (--json)
• [ ] Config file (.proj-pulse.json) for custom thresholds
• [ ] Git history analysis for churn / hotspot detection
• [ ] Dead code detection

License

MIT