npm package: @nilenpatel/dep-health
Description: Analyze JavaScript/TypeScript project dependencies: outdated packages, unused deps, vulnerabilities, and safe upgrade suggestions
Latest version: 1.0.0

# dep-health

Analyze JavaScript/TypeScript project dependencies: outdated packages, unused deps, security vulnerabilities, and safe upgrade suggestions.

## Installation

```bash
# Global install
npm install -g dep-health

# Or use directly with npx
npx dep-health
```

## Usage

```bash
# Analyze current directory
dep-health

# Analyze a specific project
dep-health ./my-project

# JSON output for CI/automation
dep-health --json

# Auto-apply safe upgrades
dep-health --fix

# Skip specific packages
dep-health --ignore lodash,axios

# Only show high+ severity issues
dep-health --severity high
```

## Options

| Option | Description |
|---|---|
| `--json` | Machine-readable JSON output |
| `--fix` | Auto-apply safe (non-breaking) upgrades to package.json |
| `--ignore <pkgs>` | Comma-separated packages to skip |
| `--severity <level>` | Minimum severity: `low`, `moderate`, `high`, `critical` |
| `-h, --help` | Show help |
| `-v, --version` | Show version |

## Exit Codes

| Code | Meaning |
|---|---|
| `0` | No issues found |
| `1` | Issues found (outdated, unused, or vulnerable) |
| `2` | Critical vulnerabilities found |

## Example Output

```
◆ dep-health analysis report
──────────────────────────────────────────────────

• Outdated Packages
  ⚠ lodash 4.17.15 → 4.17.21 (latest: 4.17.21) [patch]
  ⚠ express 4.18.0 → 4.19.2 (latest: 5.0.0) [major]

• Unused Dependencies
  ✘ moment (dependency)

• Security Vulnerabilities
   HIGH  lodash 4.17.15
    Prototype Pollution in lodash
    https://github.com/advisories/GHSA-...
    Upgrade to lodash@4.17.21

• Upgrade Suggestions
  Safe upgrades:
    ✔ lodash 4.17.15 → 4.17.21 (Fix: Prototype Pollution (high))
  Breaking upgrades (require manual review):
    ⚠ express 4.18.0 → 5.0.0 (Update available)

──────────────────────────────────────────────────
Summary
  Total dependencies: 42
  Outdated:           2
  Unused:             1
  Vulnerabilities:    1
    1 high
  Risk score:         22/100
```

## Features

- **Outdated detection** — Compares installed versions against npm registry. Reports current, wanted (max satisfying declared range), and latest versions.
- **Unused dependency detection** — Static analysis of import/require statements across `.js`, `.ts`, `.jsx`, `.tsx` files. Ignores config-only packages (eslint, jest, prettier, etc).
- **Vulnerability scanning** — Queries the npm audit API. Classifies by severity with affected versions and fix recommendations.
- **Upgrade suggestions** — Recommends minimal safe version bumps. Prefers patch/minor over major. Clearly marks breaking changes.
- **Performance** — Parallel registry calls, in-memory + disk caching, efficient file scanning.
- **Dual output** — Human-readable terminal output with colored symbols, or `--json` for CI pipelines.

## Programmatic API

```typescript
import { runAnalysis, formatJson } from 'dep-health';

const result = await runAnalysis({
  path: '/path/to/project',
  json: false,
  fix: false,
  ignore: [],
  severity: 'low',
});

console.log(result.summary.riskScore);
```

Individual modules are also exported:

```typescript
import { DependencyScanner, OutdatedChecker, UnusedDetector, RegistryClient, semver } from 'dep-health';
```

## Architecture

```
src/
  core/           # Types, semver engine, caching, registry client
    types.ts      # All TypeScript interfaces
    semver.ts     # Zero-dependency semver implementation
    cache.ts      # Memory + disk cache layer
    registry.ts   # npm registry client with batching
  scanner/        # Dependency scanning
    dependency-scanner.ts  # Reads package.json, resolves installed versions
  analyzer/       # Analysis modules
    outdated-checker.ts    # Version comparison against registry
    unused-detector.ts     # Static import analysis
    vulnerability-scanner.ts  # npm audit integration
    upgrade-engine.ts      # Safe upgrade recommendation
  cli/            # CLI interface
    bin.ts        # Entry point and arg parsing
    runner.ts     # Orchestrates the full analysis
    formatter.ts  # Human and JSON output formatting
  index.ts        # Public API exports
tests/            # Jest test suite
```

### Key Design Decisions

- **Zero runtime dependencies** — Uses only Node.js built-ins (`fs`, `path`, `url`) and the native `fetch` API (Node 18+).
- **Custom semver** — Lightweight implementation handling caret, tilde, hyphen, wildcard, and comparison ranges without pulling in the full `semver` package.
- **Dual ESM/CJS** — Compiled to both module systems for maximum compatibility. CLI uses ESM.
- **Disk + memory cache** — Registry responses cached to `.dep-health-cache/` to avoid redundant network calls.
- **Parallel registry fetches** — Batched with configurable concurrency (default: 10 simultaneous).

## GitHub Action

```yaml
name: Dependency Health Check
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9am
  workflow_dispatch:

jobs:
  dep-health:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npm ci
      - run: npx dep-health --json > dep-health-report.json
      - run: npx dep-health --severity high
```

## License

MIT