A Diff Budget for Lockfiles and Manifests

Start by enumerating every file in the repository that can change dependency resolution state, and decide which of them may appear in a pull request. Everything else that carries a resolution change gets sent back for a clean rebase or a split.

Two rules fall out of the table. First, mismatched pairs fail the check: a manifest change with no corresponding lockfile change is drift in progress, and a lockfile change with no manifest change is either a routine refresh (allowed, subject to the line cap) or tampering (blocked). The strict install commands that detect drift belong in CI, not in the reviewer's head: npm ci, yarn install --frozen-lockfile, pnpm install --frozen-lockfile, poetry check --lock, cargo check --locked (sbomify's per-ecosystem list).

Second, registry configuration files deserve their own reviewer. A one-line change to a .npmrc can repoint an entire scope at a different registry, and every line-count budget in the world will not flag a one-line change. Treat .npmrc, pip.conf, .cargo/config.toml and their equivalents as security-sensitive files that require an owner of the build or platform team, independent of size.

The allowlist also settles the recurring dispute about whether lockfiles belong in version control at all. For applications they do: npm's own guidance favors committing the generated lock so teammates, CI and deployments get identical trees, and the objection that lockfiles should not be committed applies to published libraries whose consumers ignore them anyway (when not to use package-lock.json). Write the decision down per repository type in the allowlist, so nobody relitigates it in a review thread.

Now measure. In our sample application repository, we classified every lockfile-only pull request from an automated updater over a long observation window into three buckets and recorded added-plus-removed line counts:

Routine updates stayed under 120 changed lines. Bumps that crossed a major boundary ran past 400. That gap is wide enough to be useful: a cap of 120 catches essentially all routine traffic as automatic-pass eligible, and a diff above 120 but below the major threshold is the interesting middle where reviewers should actually look.

Set the cap from your own numbers rather than ours. The method matters more than the value:

1. Export the last six months of pull requests that touched only lockfiles or only manifests.
2. Compute added plus removed lines per pull request, excluding whitespace-only churn if your lockfile format is sensitive to key ordering.
3. Sort into buckets by the semver distance of the direct dependencies involved, using the major, minor and patch rules as the classifier (SemVer 2.0.0).
4. Pick the cap at roughly the 90th percentile of the routine bucket. Anything above it needs a human.

Two refinements keep the cap from misfiring. Ignore pure reordering where your package manager serializes keys differently, otherwise a lockfile format migration will trip the budget on a change with zero resolution impact. And count the manifest and lockfile together rather than separately, because a one-line manifest change and a 300-line lockfile expansion are one change, not two.

The cap is a routing signal, not a judgment. A diff at 400 lines is not wrong; it is too big for the reviewer who has ninety seconds between meetings. Route it to a slot where that reviewer has twenty minutes, or split the update into per-package pull requests. Google's guidance that authors should split large changes into smaller cohesive ones is the same instinct applied to generated files (BSSw's summary of the Google guide).

A lockfile diff answers "what changed" but not "why". So require that every direct dependency addition lands in the pull request description in a fixed three-field format:

- name: pdf-lib
  requested: ^1.17.1
  resolved: 1.17.1
- name: @types/express
  requested: ^4.17.21
  resolved: 4.17.21

This sounds bureaucratic until you try to review a dependency upgrade without it. A reviewer needs the requested range to judge whether the author chose a sane constraint, and the resolved version to know what actually ships. Semantic versioning exists precisely so those two values carry meaning: incompatible changes move the major number, backward-compatible additions move the minor, and bug fixes move the patch (semver.org).

The in-repo tooling for this is npm ls, which lists installed dependencies and exits non-zero when the installed tree disagrees with what the manifest should resolve (npm ls for fun and insight). Two invocations cover most of the need:

# What does the manifest resolve to right now?
npm ls --depth=0

# What does a candidate package pull in, without installing it?
npm install --dry-run pdf-lib 2>&1 | grep "added [0-9]* packages"

That second command is the cheapest available smell test for a new direct dependency. Reported dry-run counts range from a single package for a minimal library to several hundred for a heavy framework, and the difference is supply chain surface area, not functionality (dependency tree nesting counts). A package that adds 300 transitive entries to a 40-package project deserves a conversation before it merges, and the dry-run count belongs in the pull request body next to the three-field block.

For a full tree view before deciding, npm ls --all prints every transitive dependency rather than only the direct ones (how to view a dependency tree).

Direct additions are a judgment call. Transitive additions get a rule, because they arrive without anyone choosing them and therefore without anyone accountable for them.

A transitive package addition blocks the merge when any one of three conditions holds:

1. New source. The resolved entry points anywhere other than the registry configured in the allowlist. This is the [email protected] attack in its general form (Snyk).
2. New lifecycle script. The added package declares a preinstall, install or postinstall script. Lifecycle scripts execute arbitrary code at install time on every developer machine and every CI runner.
3. No owner. The reviewer cannot name a person or team who would respond if that package published a malicious release tomorrow. If nobody owns it, nobody will notice.

Anything that trips none of the three passes automatically, subject to the line cap. Anything that trips one goes to a human who must write the resolution in the pull request thread: which condition fired, what was checked, and why it is acceptable. That written record is the whole point. Six months later, the note explains why the package is there; the absence of a note explains why it should not be.

Scoped overrides are the tool for making a transitive problem go away without forking. npm supports both a global override ("lodash": "4.17.21" applied everywhere) and a targeted one ("react-scripts": { "webpack": "5.74.0" } applied only inside one dependency), and the dot key applies an override to a package itself rather than to its children (npm overrides guide). Every override added to the manifest is itself a direct, reviewable decision, which is the desired outcome: the fix moves the judgment from an unreviewable generated file into a file humans read.

Three checks cover the budget. Each is small enough to read and maintain in an afternoon.

Check one, the allowlist. Fail if the diff touches dependency files outside the permitted set, or if a manifest changed without its lockfile partner:

changed=$(git diff --name-only origin/main...HEAD)

for f in $changed; do
  case "$f" in
    package.json|package-lock.json|.npmrc|pnpm-workspace.yaml) ;;
    *) echo "Unexpected dependency file: $f"; exit 1 ;;
  esac
done

if echo "$changed" | grep -qx "package.json" && \
   ! echo "$changed" | grep -qx "package-lock.json"; then
  echo "Manifest changed without lockfile. Run npm install and commit the lock."
  exit 1
fi

Check two, the line cap. Count added plus removed lines across dependency files and compare against the budget:

lines=$(git diff --numstat origin/main...HEAD -- package-lock.json package.json \
  | awk '{a+=$1; d+=$2} END {print a+d}')
echo "dependency changed lines: $lines"
[ "$lines" -gt 120 ] && echo "::warning::over lockfile budget, needs a scheduled review slot"

Check three, the transitive parser. Parse the lockfile diff into added package entries and classify each as direct or transitive by checking whether it appears in the manifest:

import json, subprocess

def manifest_direct():
    with open("package.json") as fh:
        pkg = json.load(fh)
    names = set()
    for key in ("dependencies", "devDependencies", "optionalDependencies", "peerDependencies"):
        names.update(pkg.get(key, {}).keys())
    return names

def added_lock_entries(base="origin/main"):
    diff = subprocess.run(
        ["git", "diff", f"{base}...HEAD", "--", "package-lock.json"],
        capture_output=True, text=True).stdout
    added = []
    for line in diff.splitlines():
        if line.startswith("+") and not line.startswith("+++"):
            stripped = line[1:].strip().strip(",").strip('"')
            if stripped and not stripped.startswith("{"):
                added.append(stripped)
    return added

direct = manifest_direct()
for entry in added_lock_entries():
    kind = "DIRECT" if any(entry.startswith(d) for d in direct) else "transitive"
    print(f"{kind}: {entry}")

The parser is deliberately crude: it does not need to be correct about every byte of every lockfile format, only good enough to label the entries a human will look at. Emit the output as a pull request comment, so the reviewer sees the direct additions and the transitive additions separately before opening the diff.

One automation warning. Auto-approving dependency pull requests once CI passes is common and reasonable, but the safety argument depends entirely on the test suite catching breaking behavior, and the workflow typically requires branch protection enforcing the checks before anything merges (auto-merging dependency updates). If your CI does not exercise the code path that the updated package sits under, auto-merge converts the budget into a rubber stamp. Apply auto-merge to the routine bucket only, and never to a transitive addition that trips one of the three conditions.

A rule without a path is a rule reviewers route around. Write the path down before the first pull request trips it.

Three properties make this path work. It is time-bounded, so a blocked pull request does not sit indefinitely while the author guesses. It names a role rather than a person where possible, so holidays and departures do not stall it. It always produces a written artifact, because the record is what stops the same package from being re-litigated next quarter.

Google's guidance on resolving disagreements is useful here: try to reach consensus based on the written guidance, escalate to a technical lead or code owner if that fails, and record the outcome as a comment for future readers (review standard, conflicts section). The budget document is that written guidance, and the three conditions are the consensus it encodes.

When a transitive addition turns out to be a real vulnerability rather than a hop-through, the fix belongs in the manifest as a scoped override, tracked as its own reviewable change (npm overrides guide). When it turns out to be a package nobody needs, the honest answer is usually to drop the direct dependency that dragged it in.

For teams running coding agents that edit manifests and lockfiles on their own, a skill that installs the allowlist and the parser into the agent's workflow keeps the budget enforced at the point of generation rather than at review. Teams that want the analysis, the parser and the escalation notes drafted from a repository's own history can put that work in front of an expert through Quanta Experts, and teams evaluating models to run this kind of diff classification behind one API key can start at Quanta Inference.