@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

npm install -g @sergiovalerdev/dependency-validator

Or as a dev dependency:

npm install -D @sergiovalerdev/dependency-validator

CLI Usage

# 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

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

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

npm scripts

{
  "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