Project Health Analyzer

A friendly CLI tool that analyzes your project’s health, shows rich reports (console + JSON + PNG + HTML), and even helps you safely upgrade dependencies.

🟢 This package helps maintain healthy & future-ready projects by detecting issues early and guiding developers toward improvements.

🚀 Installation

Option 1: Run via npx (recommended)

You don’t need to install it globally if you use npx.

npx project-health-analyzer

Option 2: Run via npm

npm i -g project-health-analyzer

✨ What it does

project-health-analyzer runs inside your project folder and gives you a 360° health check:

🧠 Core Insights

• Project Size Overview

  • Total project size in MB
  • Helps you spot bloated repos early

• Tech Stack Detection (GitHub-style)

  • Detects languages by file extensions (.ts, .js, .html, .scss, etc.)
  • Shows percentage usage per language (e.g. TypeScript (92%) | HTML (5%) | SCSS (3%))

• Dependency Analysis (npm / yarn / pnpm)

  • Detects outdated dependencies
  • Shows current → wanted → latest versions
  • Separates:
    • ✅ Safe updates (same major version)
    • ⚠ Major updates (breaking changes likely)

• Unused Dependencies Detector

  • Scans your source code and flags dependencies that are never imported
  • Example:
    • Unused: moment, request

• Project Bloat Radar

  • Finds folders that occupy the most space
  • Example:
    • assets/images (98 MB)
    • dist (22 MB)
    • screenshots (15 MB)

💚 Health & Trend Metrics

• Overall Project Health Score (0–100)

  • Combines:
    • Outdated dependencies
    • Vulnerability count (if integrated)
    • Dead files (if integrated)
    • Project size
  • Lower score → more risk; higher score → healthier project
  • Shown in:
    • Console
    • JSON report
    • HTML + PNG report
    • Stylish badge at top of the report

• Health Trend Over Time

  • Each scan is logged into .project-health-history.json
  • Shows last few scores, e.g.:
    • 62 → 68 → 74 → 81 → 87
  • Tells you if your project is:
    • 🚀 Improving
    • ⚠ Declining
    • ➖ Stable

📊 Reports Generated

Every run of project-health-analyzer generates:

• 🖥 Console Report

  • Quick summary box with:
    • Project size
    • Tech stack summary
    • Total outdated deps
    • Vulnerabilities count (if wired)
    • Dead files count (if wired)
    • Health score
    • Unused dependencies count
    • Biggest folder info
  • Plus:
    • Safe updates list
    • Major updates list
    • Health trend

• 📁 JSON Report (machine-readable)

  • Location: logs/report-YYYY-MM-DDTHH-MM-SS.json
  • Contains:
    • All metrics
    • Upgrade summary
    • Trend data

• 🌐 HTML Report

  • Location: logs/report-YYYY-MM-DDTHH-MM-SS.html
  • Clean HTML report rendering all sections
  • Used as a base for PNG

• 🖼 PNG Snapshot Report

  • Location: logs/report-YYYY-MM-DDTHH-MM-SS.png
  • A visual snapshot of the full HTML report
  • Includes a badge-style Health Score bar

🔧 Smart Upgrade Assistant

The tool doesn’t just tell you what’s wrong — it helps you fix it:

• Classifies dependency updates into:

  • 🟢 Safe updates (same major version → non-breaking)
  • 🔴 Major updates (breaking risk)

• After the scan:

  • If outdated dependencies exist, it will:
    • Either ask you in the terminal:

      Do you want to update safe (non-breaking) dependencies now?

    • Or auto-apply updates if you use the --fix flag

• Safe auto-fix behavior:

  • Only updates dependencies where:
    • currentMajor === latestMajor
  • Runs the appropriate command based on:
    • npm → npm install <pkg>@<latest>
    • yarn → yarn add <pkg>@<latest>
    • pnpm → pnpm add <pkg>@<latest>

• To clear the old logs use --cleanflag

Keywords:
project health · dependency audit · unused dependencies · outdated packages · security analysis · auto fix · tech stack detection · project analytics · health score · cli tool · CI reporting · developer productivity