dep-delta

Review dependency update PRs by blast radius, not vibes.

Chinese

dep-delta turns noisy npm package-lock.json updates into a dependency risk report. It highlights major version jumps, direct dependency impact, package count changes, newly introduced lifecycle install scripts, new binary entry points, and CI thresholds you can fail on.

v0.1 supports npm package-lock.json v2/v3 only.

Why

Dependabot and Renovate are great at opening dependency PRs, but the human reviewer still has to answer: "What actually changed, and how risky is it?"

npm lockfiles are intentionally complete: npm says package locks describe the exact dependency tree, support reproducible installs, and provide visibility into tree changes through source control diffs. That completeness is useful, but a raw lockfile diff is still the wrong interface when a dependency bot changes dozens of transitive packages.

Existing tools such as diff-package-lock and lockfile-diff focus on making lockfile diffs easier to read. dep-delta focuses on review risk: what should block merge, what needs a closer look, and what can be safely auto-merged behind a risk budget.

Research notes: docs/research.md

References:

• npm package-lock.json docs
• GitHub Dependabot version updates
• Renovate docs

Install-Free Usage

Run against two lockfiles:

npx --yes git+https://github.com/luoowei/dep-delta.git --before old-package-lock.json --after package-lock.json

Run inside a PR checkout:

npx --yes git+https://github.com/luoowei/dep-delta.git --base origin/main --head HEAD

Fail CI when the dependency update is too risky:

npx --yes git+https://github.com/luoowei/dep-delta.git --before old.json --after new.json --fail-on-score 70

Write a Markdown report:

npx --yes git+https://github.com/luoowei/dep-delta.git --base origin/main --head HEAD --write-report

Print JSON for bots:

npx --yes git+https://github.com/luoowei/dep-delta.git --before old.json --after new.json --json

Example Output

dep-delta Dependency Blast Radius
Risk: HIGH (100/100)
Packages: 3 -> 4 (+1)
Changes: 2 added, 1 removed, 2 updated
Direct changed: 3 | Major: 1 | Lifecycle scripts: 1

Top dependency changes:
- core: updated 1.2.3 -> 2.0.0 (major, score 83)
  Reasons: major version update; direct dependency changed; production dependency; bin entry point added
- runner: added - -> 1.0.0 (added, score 53)
  Reasons: direct dependency changed; production dependency; lifecycle script introduced; new package added

What It Checks

• Added, removed, and updated packages
• Direct versus transitive dependency changes
• Production, development, optional, and transitive scopes
• Major, minor, and patch version movement
• New or removed bin command entry points
• New lifecycle install hooks, including npm hasInstallScript metadata
• Large lockfile blast radius
• CI risk gates by score or level

CLI

dep-delta --before old-package-lock.json --after new-package-lock.json
dep-delta --base origin/main --head HEAD [--file package-lock.json]

Options:
  --before <file>         Previous package-lock.json.
  --after <file>          New package-lock.json.
  --base <git-ref>        Git ref containing the previous lockfile.
  --head <git-ref>        Git ref containing the new lockfile. Defaults to HEAD with --base.
  --file <path>           Lockfile path for git refs. Defaults to package-lock.json.
  --json                  Print machine-readable JSON.
  --write-report          Write DEP_DELTA_REPORT.md.
  --out-dir <path>        Directory for reports. Defaults to current directory.
  --fail-on <level>       Exit 1 when risk level is at least low, medium, or high.
  --fail-on-score <n>     Exit 1 when risk score is at least n.

GitHub Actions

name: Dependency blast radius

on:
  pull_request:
    paths:
      - package-lock.json

jobs:
  dep-delta:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx --yes git+https://github.com/luoowei/dep-delta.git --base origin/${{ github.base_ref }} --head HEAD --write-report --fail-on-score 70
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: dep-delta-report
          path: DEP_DELTA_REPORT.md

Local Development

npm test
node ./bin/dep-delta.js --help

Roadmap

• PR comment output for GitHub Actions
• pnpm and Yarn lockfile support
• Package age, maintainer, and download signals
• SARIF output for code scanning dashboards
• Auto-merge recommendation profiles for Dependabot and Renovate

License

MIT