Pastoralist keeps dependency overrides explainable, current, and removable.

If your package.json has overrides or resolutions, Pastoralist records why they exist, which packages still need them, and when they can be removed. It can also connect security fixes, patch files, workspaces, and CI checks to the same audit trail.

npm install pastoralist --save-dev
npx pastoralist --init

Add it to postinstall so the appendix stays current after installs:

{
  "scripts": {
    "postinstall": "pastoralist"
  }
}

Or let Pastoralist add the hook for you:

npx pastoralist --setup-hook

Overrides are useful, but they usually lose context:

{
  "overrides": {
    "lodash": "4.17.21"
  }
}

Pastoralist adds the missing record:

{
  "overrides": {
    "lodash": "4.17.21"
  },
  "pastoralist": {
    "appendix": {
      "lodash@4.17.21": {
        "dependents": {
          "my-app": "lodash@^4.17.0"
        },
        "ledger": {
          "reason": "Security vulnerability CVE-2021-23337",
          "securityProvider": "osv",
          "keep": true
        }
      }
    }
  }
}

The fix is not just the version. The fix is the record of why that version exists.

• Tracks npm and Bun overrides, pnpm pnpm.overrides, and Yarn resolutions
• Shows which direct or workspace packages still depend on each override
• Cleans stale overrides with --remove-unused
• Links patch-package patch files to the overrides they support
• Checks security advisories with OSV, GitHub Dependabot alerts, npm audit, Snyk, Socket, or Spektion
• Supports monorepos through workspaces, depPaths, overridePaths, and resolutionPaths
• Provides CI-friendly output with --dry-run, --quiet, --summary, and --outputFormat json

# Update the appendix
npx pastoralist

# Preview package.json changes
npx pastoralist --dry-run

# Remove overrides no package still needs
npx pastoralist --remove-unused

# Check advisories with the default OSV provider
npx pastoralist --checkSecurity

# Fail CI on security check errors
npx pastoralist --checkSecurity --strict

# Minimal CI output; exits 1 when vulnerabilities are found
npx pastoralist --quiet --checkSecurity

# Print package, override, and vulnerability metrics
npx pastoralist --summary

Pastoralist can be configured in package.json, .pastoralistrc.json, pastoralist.config.js, or pastoralist.config.ts.

{
  "pastoralist": {
    "depPaths": "workspace",
    "checkSecurity": true,
    "security": {
      "provider": "osv",
      "severityThreshold": "medium",
      "hasWorkspaceSecurityChecks": true
    }
  }
}

For full options, see Configuration.

name: Override Check
on: [pull_request]

jobs:
  pastoralist:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: yowainwright/pastoralist@v1
        with:
          mode: check
          fail-on-security: true

The action can validate, update files, or open maintenance PRs. See the GitHub Action docs or ACTION.md.

• Setup
• API Reference
• Configuration
• Security
• Workspaces
• Architecture

Shout out to Bryant Cabrera and Mardin for the conversation, insight, and pairing around this topic.

Made by @yowainwright. O'Sassy, 2022.