Dependency Risk Scanner - CLI Documentation

The Dependency Risk scanner extends core dependency analysis with risk classification signals. It identifies packages that may cause upgrade friction, require special build environments, or pose maintenance concerns.

Risk Classifications

Each dependency receives a risk classification based on multiple factors:

Risk Level	Indicator	Criteria
🔴 Critical	Immediate action	Deprecated with known vulnerabilities, EOL runtime dependencies
🟠 High	Plan remediation	Deprecated packages, unmaintained (>2 years), major version lag
🟡 Medium	Monitor	Native modules, platform-specific, single maintainer
🟢 Low	Normal	Standard packages, actively maintained, widely used

Detection Categories

Deprecated Packages

Packages flagged via the npm registry deprecated field:

{
  "deprecated": [
    {
      "name": "request",
      "version": "2.88.2",
      "deprecatedSince": "2020-02-11",
      "message": "request has been deprecated, see https://github.com/request/request/issues/3142",
      "risk": "high"
    }
  ]
}

Native Modules

Packages requiring native compilation, which may cause CI issues:

Detection Method	Examples
`node-gyp` in install scripts	`bcrypt`, `sqlite3`
Known native package list	`sharp`, `canvas`, `libxmljs`
`gypfile: true` in package.json	Community packages

Platform-Specific

Packages with OS or architecture constraints:

Package	Platform	Notes
`fsevents`	macOS only	Used by file watchers
`win-ca`	Windows only	Certificate store access
`@esbuild/*`	Architecture-specific	Prebuilt binaries

Use Cases

Pre-Migration Assessment

Before major upgrades, identify packages that will need attention:

vg scan --format json | jq '.dependencyRisk | .deprecated + .nativeModules'

Security Triage

Prioritize deprecated package replacements:

Critical/High risk: Replace immediately
Medium risk: Add to next sprint backlog
Low risk: Monitor for changes

CI Environment Planning

For packages in nativeModules:

Ensure build tools are installed (build-essential, python3)
Consider using prebuilt Docker images
Cache native compilation results

Example Output

{
  "dependencyRisk": {
    "summary": {
      "critical": 0,
      "high": 2,
      "medium": 4,
      "low": 156
    },
    "deprecated": [
      {
        "name": "request",
        "version": "2.88.2",
        "risk": "high",
        "deprecatedSince": "2020-02-11",
        "alternatives": ["node-fetch", "undici", "got"]
      },
      {
        "name": "node-sass",
        "version": "7.0.3",
        "risk": "high",
        "deprecatedSince": "2020-03-26",
        "alternatives": ["sass"]
      }
    ],
    "nativeModules": [
      {
        "name": "sharp",
        "version": "0.33.2",
        "risk": "medium",
        "buildRequirements": ["libvips"]
      },
      {
        "name": "bcrypt",
        "version": "5.1.1",
        "risk": "medium",
        "buildRequirements": ["node-gyp", "python3"]
      }
    ],
    "platformSpecific": [
      {
        "name": "fsevents",
        "version": "2.3.3",
        "risk": "low",
        "platform": "darwin",
        "notes": "Optional dependency, ignored on non-macOS"
      }
    ]
  }
}

Configuration

// vibgrate.config.ts
const config: VibgrateConfig = {
  scanners: {
    dependencyRisk: {
      enabled: true,
      // Suppress warnings for known acceptable packages
      ignore: ['fsevents'], // macOS-only, expected
    },
  },
};