Introduction to Pastoralist

Pastoralist keeps dependency overrides explainable, current, and removable

Pastoralist is the audit trail for package manager overrides.

If your project uses overrides, pnpm.overrides, or resolutions, Pastoralist records why each entry exists, which packages still need it, and when it can be removed. It can also connect security fixes, patch files, workspace packages, and CI checks to the same record.

Why This Matters

Overrides usually start with a good reason:

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

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

Months later, the context is gone. Was it a security fix? A transitive bug? Who still needs it? Is it safe to remove? The override should stay as the package manager instruction; the appendix carries the review detail:

{
  "overrides": {
    "lodash": "4.17.21"
  },
  "pastoralist": {
    "appendix": {
      "[email protected]": {
        "dependents": {
          "web-app": "lodash@^4.17.20",
          "admin-ui": "lodash@^4.17.19"
        },
        "ledger": {
          "addedDate": "2026-05-06T00:00:00.000Z",
          "reason": "Pin lodash to a patched version while workspace packages finish upgrades.",
          "source": "manual",
          "securityChecked": true,
          "securityProvider": "osv",
          "cves": ["CVE-2021-23337"],
          "cveDetails": [
            {
              "cve": "CVE-2021-23337",
              "severity": "high",
              "patchedVersion": "4.17.21"
            }
          ],
          "severity": "high",
          "vulnerableRange": "<4.17.21",
          "patchedVersion": "4.17.21",
          "keep": {
            "reason": "Keep until each workspace requests lodash 4.17.21 or newer.",
            "untilVersion": "4.17.21"
          }
        }
      }
    }
  }
}

{
  "overrides": {
    "lodash": "4.17.21"
  },
  "pastoralist": {
    "appendix": {
      "[email protected]": {
        "dependents": {
          "web-app": "lodash@^4.17.20",
          "admin-ui": "lodash@^4.17.19"
        },
        "ledger": {
          "addedDate": "2026-05-06T00:00:00.000Z",
          "reason": "Pin lodash to a patched version while workspace packages finish upgrades.",
          "source": "manual",
          "securityChecked": true,
          "securityProvider": "osv",
          "cves": ["CVE-2021-23337"],
          "cveDetails": [
            {
              "cve": "CVE-2021-23337",
              "severity": "high",
              "patchedVersion": "4.17.21"
            }
          ],
          "severity": "high",
          "vulnerableRange": "<4.17.21",
          "patchedVersion": "4.17.21",
          "keep": {
            "reason": "Keep until each workspace requests lodash 4.17.21 or newer.",
            "untilVersion": "4.17.21"
          }
        }
      }
    }
  }
}

The override controls the installed version. The appendix explains why that control exists, who still depends on it, what scanner or reviewer justified it, and what condition makes it removable.

What Pastoralist Handles

Tracks npm and Bun overrides, pnpm pnpm.overrides, and Yarn resolutions
Shows which direct or workspace packages still depend on each override
Removes stale overrides with --remove-unused
Links patch-package 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

At A Glance

Area	Details
Package managers	npm, pnpm, Yarn, Bun
Runtime	Node 20+
Security default	OSV, no token required
Optional providers	GitHub, npm audit, Snyk, Socket, Spektion
Monorepos	Auto-detects `workspaces`; accepts explicit package globs
CI	CLI flags plus a GitHub Action
Test surface	1,700+ test cases across unit, integration, and e2e fixtures

When To Use It

Use Pastoralist when your project has overrides that need a durable reason, a regular cleanup path, or a security audit trail.

It is designed to sit beside tools such as npm audit, Dependabot, Renovate, patch-package, syncpack, and depcheck. Those tools find or apply dependency changes. Pastoralist keeps the resulting overrides from becoming invisible technical debt.

Start Here

npm install pastoralist --save-dev
npx pastoralist init

npm install pastoralist --save-dev
npx pastoralist init

Then add it to postinstall:

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

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

Continue with the setup guide, or try a sandbox: