Dependency Management

Overview

Every dependency is a commitment -- to its maintenance, security surface, and upgrade path. Add deliberately, update strategically, audit regularly.

Core principle: Every dependency decision should be justified. Don't add what you can write. Don't ignore what you can update. Don't skip what you can audit.

When to Use

• Adding a new package or library to a project
• Security audit warnings (npm audit, pip-audit, cargo audit, etc.)
• Batch dependency update time
• Major version upgrade decisions
• Choosing between alternative libraries
• Lockfile merge conflicts
• Questioning if a package is still maintained

Don't use when:

• Internal module/code organization (that's refactoring)
• Learning a single package's API (that's research)

Decision Tree

digraph dependency_decision {
    "What dependency decision?" [shape=diamond];
    "Add new package" [shape=box];
    "Update existing" [shape=box];
    "Security alert" [shape=box];
    "Remove package" [shape=box];

    "Evaluation Criteria" [shape=box, style=filled, fillcolor=lightyellow];
    "Update Type?" [shape=diamond];
    "Urgency Matrix" [shape=box, style=filled, fillcolor=lightyellow];
    "Usage check, remove" [shape=box];

    "Patch" [shape=box];
    "Minor" [shape=box];
    "Major" [shape=box];

    "What dependency decision?" -> "Add new package";
    "What dependency decision?" -> "Update existing";
    "What dependency decision?" -> "Security alert";
    "What dependency decision?" -> "Remove package";

    "Add new package" -> "Evaluation Criteria";
    "Update existing" -> "Update Type?";
    "Security alert" -> "Urgency Matrix";
    "Remove package" -> "Usage check, remove";

    "Update Type?" -> "Patch" [label="x.x.Z"];
    "Update Type?" -> "Minor" [label="x.Y.0"];
    "Update Type?" -> "Major" [label="X.0.0"];
}

New Package Evaluation

Before adding any dependency, evaluate against all seven criteria:

Rule of thumb: If a package fails two or more criteria, find an alternative or write it yourself.

Update Strategy

Workflow for batch updates:

1. Update patch versions first, run tests, commit
2. Update minor versions one by one, run tests after each
3. Tackle major versions individually on feature branches
4. Never batch major updates together -- isolate each one

Security Urgency Matrix

When a security audit reports vulnerabilities:

1. Run the audit tool for your ecosystem (npm audit, pip-audit, cargo audit, bundler-audit)
2. Classify each finding using the matrix above
3. Address critical/exploitable issues before any other work
4. Document accepted risks for findings you cannot immediately resolve

Lockfile & Pinning Rules

• Always commit lockfiles (package-lock.json, yarn.lock, poetry.lock, Cargo.lock, etc.)
• Pin exact versions for production dependencies where possible
• Use ranges only for libraries (not applications)
• Never manually edit lockfiles -- use package manager commands
• After resolving lockfile merge conflicts, always run install to regenerate

Common Mistakes

Removing a Dependency

Before removing a package:

1. Search the codebase for all imports and usages
2. Check if other dependencies rely on it transitively
3. Remove the import statements and package reference, then run the full test suite
4. Verify the lockfile is cleanly regenerated after removal

Related Skills

• security-review -- For auditing vulnerable and outdated components (OWASP A06)
• systematic-debugging -- For diagnosing issues introduced by dependency updates
• verification-before-completion -- For confirming dependency changes do not break the build