depdig

Trace every dependency path from your project to a vulnerable package, and simulate whether a fix upgrade is actually installable.

Install

npm install -g @sam-parsons/depdig

Or run without installing:

npx @sam-parsons/depdig --package minimatch --fix ">=10.2.1"

Package name and command

The npm package is @sam-parsons/depdig, but the executable on your PATH is still depdig (see the bin field in package.json). Use the scoped name with npm install / npx; use depdig once the CLI is installed globally.

Usage

depdig --package <name> --fix <range> [options]

--package and --fix are required unless you pass --paths-only.

Examples

The commands below assume a global install so depdig is on your PATH. To run the same invocations without installing, replace depdig with npx @sam-parsons/depdig.

# Show all dependency chains to minimatch and simulate the fix upgrade
depdig --package minimatch --fix ">=10.2.1"

# Offline: just print the chains, skip registry lookups
depdig -p minimatch --fix ">=10.2.1" --paths-only

# Machine-readable JSON output
depdig -p minimatch --fix ">=10.2.1" --json

# One-line summary (useful in CI logs)
depdig -p minimatch --fix ">=10.2.1" --quiet

Flags

| Flag | Alias | Default | Description | |---|---|---|---| | --package | -p | — | Package name to trace (e.g. minimatch) | | --fix | | — | Semver range the fixed version must satisfy (e.g. ">=10.2.1") | | --paths-only | | false | Print dependency chains only; skip registry lookups (offline) | | --json | | false | Output as JSON | | --quiet | -q | false | Single summary line; suppress per-path detail | | --lockfile | | auto | Path to a specific lockfile (otherwise walks up from cwd) | | --node-version | | auto | Override the Node version used for engine compatibility checks | | --no-color | | — | Disable ANSI colour output |

Lockfile auto-detection

When --lockfile is not provided, depdig walks up from the current working directory looking for package-lock.json, then yarn.lock, then pnpm-lock.yaml. The first match wins.

Exit codes

| Code | Meaning | |---|---| | 0 | All paths have a viable fix | | 1 | At least one path has no fix in the registry for the given range | | 2 | The target package was not found in the dependency tree | | 3 | The lockfile could not be found or parsed |

Private registries and .npmrc

depdig uses pacote for registry lookups. It reads .npmrc from the project root (the directory containing your lockfile), so any registry URLs and auth tokens configured there are picked up automatically — the same way npm install would use them.

# .npmrc
registry=https://registry.mycompany.com/
//registry.mycompany.com/:_authToken=${MY_NPM_TOKEN}

No extra configuration is needed. If your project already works with npm install, depdig will use the same registry.

Publishing (maintainers)

From a clean main (git pull, no extra commits you do not want released), logged in to npm (npm whoami):

• npm run release — runs prepublish:check (via preversion), bumps the patch version (package.json + package-lock.json), creates a git commit and tag, npm publish (scoped package uses publishConfig.access: public), then git push and git push --follow-tags.
• npm run release:minor / npm run release:major — same flow for semver minor or major bumps.

npm publish by itself does not bump the version; npm always publishes whatever version is already in package.json. Use release when you want bump + publish in one step.

To verify the tarball without releasing: npm run prepublish:check.

Requirements

• Node.js >= 18
• A package-lock.json, yarn.lock, or pnpm-lock.yaml in the project