npm package: @sergiovalerdev/dependency-validator
Description: Dependency hygiene and supply chain security analysis for npm projects
Author: sergiovalerdev
Latest version: 0.1.0

# @sergiovalerdev/dependency-validator

Dependency hygiene and supply chain security analysis for npm projects.

Validates that your dependencies exist on the official registry, detects suspicious origins (git URLs, file paths, custom registries), and calculates a security score from 0 to 100.

**This tool does NOT scan for CVEs.** It focuses on dependency supply chain hygiene.

## Installation

```bash
npm install -g @sergiovalerdev/dependency-validator
```

Or as a dev dependency:

```bash
npm install -D @sergiovalerdev/dependency-validator
```

## CLI Usage

```bash
# Analyze the current project
dependency-validator

# Analyze a specific path
dependency-validator ./my-project

# CI mode (exit non-zero on failure)
dependency-validator --ci

# Strict mode (fail on any warning)
dependency-validator --strict

# Custom minimum score
dependency-validator --ci --min-score 90

# JSON output
dependency-validator --json

# Verbose logging
dependency-validator --verbose
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success (or informational mode) |
| 1 | Score below threshold (`--ci`) or warnings found (`--strict`) |
| 2 | Critical errors found (e.g., packages not on registry) |
| 3 | Runtime error (missing files, network failure) |

In default mode (without `--ci` or `--strict`), the tool always exits with code 0.

## Scoring System

The security score starts at 100 and is reduced by issues:

| Issue | Deduction | Severity |
|-------|-----------|----------|
| Package not found on registry | -10 | ERROR |
| Version not found on registry | -10 | ERROR |
| Git dependency | -5 | WARNING |
| File/link dependency | -5 | WARNING |
| Custom registry | -3 | WARNING |

The score is floored at 0.

## Programmatic API

```typescript
import { analyze } from '@sergiovalerdev/dependency-validator';

const report = await analyze('./my-project');
console.log(report.score.score); // 0-100
console.log(report.issues);      // ValidationIssue[]
```

## CI Integration

### GitHub Actions

```yaml
- name: Check dependency hygiene
  run: npx @sergiovalerdev/dependency-validator --ci --min-score 80
```

### npm scripts

```json
{
  "scripts": {
    "check:deps": "dependency-validator --ci"
  }
}
```

## Supported Package Managers

- **npm** (package-lock.json v2/v3)
- **yarn** (yarn.lock v1)
- **pnpm** (planned for v1.1.0)

When no lockfile is found, the tool falls back to analyzing `package.json` only.

## What It Detects

- **Non-existent packages**: Dependencies not found on the npm registry
- **Non-existent versions**: Locked versions that don't exist on the registry
- **Git dependencies**: Packages installed from git repositories
- **File dependencies**: Packages installed from local file paths
- **Custom registries**: Packages resolved from non-standard registries

## Limitations

- Does not scan for CVEs or known vulnerabilities (use `npm audit` for that)
- pnpm lockfile support is planned for v1.1.0
- Yarn Berry (v2+) lockfiles are not yet supported
- Monorepo/workspace analysis is planned for v1.1.0

## License

MIT