pkg-health/README.md

A CLI tool to scan your project's dependencies and generate a health report with security, version, and license insights.

# pkg-health

Scan your project's dependencies and print a dependency health report.

## Requirements

- Node.js >= 16
- Run inside a project that has a `package.json` and installed `node_modules`.

## Install

```bash
# npm (recommended)
npm install -g pkg-health

# yarn
yarn global add pkg-health

# pnpm
pnpm add -g pkg-health
```

## Usage

```bash
pkg-health [options]
```

### Commands / Options

```bash
pkg-health                 # scan and print the table
pkg-health --json          # output JSON
pkg-health --ci            # exit non-zero if Deprecated or Vulnerable found
pkg-health --help          # show help
pkg-health --version       # show version
```

### Table output (default)

Running `pkg-health` prints a colorized table:

```
┌──────────────────┬─────────┬─────────┬────────────┬────────────┬────────────┬──────────┬─────────────────┬─────────────────┐
│ Package Name     │ Current │ Latest  │ Update Type│ Status     │ License    │ Node Eng.│ Current Size    │ Latest Size     │
├──────────────────┼─────────┼─────────┼────────────┼────────────┼────────────┼──────────┼─────────────────┼─────────────────┤
│ express          │ 4.18.0  │ 5.0.0   │ Major      │ Outdated   │ MIT        │ >=12     │ 220 KB          │ 260 KB          │
│ mongoose         │ 6.9.0   │ 6.9.2   │ Patch      │ Up-to-date │ MIT        │ >=14     │ 1.2 MB          │ 1.25 MB         │
│ lodash           │ 4.17.15 │ 4.17.21 │ Patch      │ Vulnerable │ MIT        │ Any      │ 540 KB          │ 540 KB          │
│ body-parser      │ 1.19.0  │ 1.20.2  │ Minor      │ Deprecated │ MIT        │ >=10     │ 92 KB           │ 100 KB          │
│ chalk            │ 4.1.0   │ 5.3.0   │ Major      │ Outdated   │ MIT        │ >=16     │ 32 KB           │ 40 KB           │
└──────────────────┴─────────┴─────────┴────────────┴────────────┴────────────┴──────────┴─────────────────┴─────────────────┘
```

- Colors: green = healthy, yellow = outdated, red = vulnerable/deprecated.
- Missing data is shown as `N/A`.

### JSON output

```bash
pkg-health --json
```

Example JSON:

```json
{
  "results": [
    {
      "name": "express",
      "currentVersion": "4.18.0",
      "latestVersion": "5.0.0",
      "updateType": "Major",
      "status": "Outdated",
      "license": "MIT",
      "enginesNode": ">=12",
      "currentSize": 225280,
      "latestSize": 266240
    }
  ]
}
```

### CI mode

Fail the build if any dependency is Deprecated or Vulnerable:

```bash
pkg-health --ci
```

Exit codes:

- 0: no critical issues
- 2: critical issues found (Deprecated or Vulnerable)
- 1: runtime error (network/read errors, etc.)

## What it checks

- Package Name
- Current Version (installed)
- Latest Version (npm dist-tags.latest)
- Update Type (Patch / Minor / Major)
- Status (Up-to-date, Outdated, Vulnerable, Deprecated)
- License
- Node Engine requirement
- Current Package Size (installed size)
- Latest Package Size (npm dist.unpackedSize)

## Tips

- Run your package manager install first (`npm i` / `yarn` / `pnpm i`) so installed versions and sizes can be read.
- Behind a proxy? Configure npm: `npm config set proxy http://...` and `npm config set https-proxy http://...`.

## Benefits of using pkg-health

- Quickly see which dependencies are outdated and how risky the update is (Patch/Minor/Major).
- Spot potential risks at a glance with color-coded statuses.
- Understand license exposure and Node engine requirements.
- Compare installed vs. latest package sizes to anticipate bloat.
- Machine-readable JSON for CI dashboards and automated reporting.
- Optional CI gate to prevent merging when critical issues are present.

## Notes

- Vulnerability detection is a placeholder (no advisories queried by default).
- If data is missing, `N/A` is shown.

## License

MIT Copyright (c) 2025 Vatsal Kachhadiya