dependencies

Dependencies

Overview

Dependencies are the part of the codebase the team did not write but ships anyway. Done well, the dependency graph reproduces deterministically, every reference is immutable, advisories are gated in CI, and license posture is documented. Done poorly, an unpinned transitive can change the build silently between two CI runs, and a moved tag can swap a maintainer without anyone noticing.

Core principle: The dependency graph is small, reproducible, reviewable, and audited. Provenance and integrity are joined; if you cannot answer where a dependency came from, you cannot answer whether it is safe to ship. Each dependency is presumed to need a justification, not the other way around: fewer, shallower trust relationships beat more, deeper ones, and lightweight entry points stay at zero.

Core Principles

1. The lockfile pins what the manifest does not

A manifest declares the top of the graph; a lockfile pins everything beneath it. Without a committed lockfile, every install resolves the graph fresh, so two contributors (or two CI runs) install different transitive trees from the same manifest. Reproducibility, the precondition for both debugging and supply-chain auditing, is gone.

Multiple valid pinning styles exist: exact pins on direct dependencies, or ranges-with-lockfile. The principle is: the resolved graph reproduces deterministically. The red flag is "graph does not reproduce," not "did not pin every direct dep to an exact version."

Multiple valid lockfile-commit policies exist: always-committed (the conventional default), or CI-generated and verified. Either is defensible; pick one and apply it consistently.

2. No floating ranges without a lockfile

Caret, tilde, or wildcard ranges on direct dependencies in an ecosystem with no committed lockfile mean a transitive change in any sub-dependency can ship to production without anyone noticing. A floating range plus no lockfile turns external maintainers into uncredentialed committers on your build.

3. Every external mutable reference is immutable-pinned

This principle scopes to anything the project pulls from outside its own repo where the reference can be moved server-side: dependencies from a git URL or tarball URL, GitHub Actions in CI, container base images, and submodules. When the scope applies: pin to an immutable reference (a commit SHA, a content digest), not a tag or branch.

A tag can be moved. A branch certainly can. The XZ-utils backdoor (CVE-2024-3094, 2024) demonstrated the tag-repointing path against a CI Action: a maintainer with social-engineered trust silently moves the tag, and every repo using the tag executes attacker code on the next push with no diff in their own repository. The same mechanism applies to git+https://...#main, to FROM debian:stable, and to git submodule references that track a branch.

# SAFE: SHA cannot be repointed; an update produces a reviewable diff.
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4

# UNSAFE: tag can be moved server-side overnight.
- uses: actions/checkout@v4

Cross-reference: the continuous-delivery skill carries the gate-enforcement side; this skill carries the immutable-reference shape that makes the gate trustworthy.

4. Track maintenance signals on direct dependencies

A direct dependency whose upstream has had no release in two years, is archived, has a single maintainer who has gone silent, or whose homepage 404s is a CVE incubator and a future incident. Trust shifts in projects whose maintenance signals have already degraded; the historical record is consistent on this point. Cross-reference: the purpose-and-scope skill carries the upstream check on whether the dependency belongs in the project at all, which precedes the maintenance-signal check this skill carries.

5. Audit the transitive surface in CI

The bulk of vulnerabilities reachable from an application live in transitive dependencies the team never directly chose. A CI step that scans the resolved tree against an advisory database is non-negotiable for any project past the prototype stage. Without an audit gate, vulnerabilities accumulate silently between scans.

This principle scopes to projects with CI; cross-reference the security skill for the runtime-CVE side of the same gate, and the continuous-delivery skill for the gate-enforcement and pinned-action discipline that makes this audit step a reviewed and trustworthy step of the pipeline.

6. One version per dependency in a workspace (scope: monorepos)

This principle scopes to monorepos and workspace-style projects. When the scope applies: a given dependency resolves to a single version across all workspace packages. Version skew inside a single deployable unit means two copies of the same library ship together, doubling attack surface and silently changing behavior at module boundaries. Drift here also defeats license-audit and CVE tooling, which assumes one resolved version per name.

7. Lockfiles are reviewable

A lockfile is a code-review artifact: a reviewer must be able to tell whether a PR is bumping one patch version or quietly swapping a maintainer. Binary-only lockfiles save bytes but make the supply chain opaque to code review; a four-line dependency change and a four-thousand-line one look identical in git diff.

This principle scopes to ecosystems that admit binary lockfiles; in ecosystems with text-only lockfiles it is satisfied by construction. Where the scope applies, commit a paired text-format lockfile alongside the binary one.

8. License posture is declared and gated

License obligations are contractual; a copyleft transitive in a closed-source product can force disclosure or relicensing. A license audit step in CI, plus a documented allowlist or denylist, makes the obligation explicit. Provenance and licensing are joined: the same posture that answers "where did this come from" answers "are we allowed to ship it."

9. Quarantine new versions before adoption

Newly published versions of any dependency carry the highest probability of malicious or broken content per unit time. Account-takeover attacks, postinstall payloads, and accidental releases concentrate in the first hours-to-days after publish, before the wider ecosystem has a chance to surface advisories. A cooldown window (a hold of 48 hours to 1 week before a new version is allowed to land in the lockfile) buys the project the benefit of the rest of the ecosystem's scrutiny without writing any of it.

The mechanism is a constraint on the dependency-update bot, not a manual gate: Renovate's minimumReleaseAge, Dependabot's cooldown, or an equivalent. The constraint applies to every direct and transitive dependency, not just the ones the team thinks are risky. The litellm 1.82.8 incident (2026) and the Shai-Halud campaign (2025) both compromised packages where versions inside the cooldown window would have been quarantined long enough for the malicious release to be yanked before any production install picked it up.

A cooldown is not a substitute for the audit gate (principle 5); it is a multiplier on it. The audit catches what is known; the cooldown buys the time during which an unknown becomes a known.

10. Minimize the dependency surface; prefer shallow trees

Every dependency is a trust relationship; every transitive dependency is a trust relationship the team did not explicitly agree to. The durable answer to most dependency-related risk is fewer dependencies, not better ones, and shallower trees rather than deeper ones.

Heuristics that make this principle operational:

• Zero dependencies for lightweight entry points. Setup CLIs, install scripts, and other surfaces every user touches first should ship with no runtime dependencies at all. The supply chain risk on those entry points dominates the engineering cost of writing the few lines yourself. Field example: the syntropic137-npx setup package enforces a strict zero-dependency rule for exactly this reason. Cross-reference: the developer-experience skill carries the single-command-onboarding stance that makes setup CLIs valuable in the first place; the supply-chain stance here is what keeps that command trustworthy.
• Prefer one-layer-deep over deep transitive trees. A direct dependency that itself has zero dependencies (Zod is the canonical example) is materially safer than one that pulls in a hundred transitives. When evaluating two libraries that solve the same problem, the transitive count is a first-class signal. A package with three direct deps that pulls in 150 transitives is a red flag; a package that solves 80% of the problem with zero transitives is usually the right choice.
• Plan dependencies at design time, not at coding time. In the AI-assisted era, "I need this small utility" is no longer the same as "I need to add this package." A 50-line utility the project owns and reviews is safer than a package with hundreds of transitives. The default move is to write the helper, not to install the package; the package is the answer when the problem is large or genuinely shared.
• Question heavy transitive trees. pnpm why <package>, uv tree --depth 3, and equivalents make the tree visible. Any dependency that visibly inflates the tree should earn its keep; if the choice is between two libraries with similar value, the one with the smaller blast radius wins.
• Watch for abandonware adjacency. A direct dependency on a small, single-maintainer transitive is a maintenance bet whether the team made it explicitly or not. Cross-reference principle 4 (maintenance signals); the count and the maintenance posture compound.

This principle is not a vow of poverty; large, well-maintained dependencies (frameworks, runtimes, ORM

Content truncated.