Dependency Management — Production Patterns Modern Best Practices (January 2026) : Lockfile-first workflows, automated security scanning (Dependabot, Snyk, Socket.dev), semantic versioning, minimal dependencies principle, monorepo workspaces (pnpm, Nx, Turborepo), supply chain security (SBOM, AI BOM, Sigstore), reproducible builds, and AI-generated code validation. --- When to Use This Skill The agent should invoke this skill when a user requests: - Adding new dependencies to a project - Updating existing dependencies safely - Resolving dependency conflicts or version mismatches - Auditing de…

\nexclude = '''\n/(\n \\.git\n | \\.venv\n | \\.eggs\n | build\n | dist\n)/\n'''\n\n# Ruff configuration (Python linter)\n[tool.ruff]\nline-length = 100\ntarget-version = \"py312\"\nselect = [\n \"E\", # pycodestyle errors\n \"W\", # pycodestyle warnings\n \"F\", # pyflakes\n \"I\", # isort\n \"B\", # flake8-bugbear\n \"C4\", # flake8-comprehensions\n]\nignore = [\"E501\"] # line too long (handled by black)\n\n[tool.ruff.isort]\nknown-first-party = [\"project\"]\n\n# Pytest configuration\n[tool.pytest.ini_options]\ntestpaths = [\"tests\"]\npython_files = [\"test_*.py\", \"*_test.py\"]\npython_classes = [\"Test*\"]\npython_functions = [\"test_*\"]\naddopts = [\n \"--strict-markers\",\n \"--cov=project\",\n \"--cov-report=term-missing\",\n \"--cov-report=html\",\n \"--cov-report=xml\",\n \"-v\",\n]\n\n# MyPy configuration\n[tool.mypy]\npython_version = \"3.12\"\nwarn_return_any = true\nwarn_unused_configs = true\ndisallow_untyped_defs = true\ndisallow_incomplete_defs = true\ncheck_untyped_defs = true\nno_implicit_optional = true\nwarn_redundant_casts = true\nwarn_unused_ignores = true\nstrict_equality = true\n\n[[tool.mypy.overrides]]\nmodule = \"tests.*\"\ndisallow_untyped_defs = false\n\n# Coverage configuration\n[tool.coverage.run]\nsource = [\"project\"]\nomit = [\"tests/*\", \"**/__pycache__/*\"]\n\n[tool.coverage.report]\nexclude_lines = [\n \"pragma: no cover\",\n \"def __repr__\",\n \"raise AssertionError\",\n \"raise NotImplementedError\",\n \"if __name__ == .__main__.:\",\n]\n","content_type":"text/plain; charset=utf-8","language":"toml","size":3161,"content_sha256":"3a4efafc4cb0b76a1e5e2dbf70188ccfc188b342c83ef1cd94f5f3f29ecae466"},{"filename":"data/sources.json","content":"{\n \"metadata\": {\n \"title\": \"Dependency Management - Sources\",\n \"description\": \"Primary sources for lockfiles, reproducible builds, vulnerability management, SBOMs, AI BOM, and supply-chain security\",\n \"last_updated\": \"2026-01-17\"\n },\n \"package_managers\": [\n {\n \"name\": \"npm Documentation\",\n \"url\": \"https://docs.npmjs.com/\",\n \"description\": \"Official npm docs (install, lockfiles, workspaces, auditing)\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"pnpm Documentation\",\n \"url\": \"https://pnpm.io/\",\n \"description\": \"pnpm docs (workspaces, store, overrides)\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"Python Packaging User Guide (PyPA)\",\n \"url\": \"https://packaging.python.org/\",\n \"description\": \"Authoritative Python packaging guidance\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"Poetry Documentation\",\n \"url\": \"https://python-poetry.org/docs/\",\n \"description\": \"Poetry dependency management and lockfile usage\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"Cargo Book\",\n \"url\": \"https://doc.rust-lang.org/cargo/\",\n \"description\": \"Rust Cargo reference (lockfiles, features, publishing)\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"Go Modules Reference\",\n \"url\": \"https://go.dev/ref/mod\",\n \"description\": \"Go module system reference\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"uv Documentation (Astral)\",\n \"url\": \"https://docs.astral.sh/uv/\",\n \"description\": \"Fast Python package manager that can replace pip/virtualenv in many workflows; verify current feature parity vs Poetry for your use case\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"Bun Package Manager\",\n \"url\": \"https://bun.sh/docs/cli/install\",\n \"description\": \"JavaScript runtime with built-in package manager; verify current ecosystem maturity and compatibility for production use\",\n \"add_as_web_search\": true\n }\n ],\n \"versioning_and_reproducibility\": [\n {\n \"name\": \"Semantic Versioning 2.0.0\",\n \"url\": \"https://semver.org/\",\n \"description\": \"SemVer specification\",\n \"add_as_web_search\": false\n },\n {\n \"name\": \"npm - package-lock.json\",\n \"url\": \"https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json\",\n \"description\": \"Official npm lockfile documentation\",\n \"add_as_web_search\": true\n }\n ],\n \"vulnerability_management\": [\n {\n \"name\": \"Open Source Vulnerabilities (OSV)\",\n \"url\": \"https://osv.dev/\",\n \"description\": \"Open vulnerability database and API for OSS ecosystems\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"GitHub Advisory Database\",\n \"url\": \"https://github.com/advisories\",\n \"description\": \"Security advisories for open source vulnerabilities\",\n \"add_as_web_search\": true\n }\n ],\n \"supply_chain_security\": [\n {\n \"name\": \"NIST SP 800-218 (SSDF)\",\n \"url\": \"https://csrc.nist.gov/publications/detail/sp/800-218/final\",\n \"description\": \"Secure Software Development Framework\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"SLSA v1.0 Specification\",\n \"url\": \"https://slsa.dev/spec/v1.0/\",\n \"description\": \"Supply-chain Levels for Software Artifacts (build provenance)\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"SPDX\",\n \"url\": \"https://spdx.dev/\",\n \"description\": \"SPDX SBOM standard (ISO/IEC)\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"CycloneDX\",\n \"url\": \"https://cyclonedx.org/\",\n \"description\": \"CycloneDX SBOM standard\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"Sigstore\",\n \"url\": \"https://www.sigstore.dev/\",\n \"description\": \"Signing and verifying software artifacts (cosign, fulcio, rekor)\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"OpenSSF Scorecard\",\n \"url\": \"https://securityscorecards.dev/\",\n \"description\": \"Automated security health metrics for open source projects\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"CISA SBOM Resources\",\n \"url\": \"https://www.cisa.gov/sbom\",\n \"description\": \"CISA SBOM minimum elements and federal requirements (2025 update)\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"EU Cyber Resilience Act (CRA)\",\n \"url\": \"https://digital-strategy.ec.europa.eu/en/policies/cyber-resilience-act\",\n \"description\": \"EU regulation requiring SBOMs for software products (effective Dec 2027)\",\n \"add_as_web_search\": true\n }\n ],\n \"tools\": [\n {\n \"name\": \"Syft (SBOM generator)\",\n \"url\": \"https://github.com/anchore/syft\",\n \"description\": \"Generate SBOMs from container images and filesystems\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"Grype (vulnerability scanner)\",\n \"url\": \"https://github.com/anchore/grype\",\n \"description\": \"Scan container images and filesystems for known vulnerabilities\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"Renovate\",\n \"url\": \"https://docs.renovatebot.com/\",\n \"description\": \"Automated dependency updates (highly configurable)\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"Dependabot\",\n \"url\": \"https://github.com/dependabot\",\n \"description\": \"Automated dependency updates and security alerts\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"Socket.dev\",\n \"url\": \"https://socket.dev/\",\n \"description\": \"Supply chain security platform detecting malicious packages\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"OWASP Dependency-Track\",\n \"url\": \"https://dependencytrack.org/\",\n \"description\": \"Continuous SBOM analysis platform for component risk identification\",\n \"add_as_web_search\": true\n }\n ],\n \"ai_supply_chain\": [\n {\n \"name\": \"Endor Labs - State of Dependency Management 2025\",\n \"url\": \"https://www.endorlabs.com/lp/state-of-dependency-management-2025\",\n \"description\": \"Research on AI coding agent risks in software supply chain\",\n \"add_as_web_search\": true\n },\n {\n \"name\": \"AI BOM Concept (SD Times)\",\n \"url\": \"https://sdtimes.com/ai/from-sbom-to-ai-bom-rethinking-supply-chain-security-for-ai-native-software/\",\n \"description\": \"Extended SBOM for AI-native systems (models, datasets, training artifacts)\",\n \"add_as_web_search\": true\n }\n ],\n \"optional_ai\": [\n {\n \"name\": \"Automated PR triage and summarization (Optional)\",\n \"url\": \"https://docs.github.com/en/copilot\",\n \"description\": \"Optional AI assistance for PR summaries (requires human review; product features vary)\",\n \"add_as_web_search\": true,\n \"optional\": true\n }\n ]\n}\n","content_type":"application/json; charset=utf-8","language":"json","size":6767,"content_sha256":"2793533de84a8dd714ee76cac22ec5b6dbf4e4840b527c2aab7ac6c62d4c8eac"},{"filename":"references/anti-patterns.md","content":"# Dependency Management Anti-Patterns\n\n**When to Use**: Learn what NOT to do when managing dependencies to avoid common pitfalls.\n\n---\n\n## Overview\n\nAnti-patterns are common practices that seem helpful but actually cause problems. This guide covers the most damaging dependency management anti-patterns and how to avoid them.\n\n---\n\n## Critical Anti-Patterns (NEVER Do These)\n\n### 1. Not Committing Lockfiles\n\n**BAD: Anti-Pattern:**\n\n```bash\n# .gitignore\npackage-lock.json # BAD: DON'T IGNORE\npnpm-lock.yaml # BAD: DON'T IGNORE\npoetry.lock # BAD: DON'T IGNORE\nCargo.lock # BAD: DON'T IGNORE (for apps)\n```\n\n**Why it's bad:**\n- Breaks reproducibility - different versions installed on different machines\n- \"Works on my machine\" syndrome\n- CI/production may get different versions than dev\n- Hidden bugs from version mismatches\n- Security vulnerabilities may appear unpredictably\n\n**Real-world disaster:**\n\n```\nDeveloper: Uses [email protected] (no vulnerabilities)\nCI: Installs [email protected] (has breaking change)\nProduction: Installs [email protected] (has CVE-2023-xxxxx)\n\nResult: Production is vulnerable, CI tests don't catch it\n```\n\n**GOOD: Correct Approach:**\n\n```bash\n# Commit lockfiles\ngit add package-lock.json pnpm-lock.yaml poetry.lock Cargo.lock go.sum\ngit commit -m \"chore: add lockfiles for reproducibility\"\n```\n\n**Exception:** Don't commit `Cargo.lock` for Rust libraries (only for applications).\n\n---\n\n### 2. Using Wildcards (`*`) for Version Ranges\n\n**BAD: Anti-Pattern:**\n\n```json\n{\n \"dependencies\": {\n \"express\": \"*\",\n \"react\": \"*\"\n }\n}\n```\n\n**Why it's bad:**\n- Completely unpredictable versions\n- Breaking changes appear randomly\n- No reproducibility even with lockfiles\n- Production can break on any deploy\n- Impossible to debug version-related issues\n\n**Real-world disaster:**\n\n```\nWeek 1: [email protected] installed (works fine)\nWeek 2: [email protected] released (breaking changes)\nWeek 3: New deploy pulls [email protected]\nResult: Production crashes, team scrambles to fix\n```\n\n**GOOD: Correct Approach:**\n\n```json\n{\n \"dependencies\": {\n \"express\": \"^4.18.0\", // Allows patches and minors, not majors\n \"react\": \"~18.2.0\" // Allows only patches\n }\n}\n```\n\n**When to use exact versions:**\n\n```json\n{\n \"dependencies\": {\n \"critical-payment-lib\": \"1.2.3\" // Exact version for mission-critical\n }\n}\n```\n\n---\n\n### 3. Manual Lockfile Editing\n\n**BAD: Anti-Pattern:**\n\n```bash\n# Manually editing package-lock.json\nvim package-lock.json\n# Change version numbers by hand\n```\n\n**Why it's bad:**\n- Lockfile integrity broken\n- Checksums won't match\n- Installation will fail or reinstall wrong versions\n- Package manager will overwrite your changes\n- Corrupts dependency tree\n\n**GOOD: Correct Approach:**\n\n```bash\n# Use package manager commands\nnpm install \u003cpackage>@\u003cversion>\nnpm update\nnpm dedupe\n\n# Let the package manager manage the lockfile\n```\n\n---\n\n### 4. Ignoring Security Audits\n\n**BAD: Anti-Pattern:**\n\n```bash\n$ npm audit\nfound 23 vulnerabilities (5 high, 18 moderate)\n\n# Developer: \"I'll fix it later\"\n# (Never fixes it)\n```\n\n**Why it's bad:**\n- Known vulnerabilities exploited in production\n- Data breaches, security incidents\n- Compliance violations (SOC2, PCI-DSS)\n- Legal liability\n- Reputation damage\n\n**Real-world disaster:**\n\n```\nEquifax breach (2017):\n- Known vulnerability in Apache Struts\n- Patch available for 2 months\n- Never applied\n- Result: 147 million records stolen, $700M+ in costs\n```\n\n**GOOD: Correct Approach:**\n\n```bash\n# Run audit regularly\nnpm audit\n\n# Fix automatically (safe)\nnpm audit fix\n\n# Review and fix manually (risky fixes)\nnpm audit fix --force\n\n# Set up automated alerts\n# Use Dependabot, Snyk, or GitHub Advanced Security\n```\n\n---\n\n### 5. Adding Dependencies Without Review\n\n**BAD: Anti-Pattern:**\n\n```bash\n# Developer sees a cool package on Twitter\nnpm install left-pad is-odd uppercase\n\n# No review, no research, no questions\n```\n\n**Why it's bad:**\n- Supply chain attacks (malicious packages)\n- Dependency bloat (hundreds of transitive deps)\n- Bundle size explosion\n- Security vulnerabilities\n- Unmaintained packages\n- License violations\n\n**Real-world disasters:**\n\n```\nevent-stream (2018):\n- Popular npm package compromised\n- Malicious code injected by new maintainer\n- Stole Bitcoin wallet credentials\n- Downloaded 8M times per week\n\nleft-pad (2016):\n- 11-line package unpublished\n- Broke thousands of projects\n- Highlighted fragility of npm ecosystem\n```\n\n**GOOD: Correct Approach:**\n\n```bash\n# Before adding ANY dependency:\n1. Check last update (within 6 months?)\n2. Check weekly downloads (>10k?)\n3. Check GitHub issues (responsive maintainers?)\n4. Check bundle size (bundlephobia.com)\n5. Check dependency tree (npm ls \u003cpackage>)\n6. Check security (npm audit \u003cpackage>)\n7. Check license compatibility\n8. Ask: Can I implement this in \u003c100 LOC?\n\n# Document decision\n# Add to ADR (Architecture Decision Record)\n```\n\n---\n\n## Dangerous Anti-Patterns (Avoid These)\n\n### 6. Never Updating Dependencies\n\n**BAD: Anti-Pattern:**\n\n```bash\n# Package.json from 2019\n{\n \"dependencies\": {\n \"express\": \"4.16.0\", // 5 years old\n \"lodash\": \"4.17.11\", // Known vulnerabilities\n \"moment\": \"2.24.0\" // Deprecated library\n }\n}\n```\n\n**Why it's bad:**\n- Technical debt accumulates\n- Security vulnerabilities pile up\n- Breaking changes pile up (harder to update later)\n- Incompatibility with modern tools\n- Loss of community support\n\n**GOOD: Correct Approach:**\n\n```bash\n# Update regularly (monthly or quarterly)\nnpm outdated\nnpm update\n\n# Or use automated tools\n# Dependabot, Renovate\n```\n\n---\n\n### 7. Using Deprecated Packages\n\n**BAD: Anti-Pattern:**\n\n```json\n{\n \"dependencies\": {\n \"request\": \"^2.88.0\", // Deprecated since 2020\n \"moment\": \"^2.29.0\", // Maintenance mode\n \"gulp\": \"^3.9.0\", // Use Gulp 4+\n \"node-sass\": \"^4.14.0\" // Deprecated (use sass)\n }\n}\n```\n\n**Why it's bad:**\n- No security patches\n- Incompatible with newer Node versions\n- No bug fixes\n- Community moves on\n- Harder to hire developers familiar with old tools\n\n**GOOD: Correct Approach:**\n\n```json\n{\n \"dependencies\": {\n \"axios\": \"^1.6.0\", // Instead of request\n \"date-fns\": \"^2.30.0\", // Instead of moment\n \"gulp\": \"^4.0.2\", // Gulp 4+\n \"sass\": \"^1.69.0\" // Instead of node-sass\n }\n}\n```\n\n**Check deprecation status:**\n\n```bash\nnpm outdated\nnpm view \u003cpackage>\n# Look for \"DEPRECATED\" warning\n```\n\n---\n\n### 8. Mixing Package Managers\n\n**BAD: Anti-Pattern:**\n\n```bash\n# Project has both\npackage-lock.json # From npm\nyarn.lock # From yarn\npnpm-lock.yaml # From pnpm\n\n# Team uses different package managers\n# Lockfiles conflict\n```\n\n**Why it's bad:**\n- Conflicting lockfiles\n- Inconsistent dependency resolution\n- Different versions on different machines\n- Merge conflicts in lockfiles\n- Confusion for new team members\n\n**GOOD: Correct Approach:**\n\n```bash\n# Choose ONE package manager\n# Document in README.md\n# Add to package.json\n\n{\n \"packageManager\": \"[email protected]\",\n \"engines\": {\n \"npm\": \"please-use-pnpm\",\n \"yarn\": \"please-use-pnpm\"\n }\n}\n```\n\n---\n\n### 9. Using `--force` or `--legacy-peer-deps` Without Understanding\n\n**BAD: Anti-Pattern:**\n\n```bash\n# Error during npm install\n$ npm install\nnpm ERR! peer dep missing: react@^18.0.0\n\n# Developer: \"I'll just force it\"\n$ npm install --force\n# or\n$ npm install --legacy-peer-deps\n```\n\n**Why it's bad:**\n- Hides real problems\n- May install incompatible versions\n- Runtime errors in production\n- Hard to debug later\n- Breaks assumptions of libraries\n\n**GOOD: Correct Approach:**\n\n```bash\n# Understand WHY the error occurred\nnpm ls react\n\n# Fix the root cause\n# Option 1: Update the dependency\nnpm update package-with-peer-dep\n\n# Option 2: Install missing peer dependency\nnpm install react@^18.0.0\n\n# Option 3: Use overrides (if necessary)\n{\n \"overrides\": {\n \"react\": \"18.2.0\"\n }\n}\n\n# Document why (if using --legacy-peer-deps)\n```\n\n---\n\n### 10. Not Using Virtual Environments (Python)\n\n**BAD: Anti-Pattern:**\n\n```bash\n# Installing globally (Python)\nsudo pip install flask\nsudo pip install django\n\n# System Python polluted\n# Conflicts between projects\n```\n\n**Why it's bad:**\n- Different projects need different versions\n- System Python gets corrupted\n- Permission issues\n- Can't reproduce environments\n- Hard to deploy\n\n**GOOD: Correct Approach:**\n\n```bash\n# Use virtual environments\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n\n# Or use poetry\npoetry install\n```\n\n---\n\n## Moderate Anti-Patterns (Be Careful)\n\n### 11. Overusing Overrides\n\n**BAD: Anti-Pattern:**\n\n```json\n{\n \"overrides\": {\n \"axios\": \"1.6.0\",\n \"lodash\": \"4.17.21\",\n \"express\": \"4.18.0\",\n \"react\": \"18.2.0\",\n \"typescript\": \"5.0.0\",\n \"webpack\": \"5.88.0\",\n \"...\": \"50 more overrides\"\n }\n}\n```\n\n**Why it's bad:**\n- Hides real dependency issues\n- May break packages that expect specific versions\n- Hard to maintain\n- Masks incompatibilities\n- Makes debugging harder\n\n**GOOD: Correct Approach:**\n\n```json\n{\n \"overrides\": {\n \"axios\": \"1.6.0\" // Only 1-2 critical overrides\n }\n}\n\n// Document WHY in README:\n// - axios override: CVE-2023-xxxxx fix\n```\n\n---\n\n### 12. Ignoring Peer Dependency Warnings\n\n**BAD: Anti-Pattern:**\n\n```bash\n$ npm install\nnpm WARN [email protected] requires a peer of react@^18.0.0\nnpm WARN [email protected] is installed\n\n# Developer: \"It's just a warning, ignore it\"\n```\n\n**Why it's bad:**\n- Runtime errors in production\n- Incompatible API usage\n- Subtle bugs\n- Undefined behavior\n\n**GOOD: Correct Approach:**\n\n```bash\n# Install the correct peer dependency\nnpm install react@^18.0.0\n\n# Or check if library supports your version\nnpm info react-dom peerDependencies\n```\n\n---\n\n### 13. Committing `node_modules/`\n\n**BAD: Anti-Pattern:**\n\n```bash\n# .gitignore missing node_modules/\ngit add node_modules/\ngit commit -m \"add dependencies\"\n```\n\n**Why it's bad:**\n- Massive repo size (100MB+)\n- Slow git operations\n- Platform-specific binaries break\n- Conflicts on every change\n- Defeats purpose of package.json\n\n**GOOD: Correct Approach:**\n\n```bash\n# .gitignore\nnode_modules/\nvenv/\n__pycache__/\ntarget/ # Rust\nvendor/ # Go (usually)\n\n# Commit lockfiles instead\ngit add package-lock.json\n```\n\n---\n\n### 14. Using Development Dependencies in Production\n\n**BAD: Anti-Pattern:**\n\n```json\n{\n \"dependencies\": {\n \"express\": \"^4.18.0\",\n \"jest\": \"^29.0.0\", // BAD: Should be devDependency\n \"eslint\": \"^8.0.0\", // BAD: Should be devDependency\n \"typescript\": \"^5.0.0\" // BAD: Should be devDependency\n }\n}\n```\n\n**Why it's bad:**\n- Bloated production bundles\n- Slower deployments\n- Higher memory usage\n- Security surface area increased\n\n**GOOD: Correct Approach:**\n\n```json\n{\n \"dependencies\": {\n \"express\": \"^4.18.0\"\n },\n \"devDependencies\": {\n \"jest\": \"^29.0.0\",\n \"eslint\": \"^8.0.0\",\n \"typescript\": \"^5.0.0\"\n }\n}\n```\n\n**Install production-only:**\n\n```bash\nnpm install --production\n# or\nnpm ci --production\n```\n\n---\n\n## Checklist: Avoiding Anti-Patterns\n\n**Before every dependency change:**\n\n- [ ] [OK] Commit lockfiles\n- [ ] [OK] Use semantic versioning (not wildcards)\n- [ ] [OK] Use package manager commands (not manual edits)\n- [ ] [OK] Run security audit\n- [ ] [OK] Review dependency before adding\n- [ ] [OK] Update dependencies regularly\n- [ ] [OK] Avoid deprecated packages\n- [ ] [OK] Use one package manager\n- [ ] [OK] Understand `--force` before using\n- [ ] [OK] Use virtual environments (Python)\n- [ ] [OK] Minimize overrides\n- [ ] [OK] Fix peer dependency warnings\n- [ ] [OK] Never commit `node_modules/`\n- [ ] [OK] Separate dev and prod dependencies\n\n---\n\n## Summary\n\n**The Top 5 Most Damaging Anti-Patterns:**\n\n1. **Not committing lockfiles** - Breaks reproducibility\n2. **Using wildcards (`*`)** - Unpredictable versions\n3. **Ignoring security audits** - Exploitable vulnerabilities\n4. **Adding deps without review** - Supply chain attacks\n5. **Never updating** - Technical debt accumulates\n\n**Remember:** Dependency management requires discipline. Shortcuts today become disasters tomorrow.\n\n---\n\n## Quick Reference: What NOT To Do\n\n| [FAIL] DON'T | [OK] DO |\n|---------|-------|\n| Ignore lockfiles | Commit lockfiles to git |\n| Use wildcards (`*`) | Use semver ranges (`^`, `~`) |\n| Edit lockfiles manually | Use package manager commands |\n| Ignore `npm audit` | Fix vulnerabilities immediately |\n| Add deps without review | Check bundle size, security, maintenance |\n| Never update | Update monthly/quarterly |\n| Use deprecated packages | Migrate to maintained alternatives |\n| Mix package managers | Choose one, document in README |\n| Use `--force` blindly | Understand and fix root cause |\n| Skip virtual envs (Python) | Always use venv/poetry |\n| Overuse overrides | Only 1-2 critical overrides |\n| Ignore peer dep warnings | Install correct versions |\n| Commit `node_modules/` | Add to `.gitignore` |\n| Mix dev/prod deps | Separate into correct categories |\n\n---\n\n**Final Advice:** When in doubt, follow the principle of least surprise. If something seems hacky or fragile, it probably is. Do it the right way the first time.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":13125,"content_sha256":"3b258338d097e0076610fd5886ee119b4c40451f1fdd9c3d947c1b54abb87089"},{"filename":"references/container-dependency-patterns.md","content":"# Container Dependency Patterns\n\n> Operational reference for managing dependencies in containerized environments — multi-stage builds, layer caching, base image selection, vulnerability scanning, and reproducible builds.\n\n**Freshness anchor:** January 2026 — aligned with Docker Engine 27.x, BuildKit 0.17, Trivy 0.58, Grype 0.83, and OCI Image Spec v1.1.\n\n---\n\n## Base Image Selection Decision Tree\n\n```\nWhat runtime do you need?\n├── Static binary (Go, Rust)\n│ └── Use distroless/static or scratch\n├── Minimal runtime (Node.js, Python, Java)\n│ ├── Need shell access for debugging?\n│ │ ├── YES → Alpine variant (e.g., node:22-alpine)\n│ │ └── NO → Distroless (e.g., gcr.io/distroless/nodejs22-debian12)\n│ └── Need specific system libraries (native extensions)?\n│ ├── YES → Debian slim (e.g., node:22-slim)\n│ └── NO → Alpine variant\n└── Complex system dependencies (ML, scientific computing)\n └── Use Debian slim or Ubuntu LTS\n └── Pin to specific version tag, never use :latest\n```\n\n### Base Image Comparison\n\n| Base | Size (compressed) | Package Manager | Shell | CVE surface | Use when |\n|---|---|---|---|---|---|\n| `scratch` | 0 MB | None | No | Minimal | Static binaries only |\n| `distroless/static` | ~2 MB | None | No | Very low | Go, Rust static binaries |\n| `distroless/base` | ~20 MB | None | No | Low | C/C++ with glibc |\n| `alpine:3.21` | ~3 MB | apk | Yes (ash) | Low | General minimal containers |\n| `debian:bookworm-slim` | ~30 MB | apt | Yes (bash) | Medium | Native extensions needed |\n| `ubuntu:24.04` | ~30 MB | apt | Yes (bash) | Medium | Complex dependency chains |\n\n### Alpine Gotchas Checklist\n\n- [ ] Uses musl libc, not glibc — some native extensions may fail\n- [ ] Python packages with C extensions may need `apk add build-base`\n- [ ] DNS resolution differences (musl resolver) — test thoroughly\n- [ ] No locales by default — add if needed for i18n\n- [ ] Smaller community for troubleshooting vs Debian\n\n---\n\n## Multi-Stage Build Patterns\n\n### Standard Multi-Stage Pattern\n\n```dockerfile\n# ---- Build stage ----\nFROM node:22-alpine AS builder\n\nWORKDIR /app\nCOPY package.json package-lock.json ./\nRUN npm ci --ignore-scripts\nCOPY . .\nRUN npm run build\n\n# ---- Production stage ----\nFROM node:22-alpine AS production\n\nWORKDIR /app\nENV NODE_ENV=production\n\n# Install production deps only\nCOPY package.json package-lock.json ./\nRUN npm ci --omit=dev --ignore-scripts && npm cache clean --force\n\n# Copy built artifacts from builder\nCOPY --from=builder /app/dist ./dist\n\n# Non-root user\nRUN addgroup -g 1001 appgroup && adduser -u 1001 -G appgroup -D appuser\nUSER appuser\n\nEXPOSE 3000\nCMD [\"node\", \"dist/server.js\"]\n```\n\n### Build vs Runtime Dependencies\n\n| Category | Examples | Stage |\n|---|---|---|\n| Build tools | gcc, make, python3 (node-gyp) | Build stage only |\n| Dev dependencies | jest, eslint, typescript | Build stage only |\n| Build artifacts | compiled JS, binaries, bundled CSS | Copy to production stage |\n| Runtime dependencies | express, pg, redis | Production stage |\n| System runtime libs | libssl, libc | Production base image |\n\n### Multi-Stage Checklist\n\n- [ ] Build dependencies NOT present in final image\n- [ ] Dev dependencies NOT installed in production stage\n- [ ] Only necessary artifacts copied from build stage\n- [ ] Final stage uses minimal base image\n- [ ] Final stage runs as non-root user\n- [ ] npm/pip/apt caches cleaned in the same RUN layer\n\n---\n\n## Layer Caching Optimization\n\n### Layer Ordering Rules\n\n```\nMost stable layers first → Least stable layers last\n\n1. Base image (changes rarely)\n2. System package installation (changes monthly)\n3. Language runtime config (changes per-project)\n4. Dependency manifests COPY (changes when deps update)\n5. Dependency install RUN (cached if manifests unchanged)\n6. Application source COPY (changes every commit)\n7. Build command RUN (runs every commit)\n```\n\n### Caching Optimization Checklist\n\n- [ ] `COPY package.json package-lock.json ./` BEFORE `COPY . .`\n- [ ] Dependency install (`npm ci`) in separate layer from source copy\n- [ ] System packages installed in single `RUN` with `&&` chaining\n- [ ] `.dockerignore` excludes: `node_modules`, `.git`, `dist`, `*.md`, tests\n- [ ] BuildKit cache mounts used for package manager caches\n\n### BuildKit Cache Mounts\n\n```dockerfile\n# Node.js - cache npm\nRUN --mount=type=cache,target=/root/.npm \\\n npm ci --ignore-scripts\n\n# Python - cache pip\nRUN --mount=type=cache,target=/root/.cache/pip \\\n pip install --no-compile -r requirements.txt\n\n# Go - cache module downloads and build cache\nRUN --mount=type=cache,target=/go/pkg/mod \\\n --mount=type=cache,target=/root/.cache/go-build \\\n go build -o /app/server ./cmd/server\n\n# Rust - cache cargo registry and build artifacts\nRUN --mount=type=cache,target=/usr/local/cargo/registry \\\n --mount=type=cache,target=/app/target \\\n cargo build --release\n```\n\n### .dockerignore Template\n\n```\n.git\n.github\nnode_modules\ndist\nbuild\n*.md\n*.log\n.env*\n.vscode\n.idea\ntests\n__tests__\ncoverage\ndocker-compose*.yml\nMakefile\n```\n\n---\n\n## Vulnerability Scanning\n\n### Tool Comparison\n\n| Tool | Type | CI Integration | Database | License |\n|---|---|---|---|---|\n| Trivy | Image + FS + IaC | GitHub Actions, GitLab CI | Multiple (NVD, GHSA) | Apache 2.0 |\n| Grype | Image + FS | GitHub Actions | Anchore feed | Apache 2.0 |\n| Docker Scout | Image | Docker Desktop, CI | Docker advisory DB | Free tier |\n| Snyk Container | Image | CI/CD, IDE | Snyk DB | Free tier |\n\n### Trivy Integration\n\n```bash\n# Scan a built image\ntrivy image --severity HIGH,CRITICAL myapp:latest\n\n# Scan with exit code for CI gating\ntrivy image --exit-code 1 --severity CRITICAL myapp:latest\n\n# Scan filesystem (lock files)\ntrivy fs --scanners vuln /app\n\n# Scan and output SARIF for GitHub Security\ntrivy image --format sarif --output results.sarif myapp:latest\n\n# Ignore unfixed vulnerabilities\ntrivy image --ignore-unfixed myapp:latest\n```\n\n### Grype Integration\n\n```bash\n# Scan an image\ngrype myapp:latest\n\n# Fail on high/critical\ngrype myapp:latest --fail-on high\n\n# Output JSON for processing\ngrype myapp:latest -o json > results.json\n```\n\n### Scanning Pipeline Checklist\n\n- [ ] Scan on every image build in CI\n- [ ] Gate deployments on CRITICAL vulnerabilities (fail the build)\n- [ ] HIGH vulnerabilities tracked as tickets, fixed within SLA\n- [ ] Base image scanned separately from application layer\n- [ ] `.trivyignore` or Grype config for accepted risks (with expiration dates)\n- [ ] Weekly scheduled scan of deployed images (catch new CVEs)\n- [ ] SBOM generated and stored (`trivy image --format spdx-json`)\n\n### Vulnerability SLA Reference\n\n| Severity | Fix SLA | Action |\n|---|---|---|\n| CRITICAL | 24-48 hours | Immediate patch or mitigation |\n| HIGH | 7 days | Prioritize in current sprint |\n| MEDIUM | 30 days | Schedule in backlog |\n| LOW | 90 days | Address during maintenance |\n\n---\n\n## Reproducible Builds\n\n### Pinning Strategies\n\n| What to Pin | How | Example |\n|---|---|---|\n| Base image | SHA256 digest | `FROM node:22-alpine@sha256:abc123...` |\n| System packages | Version specifier | `apk add --no-cache curl=8.5.0-r0` |\n| Language deps | Lockfile | `package-lock.json`, `poetry.lock` |\n| Build tools | Version in Dockerfile | `ARG BUILDKIT_VERSION=0.17.0` |\n\n### Reproducibility Checklist\n\n- [ ] Base images pinned to digest (not just tag)\n- [ ] Lockfiles committed and used (`npm ci`, not `npm install`)\n- [ ] `--ignore-scripts` flag used during install (run scripts explicitly if needed)\n- [ ] No `curl | bash` patterns for installing tools (pin versions instead)\n- [ ] `apt-get` uses `--no-install-recommends`\n- [ ] Build arguments used for version pins (visible, overridable)\n- [ ] Timezone and locale set explicitly if needed\n- [ ] `COPY` uses specific paths, not `.` (avoids accidental inclusion)\n\n### Base Image Update Strategy\n\n```\nIs there a CRITICAL CVE in the base image?\n├── YES → Update immediately\n│ ├── Rebuild and test\n│ └── Deploy within SLA\n└── NO\n ├── Monthly: check for base image updates\n ├── Quarterly: evaluate major version bumps\n └── Automate with Renovate/Dependabot\n └── Auto-PR for digest updates\n └── Manual review for major version changes\n```\n\n---\n\n## Language-Specific Patterns\n\n### Node.js\n\n```dockerfile\nFROM node:22-alpine AS builder\nWORKDIR /app\nCOPY package.json package-lock.json ./\nRUN npm ci --ignore-scripts\nCOPY . .\nRUN npm run build && npm prune --production\n```\n\n- Use `npm ci` (not `npm install`) for reproducibility\n- `npm prune --production` removes dev deps after build\n- Set `NODE_ENV=production` in production stage\n\n### Python\n\n```dockerfile\nFROM python:3.13-slim AS builder\nWORKDIR /app\nRUN pip install --no-cache-dir poetry==1.8.5\nCOPY pyproject.toml poetry.lock ./\nRUN poetry export -f requirements.txt -o requirements.txt --without-hashes\nRUN pip install --no-cache-dir --prefix=/install -r requirements.txt\n\nFROM python:3.13-slim\nCOPY --from=builder /install /usr/local\nCOPY . /app\nWORKDIR /app\n```\n\n- Use `poetry export` or `pip-compile` for deterministic installs\n- `--prefix=/install` allows clean copy of installed packages\n\n### Go\n\n```dockerfile\nFROM golang:1.23-alpine AS builder\nWORKDIR /app\nCOPY go.mod go.sum ./\nRUN go mod download\nCOPY . .\nRUN CGO_ENABLED=0 go build -ldflags=\"-s -w\" -o /server ./cmd/server\n\nFROM scratch\nCOPY --from=builder /server /server\nCOPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/\nENTRYPOINT [\"/server\"]\n```\n\n- `CGO_ENABLED=0` for static binary\n- `-ldflags=\"-s -w\"` strips debug info (smaller binary)\n- `scratch` base image for minimal surface\n\n### Rust\n\n```dockerfile\nFROM rust:1.84-slim AS builder\nWORKDIR /app\nCOPY Cargo.toml Cargo.lock ./\nRUN mkdir src && echo \"fn main() {}\" > src/main.rs\nRUN cargo build --release\nCOPY src ./src\nRUN touch src/main.rs && cargo build --release\n\nFROM gcr.io/distroless/cc-debian12\nCOPY --from=builder /app/target/release/myapp /\nENTRYPOINT [\"/myapp\"]\n```\n\n- Dummy `main.rs` trick caches dependency compilation\n- `touch` forces rebuild of application code only\n\n---\n\n## Anti-Patterns\n\n| Anti-Pattern | Problem | Fix |\n|---|---|---|\n| Using `:latest` tag | Non-reproducible, unpredictable updates | Pin to version tag or SHA digest |\n| Installing dev tools in production image | Larger image, bigger attack surface | Multi-stage build, copy artifacts only |\n| Running as root | Security vulnerability | `USER nonroot` or `USER 1001` |\n| `COPY . .` before dependency install | Busts cache on every code change | Copy manifests first, install, then copy source |\n| `apt-get install` without `--no-install-recommends` | Bloated image with unnecessary packages | Always use `--no-install-recommends` |\n| No `.dockerignore` | `.git`, `node_modules` copied into build context | Maintain `.dockerignore` |\n| Multiple `RUN apt-get` commands | Wasted layers, cache issues | Chain with `&&` in single `RUN` |\n| Ignoring vulnerability scan results | Known CVEs in production | Gate CI on CRITICAL, SLA for HIGH |\n| `npm install` instead of `npm ci` | Non-deterministic dependency resolution | Always use `npm ci` with lockfile |\n| No health check | Orchestrator cannot detect unhealthy containers | Add `HEALTHCHECK` instruction |\n\n---\n\n## Cross-References\n\n- `dev-dependency-management/references/version-conflict-resolution.md` — resolving conflicts in lockfiles\n- `dev-dependency-management/references/license-compliance.md` — scanning container images for license issues\n- `software-security-appsec/references/threat-modeling-guide.md` — container threat model\n- `software-backend/references/nodejs-best-practices.md` — Node.js containerization specifics\n- `qa-observability/references/log-aggregation-patterns.md` — container logging patterns\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":11906,"content_sha256":"a3685dbc55f44344324f22970571690b9a94b313b4497773b3f2626fdfb7e635"},{"filename":"references/dependency-selection-guide.md","content":"# Dependency Selection Guide\n\n**When to Use**: Deciding whether to add a new dependency or choosing between similar packages.\n\n---\n\n## Minimal Dependencies Principle\n\nEvery dependency added to your project increases:\n- Attack surface area\n- Bundle size\n- Maintenance burden\n- Supply chain risk\n- Build complexity\n\n**Golden Rule**: The best dependency is the one you don't add.\n\n---\n\n## Questions to Ask Before Adding a Dependency\n\n### 1. Do I Really Need This?\n\n**Can I implement this in \u003c100 lines of code?**\n\nMany utility libraries can be replaced with simple native implementations:\n\n```javascript\n// BAD: Don't add 'is-odd' package\nconst isOdd = require('is-odd')\n\n// GOOD: Use simple function\nconst isOdd = (n) => n % 2 !== 0\n\n// BAD: Don't add 'left-pad' package\nconst leftPad = require('left-pad')\n\n// GOOD: Use native method\nconst leftPad = (str, len) => str.padStart(len, '0')\n\n// BAD: Don't add 'axios' for simple requests\nconst axios = require('axios')\nconst data = await axios.get(url)\n\n// GOOD: Use native fetch\nconst response = await fetch(url)\nconst data = await response.json()\n```\n\n**Native alternatives often exist:**\n\n| Instead of | Use Native |\n|-----------|------------|\n| `moment` | `Intl.DateTimeFormat`, `Date` |\n| `lodash.debounce` | Simple timeout wrapper |\n| `uuid` | `crypto.randomUUID()` (Node 14.17+) |\n| `axios` | `fetch` API |\n| `is-array` | `Array.isArray()` |\n| `query-string` | `URLSearchParams` |\n\n### 2. Is This Package Well-Maintained?\n\n**Maintenance Checklist:**\n\n- [ ] **Last commit within 6 months** - Active development\n- [ ] **Active issue resolution** - Check open/closed ratio\n- [ ] **Weekly downloads >10k** - Community adoption\n- [ ] **Multiple maintainers** - Bus factor > 1\n- [ ] **CI/Tests passing** - Quality assurance\n- [ ] **Changelog maintained** - Clear release notes\n- [ ] **Responsive to security issues** - Check GitHub Security tab\n\n**Red Flags:**\n\n- [WARNING] No commits in 2+ years\n- [WARNING] Low weekly downloads (\u003c1000)\n- [WARNING] No tests or CI\n- [WARNING] Single maintainer with no recent activity\n- [WARNING] Many open security issues\n- [WARNING] No documentation or examples\n\n**Where to Check:**\n\n```bash\n# View package metadata\nnpm info \u003cpackage>\n\n# Check GitHub activity\nnpm repo \u003cpackage>\n\n# View npm package page\nnpm home \u003cpackage>\n```\n\n### 3. What's the Dependency Tree Size?\n\n**View dependency tree:**\n\n```bash\nnpm ls \u003cpackage> # Show dependency tree\nnpm info \u003cpackage> # Show package metadata\npnpm why \u003cpackage> # Show why package is installed\n```\n\n**Example output:**\n\n```bash\n$ npm ls axios\[email protected]\n└─┬ [email protected]\n ├── [email protected]\n ├── [email protected]\n │ ├── [email protected]\n │ ├── [email protected]\n │ │ └── [email protected]\n │ └── [email protected]\n │ └── [email protected]\n └── [email protected]\n```\n\n**Red Flags:**\n\n- Large dependency tree (>50 transitive deps)\n- Circular dependencies\n- Conflicting peer dependencies\n- Multiple versions of same package\n\n### 4. What's the Bundle Size Impact?\n\n**For JavaScript/TypeScript:**\n\nUse [Bundlephobia](https://bundlephobia.com/) to check:\n\n- **Minified size** - Production bundle impact\n- **Minified + gzipped** - Network transfer size\n- **Tree-shakeable** - Can unused code be removed?\n\n**Command-line check:**\n\n```bash\n# Check package size\nnpm info \u003cpackage> size\n\n# Compare with alternative\nnpm info date-fns size\nnpm info dayjs size\nnpm info moment size\n```\n\n**Example comparison:**\n\n| Package | Minified | Gzipped | Verdict |\n|---------|----------|---------|---------|\n| `moment` | 229 kB | 71.6 kB | [FAIL] Too large |\n| `date-fns` | 78.4 kB | 13.4 kB | GOOD |\n| `dayjs` | 6.5 kB | 2.6 kB | [OK] Best |\n\n**Guidelines:**\n\n- \u003c10 kB gzipped: [OK] Excellent\n- 10-50 kB gzipped: [YELLOW] Acceptable\n- >50 kB gzipped: [WARNING] Evaluate carefully\n- >100 kB gzipped: [FAIL] Likely too large\n\n### 5. What Are the Security Risks?\n\n**Security audit:**\n\n```bash\n# Check for vulnerabilities\nnpm audit\nnpm audit --json | jq '.vulnerabilities'\n\n# Check specific package\nnpm audit \u003cpackage>\n\n# Use third-party scanners\nnpx snyk test\n```\n\n**Check vulnerability databases:**\n\n- [npm advisory database](https://github.com/advisories)\n- [Snyk vulnerability DB](https://snyk.io/vuln/)\n- [CVE database](https://cve.mitre.org/)\n\n**Red Flags:**\n\n- Critical/High severity CVEs in last 12 months\n- Known supply chain attacks\n- No security policy (`SECURITY.md`)\n- No contact for security issues\n\n### 6. Are There Better Alternatives?\n\n**Evaluation matrix:**\n\n| Criterion | Tool/Check |\n|-----------|-----------|\n| Popularity | npm registry, GitHub stars |\n| Maintenance | Last commit, issue response time |\n| Bundle Size | Bundlephobia |\n| Performance | Benchmarks, real-world tests |\n| Security | npm audit, Snyk |\n| Documentation | README, website quality |\n| API Design | TypeScript support, ease of use |\n| Dependencies | `npm ls`, transitive count |\n| License | Check LICENSE file |\n\n---\n\n## Choosing Between Similar Packages\n\n### Step-by-Step Evaluation\n\n**1. Create comparison table:**\n\n| Criterion | Package A | Package B | Package C |\n|-----------|-----------|-----------|-----------|\n| Weekly downloads | 10M | 5M | 1M |\n| Bundle size (gzipped) | 13 kB | 7 kB | 25 kB |\n| Last update | 2 weeks | 1 month | 6 months |\n| GitHub stars | 45k | 20k | 8k |\n| Open issues | 150 | 50 | 300 |\n| TypeScript support | [OK] | [OK] | [FAIL] |\n| Tree-shakeable | [OK] | [OK] | [FAIL] |\n| CVEs (last 12mo) | 0 | 0 | 2 |\n\n**2. Test API ergonomics:**\n\nTry each package in a sandbox:\n\n```javascript\n// Package A\nimport { format } from 'date-fns'\nformat(new Date(), 'yyyy-MM-dd')\n\n// Package B\nimport dayjs from 'dayjs'\ndayjs().format('YYYY-MM-DD')\n\n// Package C - Native\nnew Intl.DateTimeFormat('en-CA').format(new Date())\n```\n\n**3. Consider ecosystem fit:**\n\n- Does it work with your framework? (React, Vue, Angular)\n- Does it support your build tools? (Vite, webpack, esbuild)\n- Is it actively used in your stack's ecosystem?\n\n**4. Document your choice:**\n\nCreate an Architecture Decision Record (ADR):\n\n```markdown\n# ADR 001: Date Library Selection\n\n## Status\nAccepted\n\n## Context\nWe need a date formatting/manipulation library for the user dashboard.\n\n## Decision\nUse `date-fns` over `dayjs` and `moment`.\n\n## Rationale\n- Tree-shakeable (import only what we use)\n- TypeScript support (native types)\n- 13 kB gzipped vs moment's 71 kB\n- Active maintenance (weekly releases)\n- No security issues in last 2 years\n- Functional API fits our codebase style\n\n## Alternatives Considered\n- `moment`: Deprecated, too large\n- `dayjs`: Smaller, but less mature ecosystem\n- Native `Intl`: Insufficient for complex formatting needs\n\n## Consequences\n- Bundle size increase: +13 kB gzipped\n- Team needs to learn date-fns API\n- Migration path from moment already documented\n```\n\n---\n\n## Real-World Examples\n\n### Example 1: Date Libraries (JavaScript)\n\n| Library | Bundle Size | Downloads/week | Last Update | Verdict |\n|---------|------------|----------------|-------------|---------|\n| `moment` | 229 kB | 10M+ | Maintenance mode | [FAIL] Deprecated |\n| `date-fns` | 13 kB | 12M+ | Active | [OK] Recommended |\n| `dayjs` | 7 kB | 10M+ | Active | [OK] Lightweight alternative |\n| Native `Intl` | 0 kB | Native | N/A | [OK] Best (no dependency) |\n\n**Recommendation**: Use native `Intl` for simple formatting, `date-fns` for complex needs.\n\n### Example 2: HTTP Clients (JavaScript)\n\n| Library | Bundle Size | Downloads/week | TypeScript | Verdict |\n|---------|------------|----------------|------------|---------|\n| `axios` | 14 kB | 50M+ | [OK] | GOOD (features-rich) |\n| `got` | 50 kB | 5M+ | [OK] | [YELLOW] Node.js only |\n| `ky` | 5 kB | 2M+ | [OK] | [OK] Lightweight |\n| Native `fetch` | 0 kB | Native | [OK] | [OK] Best (modern browsers) |\n\n**Recommendation**: Use native `fetch` for simple requests, `axios` for complex needs (interceptors, retries).\n\n### Example 3: State Management (React)\n\n| Library | Bundle Size | Learning Curve | Ecosystem | Verdict |\n|---------|------------|----------------|-----------|---------|\n| Redux | 6 kB | High | Large | [OK] Enterprise apps |\n| Zustand | 3 kB | Low | Growing | [OK] Simple apps |\n| Jotai | 3 kB | Medium | Modern | [OK] Atomic state |\n| Context API | 0 kB | Low | Native | [OK] Simple state |\n\n**Recommendation**: Start with Context API, add Zustand for global state, Redux for complex apps only.\n\n---\n\n## Checklist: Before Adding Any Dependency\n\nUse this checklist for EVERY dependency you consider adding:\n\n**Necessity:**\n- [ ] Can I implement this in \u003c100 lines of native code?\n- [ ] Does a native alternative exist? (check MDN, language docs)\n- [ ] Is this solving a real problem (not premature optimization)?\n\n**Maintenance:**\n- [ ] Last commit within 6 months?\n- [ ] Active issue resolution?\n- [ ] Weekly downloads >10k?\n- [ ] Multiple maintainers?\n- [ ] CI/tests passing?\n\n**Quality:**\n- [ ] Bundle size acceptable? (\u003c50 kB gzipped)\n- [ ] Dependency tree reasonable? (\u003c20 transitive deps)\n- [ ] TypeScript support? (if using TypeScript)\n- [ ] Tree-shakeable? (for JS libraries)\n- [ ] Good documentation?\n\n**Security:**\n- [ ] No critical/high CVEs in last 12 months?\n- [ ] Has security policy (`SECURITY.md`)?\n- [ ] Passed `npm audit` / `snyk test`?\n- [ ] License compatible with project?\n\n**Alternatives:**\n- [ ] Compared 2-3 alternatives?\n- [ ] Documented choice in ADR?\n- [ ] Team reviewed decision?\n\n---\n\n## When to REJECT a Dependency\n\n**Automatic Rejection Criteria:**\n\n1. **Critical security vulnerability** with no fix available\n2. **Abandoned package** (no commits in 2+ years)\n3. **Incompatible license** (GPL in proprietary project)\n4. **Massive bundle size** (>100 kB for simple utility)\n5. **Better native alternative** exists (e.g., fetch vs axios for simple GET)\n6. **Can implement in \u003c50 lines** of simple code\n\n**Example rejections:**\n\n```javascript\n// BAD: REJECT: 'is-odd' package (1 line native implementation)\n// npm install is-odd\nconst isOdd = (n) => n % 2 !== 0\n\n// BAD: REJECT: 'left-pad' package (1 line native)\n// npm install left-pad\nconst leftPad = (str, len) => str.padStart(len, '0')\n\n// BAD: REJECT: 'moment' (deprecated, 229 kB)\n// Use date-fns (13 kB) or native Intl\n\n// BAD: REJECT: 'request' (deprecated since 2020)\n// Use axios or native fetch\n```\n\n---\n\n## Summary\n\n**The Dependency Decision Tree:**\n\n```\nShould I add this dependency?\n ├─ Can I implement in \u003c100 LOC? → YES → Don't add\n ├─ Is there a native alternative? → YES → Use native\n ├─ Is it well-maintained? → NO → Don't add\n ├─ Bundle size acceptable? → NO → Find alternative\n ├─ Security audit clean? → NO → Don't add\n └─ All checks pass → Add with caution, document choice\n```\n\n**Remember:** Every dependency is a liability. Add dependencies deliberately, not reflexively.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":10898,"content_sha256":"d332b8a2dc9e320c03b3b94c5bfb5e9ed18ff434c6774830081af728c16c0747"},{"filename":"references/ecosystem-guides.md","content":"# Dependency Management by Ecosystem\n\n**When to Use**: Ecosystem-specific guidance for Node.js, Python, Rust, Go, and other language ecosystems.\n\n---\n\n## Node.js (npm / yarn / pnpm / Bun)\n\n### Package Manager Comparison (January 2026)\n\n| Feature | npm 11.x | yarn 4.x (Berry) | pnpm 10.x | Bun 1.3 |\n|---------|----------|------------------|-----------|---------|\n| **Speed** | Slowest | Decent | Fast | **Fastest** (7× npm) |\n| **Disk Usage** | High (duplicates) | PnP: None / Classic: High | **Lowest** (hard links) | Low (global cache) |\n| **Monorepo Support** | Good (workspaces) | Good (workspaces) | **Best** (strict isolation) | Good (improving) |\n| **Security** | Good (audit built-in) | Good | Good | Good |\n| **Ecosystem** | Largest | Large | Large | Growing |\n| **Lockfile** | package-lock.json | yarn.lock | pnpm-lock.yaml | bun.lock |\n| **Install Command** | `npm install` | `yarn install` | `pnpm install` | `bun install` |\n| **CI Command** | `npm ci` | `yarn install --frozen-lockfile` | `pnpm install --frozen-lockfile` | `bun install --frozen-lockfile` |\n| **Deterministic** | Yes | **Excellent** (PnP) | **Excellent** | Yes |\n\n**Recommendations (January 2026):**\n\n- **New projects:** **pnpm** (fastest stable, best disk efficiency) or **Bun** (7× faster, production-ready)\n- **Enterprise monorepos:** **pnpm** (most stable workspace support)\n- **Speed-focused experimentation:** **Bun** (bleeding edge performance)\n- **Maximum compatibility:** **npm** (most packages tested against it)\n\n### npm Best Practices\n\n**1. Use `npm ci` in CI/CD (not `npm install`):**\n\n```bash\n# BAD: Bad (in CI)\nnpm install\n\n# GOOD: Good (in CI)\nnpm ci\n```\n\n**Why:** `npm ci` installs from lockfile exactly, faster, and fails if package.json and lockfile are out of sync.\n\n**2. Enable `save-exact` for critical applications:**\n\n```bash\nnpm config set save-exact true\n```\n\nOr in `.npmrc`:\n\n```ini\nsave-exact=true\n```\n\n**Effect:**\n\n```json\n{\n \"dependencies\": {\n \"express\": \"4.18.2\" // Exact version (not ^4.18.2)\n }\n}\n```\n\n**3. Use `.npmrc` for team configuration:**\n\n```ini\n# .npmrc (committed to git)\nsave-exact=false\npackage-lock=true\nengine-strict=true\naudit-level=moderate\n```\n\n**4. Configure private registry (optional):**\n\n```ini\nregistry=https://registry.npmjs.org/\n@myorg:registry=https://npm.mycompany.com/\n```\n\n**5. Audit dependencies monthly:**\n\n```bash\n# Check for vulnerabilities\nnpm audit\n\n# Auto-fix non-breaking\nnpm audit fix\n\n# Check specific package\nnpm view \u003cpackage> vulnerabilities\n```\n\n**6. Use workspaces for monorepos:**\n\n```json\n{\n \"workspaces\": [\n \"packages/*\",\n \"apps/*\"\n ]\n}\n```\n\n### pnpm Best Practices\n\n**1. Use `pnpm` for speed and disk efficiency:**\n\n```bash\n# Install pnpm globally\nnpm install -g pnpm\n\n# Migrate from npm\npnpm import # Converts package-lock.json → pnpm-lock.yaml\n\n# Install dependencies\npnpm install\n```\n\n**2. Configure workspaces:**\n\n```yaml\n# pnpm-workspace.yaml\npackages:\n - 'packages/*'\n - 'apps/*'\n - '!**/test/**' # Exclude test directories\n```\n\n**3. Use filters for monorepo commands:**\n\n```bash\n# Run script in specific package\npnpm --filter @myorg/ui build\n\n# Run script in all packages\npnpm -r test\n\n# Run script in changed packages only\npnpm --filter=\"...[origin/main]\" test\n```\n\n**4. Enable strict peer dependencies:**\n\n```ini\n# .npmrc\nstrict-peer-dependencies=true\n```\n\n**5. Use overrides for transitive deps:**\n\n```json\n{\n \"pnpm\": {\n \"overrides\": {\n \"axios\": \"1.6.0\"\n }\n }\n}\n```\n\n### yarn Best Practices\n\n**1. Use Yarn 3+ (Berry) for modern features:**\n\n```bash\n# Enable Corepack (Node 16.10+)\ncorepack enable\n\n# Set Yarn version\nyarn set version stable\n```\n\n**2. Use workspaces:**\n\n```json\n{\n \"workspaces\": {\n \"packages\": [\n \"packages/*\"\n ]\n }\n}\n```\n\n**3. Use `yarn why` to understand dependencies:**\n\n```bash\nyarn why lodash\n```\n\n**4. Configure resolutions:**\n\n```json\n{\n \"resolutions\": {\n \"lodash\": \"4.17.21\"\n }\n}\n```\n\n### Bun Best Practices\n\n**1. Install Bun:**\n\n```bash\n# macOS/Linux\ncurl -fsSL https://bun.sh/install | bash\n\n# Windows (via npm)\nnpm install -g bun\n```\n\n**2. Initialize and install:**\n\n```bash\n# New project\nbun init\n\n# Install dependencies (7× faster than npm)\nbun install\n\n# CI/CD (frozen lockfile)\nbun install --frozen-lockfile\n```\n\n**3. Add dependencies:**\n\n```bash\n# Production dependency\nbun add express\n\n# Dev dependency\nbun add -d typescript\n\n# Exact version\nbun add [email protected]\n```\n\n**4. Use workspaces:**\n\n```json\n{\n \"workspaces\": [\"packages/*\", \"apps/*\"]\n}\n```\n\n```bash\n# Run in specific workspace\nbun run --filter @myorg/ui build\n```\n\n**5. Security auditing:**\n\n```bash\n# Currently use npm audit (Bun audit in development)\nnpm audit\n```\n\n**6. Override transitive dependencies:**\n\n```json\n{\n \"overrides\": {\n \"axios\": \"1.6.0\"\n }\n}\n```\n\n**When to use Bun:**\n\n- Greenfield projects where speed is critical\n- Development environments (fast feedback)\n- Scripts and tooling (fast startup)\n\n**When to prefer pnpm:**\n\n- Enterprise monorepos requiring stable workspace support\n- Projects with complex peer dependency requirements\n- Maximum ecosystem compatibility needed\n\n---\n\n## Python (pip / poetry / conda / uv)\n\n### Tool Comparison (January 2026)\n\n| Tool | Use Case | Lockfile | Virtual Env | Speed |\n|------|----------|----------|-------------|-------|\n| **uv** (Astral) | All Python projects | `uv.lock` | Automatic | **10-100× faster** |\n| **pip** + **venv** | Simple projects | `requirements.txt` (pinned) | Manual (`venv`) | Baseline |\n| **pip-tools** | Production apps | `requirements.txt` (pinned) | Manual (`venv`) | Baseline |\n| **poetry** | Modern Python apps | `poetry.lock` | Automatic | Moderate |\n| **conda** | Data science, ML | `environment.yml` | Automatic | Slow |\n\n**Recommendations (January 2026):**\n\n- **New projects:** **uv** (10-100× faster than pip, replaces pip/poetry/virtualenv in single tool)\n- **Mature projects:** **Poetry** (battle-tested, excellent dependency resolution)\n- **Simple scripts:** pip + venv (minimal setup)\n- **Data science/ML:** **conda** (binary packages) or **uv** (faster environment setup)\n\n### pip + pip-tools Best Practices\n\n**1. Separate `requirements.in` (loose) from `requirements.txt` (pinned):**\n\n```ini\n# requirements.in (loose constraints)\nflask>=2.0.0\nrequests>=2.28.0\n```\n\n```bash\n# Generate pinned requirements.txt\npip-compile requirements.in\n```\n\n**Output (`requirements.txt`):**\n\n```ini\n# This file is autogenerated by pip-compile\nflask==2.3.2\n via -r requirements.in\nrequests==2.31.0\n via -r requirements.in\nclick==8.1.3\n via flask\n...\n```\n\n**2. Separate dev and production requirements:**\n\n```ini\n# requirements-dev.in\n-r requirements.txt\npytest>=7.0.0\nblack>=23.0.0\n```\n\n**3. Use virtual environments:**\n\n```bash\n# Create venv\npython3 -m venv venv\n\n# Activate\nsource venv/bin/activate # Unix\nvenv\\Scripts\\activate # Windows\n\n# Install dependencies\npip install -r requirements.txt\n```\n\n**4. Use constraints for transitive deps:**\n\n```ini\n# constraints.txt\nurllib3==1.26.18 # Pin transitive dependency\n```\n\n```bash\npip install -c constraints.txt -r requirements.txt\n```\n\n### Poetry Best Practices\n\n**1. Initialize project:**\n\n```bash\npoetry new myproject\ncd myproject\n```\n\n**2. Add dependencies:**\n\n```bash\n# Production dependency\npoetry add requests\n\n# Dev dependency\npoetry add --group dev pytest\n\n# Install all dependencies\npoetry install\n```\n\n**3. Use dependency groups:**\n\n```toml\n[tool.poetry.group.dev.dependencies]\npytest = \"^7.0.0\"\nblack = \"^23.0.0\"\n\n[tool.poetry.group.test.dependencies]\ncoverage = \"^7.0.0\"\n```\n\n**4. Lock without installing:**\n\n```bash\npoetry lock --no-update\n```\n\n**5. Export to requirements.txt:**\n\n```bash\npoetry export -f requirements.txt --output requirements.txt --without-hashes\n```\n\n**6. Configure poetry:**\n\n```bash\n# Use in-project virtualenv\npoetry config virtualenvs.in-project true\n\n# Don't create virtualenv (use system Python)\npoetry config virtualenvs.create false\n```\n\n### conda Best Practices\n\n**1. Create environment from file:**\n\n```yaml\n# environment.yml\nname: myproject\nchannels:\n - conda-forge\n - defaults\ndependencies:\n - python=3.10\n - numpy=1.24.0\n - pandas=2.0.0\n - scikit-learn=1.2.0\n - pip:\n - custom-package==1.0.0\n```\n\n```bash\nconda env create -f environment.yml\nconda activate myproject\n```\n\n**2. Export environment:**\n\n```bash\n# Export exact environment\nconda env export > environment.yml\n\n# Export cross-platform\nconda env export --from-history > environment.yml\n```\n\n**3. Update environment:**\n\n```bash\nconda env update -f environment.yml --prune\n```\n\n**4. Use conda-lock for reproducibility:**\n\n```bash\n# Install conda-lock\nconda install -c conda-forge conda-lock\n\n# Generate lockfile\nconda-lock -f environment.yml -p linux-64\n```\n\n### uv Best Practices (NEW - January 2026)\n\n**uv** by Astral is an ultra-fast Python package manager written in Rust. It replaces pip, pip-tools, pipx, poetry, pyenv, twine, and virtualenv in a single tool.\n\n**1. Install uv:**\n\n```bash\n# macOS/Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Windows\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# Via pip (if needed)\npip install uv\n```\n\n**2. Initialize project:**\n\n```bash\n# Create new project\nuv init myproject\ncd myproject\n\n# Creates pyproject.toml and uv.lock\n```\n\n**3. Add dependencies:**\n\n```bash\n# Add production dependency\nuv add requests\n\n# Add dev dependency\nuv add --dev pytest\n\n# Add with version constraint\nuv add \"flask>=2.0\"\n\n# Install all dependencies\nuv sync\n```\n\n**4. Run scripts and tools:**\n\n```bash\n# Run Python script\nuv run python script.py\n\n# Run tool (like pipx)\nuv tool run ruff check .\n\n# Install tool globally\nuv tool install ruff\n```\n\n**5. Manage Python versions:**\n\n```bash\n# Install Python version\nuv python install 3.12\n\n# List available versions\nuv python list\n\n# Pin version for project\nuv python pin 3.12\n```\n\n**6. CI/CD usage:**\n\n```bash\n# Install from lockfile (fast, reproducible)\nuv sync --frozen\n\n# Export to requirements.txt (for compatibility)\nuv export > requirements.txt\n```\n\n**7. Workspaces (monorepo):**\n\n```toml\n# pyproject.toml\n[tool.uv.workspace]\nmembers = [\"packages/*\"]\n```\n\n**Migration from Poetry:**\n\n```bash\n# uv can read pyproject.toml from Poetry\n# Just run:\nuv sync\n\n# This creates uv.lock from existing pyproject.toml\n```\n\n**When to use uv:**\n\n- All new Python projects (10-100× faster)\n- Existing projects wanting faster installs\n- Teams standardizing on single tool\n- CI/CD pipelines (massive time savings)\n\n**When Poetry may still be preferred:**\n\n- Complex plugin ecosystem requirements\n- Teams with heavy Poetry investment\n- Projects requiring Poetry-specific features\n\n---\n\n## Rust (Cargo)\n\n### Best Practices\n\n**1. Commit `Cargo.lock` for applications (not libraries):**\n\n**Applications:**\n\n```bash\ngit add Cargo.lock # GOOD: Commit for reproducibility\n```\n\n**Libraries:**\n\n```bash\necho \"Cargo.lock\" >> .gitignore # BAD: Don't commit (users generate their own)\n```\n\n**2. Use `cargo update` to update dependencies:**\n\n```bash\n# Update all dependencies\ncargo update\n\n# Update specific package\ncargo update -p serde\n\n# Preview updates without applying\ncargo update --dry-run\n```\n\n**3. Use `cargo audit` for security scanning:**\n\n```bash\n# Install cargo-audit\ncargo install cargo-audit\n\n# Run audit\ncargo audit\n\n# Fix vulnerabilities automatically\ncargo audit fix\n```\n\n**4. Leverage Cargo features for optional dependencies:**\n\n```toml\n[features]\ndefault = [\"serde\"]\nfull = [\"serde\", \"tokio\", \"async\"]\n\n[dependencies]\nserde = { version = \"1.0\", optional = true }\ntokio = { version = \"1.0\", optional = true }\n```\n\n**Usage:**\n\n```bash\n# Build with default features\ncargo build\n\n# Build with all features\ncargo build --all-features\n\n# Build with specific feature\ncargo build --features full\n```\n\n**5. Use workspaces for multi-crate projects:**\n\n```toml\n# Cargo.toml (workspace root)\n[workspace]\nmembers = [\n \"crates/core\",\n \"crates/api\",\n \"crates/cli\"\n]\n\n[workspace.dependencies]\nserde = \"1.0\" # Shared version\n```\n\n**6. Use `cargo-outdated` to check for updates:**\n\n```bash\ncargo install cargo-outdated\ncargo outdated\n```\n\n---\n\n## Go (go mod)\n\n### Best Practices\n\n**1. Use Go modules (standard since 1.11):**\n\n```bash\n# Initialize module\ngo mod init github.com/username/project\n\n# Add dependency (automatic)\ngo get github.com/pkg/errors\n\n# Download dependencies\ngo mod download\n```\n\n**2. Commit `go.sum` for reproducibility:**\n\n```bash\ngit add go.mod go.sum\n```\n\n**3. Use `go mod tidy` to clean up:**\n\n```bash\n# Remove unused dependencies\ngo mod tidy\n\n# Run before commits\n```\n\n**4. Vendor dependencies for enterprise projects:**\n\n```bash\n# Create vendor directory\ngo mod vendor\n\n# Build using vendored deps\ngo build -mod=vendor\n```\n\n**5. Use semantic import versioning for major versions:**\n\n```go\n// Import v2+\nimport \"github.com/pkg/errors/v2\"\n```\n\n```toml\n# go.mod\nrequire (\n github.com/pkg/errors/v2 v2.1.0\n)\n```\n\n**6. Use `go list` to inspect dependencies:**\n\n```bash\n# List all dependencies\ngo list -m all\n\n# List outdated dependencies\ngo list -u -m all\n\n# View dependency graph\ngo mod graph\n```\n\n---\n\n## Java (Maven / Gradle)\n\n### Maven Best Practices\n\n**1. Use dependency management section:**\n\n```xml\n\u003cdependencyManagement>\n \u003cdependencies>\n \u003cdependency>\n \u003cgroupId>org.springframework.boot\u003c/groupId>\n \u003cartifactId>spring-boot-dependencies\u003c/artifactId>\n \u003cversion>3.1.0\u003c/version>\n \u003ctype>pom\u003c/type>\n \u003cscope>import\u003c/scope>\n \u003c/dependency>\n \u003c/dependencies>\n\u003c/dependencyManagement>\n```\n\n**2. Use properties for versions:**\n\n```xml\n\u003cproperties>\n \u003cspring.version>6.0.0\u003c/spring.version>\n \u003cjackson.version>2.15.0\u003c/jackson.version>\n\u003c/properties>\n\n\u003cdependencies>\n \u003cdependency>\n \u003cgroupId>org.springframework\u003c/groupId>\n \u003cartifactId>spring-core\u003c/artifactId>\n \u003cversion>${spring.version}\u003c/version>\n \u003c/dependency>\n\u003c/dependencies>\n```\n\n**3. Use `mvn dependency:tree` to view dependencies:**\n\n```bash\nmvn dependency:tree\nmvn dependency:tree -Dverbose\n```\n\n**4. Check for updates:**\n\n```bash\nmvn versions:display-dependency-updates\n```\n\n### Gradle Best Practices\n\n**1. Use version catalogs (Gradle 7.0+):**\n\n```toml\n# gradle/libs.versions.toml\n[versions]\nspring = \"6.0.0\"\njackson = \"2.15.0\"\n\n[libraries]\nspring-core = { module = \"org.springframework:spring-core\", version.ref = \"spring\" }\njackson-databind = { module = \"com.fasterxml.jackson.core:jackson-databind\", version.ref = \"jackson\" }\n```\n\n```groovy\n// build.gradle\ndependencies {\n implementation libs.spring.core\n implementation libs.jackson.databind\n}\n```\n\n**2. Use dependency constraints:**\n\n```groovy\ndependencies {\n constraints {\n implementation 'org.apache.commons:commons-lang3:3.12.0'\n }\n}\n```\n\n**3. View dependency tree:**\n\n```bash\n./gradlew dependencies\n./gradlew dependencies --configuration runtimeClasspath\n```\n\n---\n\n## PHP (Composer)\n\n### Best Practices\n\n**1. Commit `composer.lock`:**\n\n```bash\ngit add composer.lock\n```\n\n**2. Use `composer install` (not `composer update`) in production:**\n\n```bash\n# Production\ncomposer install --no-dev --optimize-autoloader\n\n# Development\ncomposer install\n```\n\n**3. Use version constraints:**\n\n```json\n{\n \"require\": {\n \"symfony/http-foundation\": \"^6.0\",\n \"guzzlehttp/guzzle\": \"~7.4\"\n }\n}\n```\n\n**4. Check for security vulnerabilities:**\n\n```bash\ncomposer audit\n```\n\n**5. View dependency tree:**\n\n```bash\ncomposer show --tree\n```\n\n---\n\n## .NET (NuGet)\n\n### Best Practices\n\n**1. Use Central Package Management:**\n\n```xml\n\u003c!-- Directory.Packages.props -->\n\u003cProject>\n \u003cPropertyGroup>\n \u003cManagePackageVersionsCentrally>true\u003c/ManagePackageVersionsCentrally>\n \u003c/PropertyGroup>\n \u003cItemGroup>\n \u003cPackageVersion Include=\"Newtonsoft.Json\" Version=\"13.0.3\" />\n \u003c/ItemGroup>\n\u003c/Project>\n```\n\n**2. Use `packages.lock.json`:**\n\n```bash\ndotnet restore --use-lock-file\n```\n\n**3. Check for updates:**\n\n```bash\ndotnet list package --outdated\n```\n\n**4. Audit for vulnerabilities:**\n\n```bash\ndotnet list package --vulnerable\n```\n\n---\n\n## Summary Table (January 2026)\n\n| Ecosystem | Package Manager | Lockfile | Best Tool | Security Audit |\n|-----------|-----------------|----------|-----------|----------------|\n| **Node.js** | npm/yarn/pnpm/Bun | `pnpm-lock.yaml` / `bun.lock` | **pnpm** or **Bun** | `npm audit` |\n| **Python** | pip/poetry/conda/uv | `uv.lock` / `poetry.lock` | **uv** | `pip-audit` |\n| **Rust** | cargo | `Cargo.lock` | cargo | `cargo audit` |\n| **Go** | go mod | `go.sum` | go mod | `govulncheck` |\n| **Java** | maven/gradle | n/a / lockfile (Gradle 6.8+) | gradle | `mvn dependency-check` |\n| **PHP** | composer | `composer.lock` | composer | `composer audit` |\n| **.NET** | nuget | `packages.lock.json` | dotnet | `dotnet list package --vulnerable` |\n\n---\n\n## Quick Decision Guide (January 2026)\n\n**Choose package manager based on:**\n\n| Scenario | Recommendation |\n|----------|----------------|\n| New Node.js project | **pnpm** (stable, fast) or **Bun** (fastest) |\n| Enterprise Node.js monorepo | **pnpm** (best workspace support) |\n| Speed-focused JS development | **Bun** (7× faster than npm) |\n| Existing npm project | Stay with npm or migrate to pnpm |\n| New Python project | **uv** (10-100× faster than pip) |\n| Python application (mature) | **Poetry** or **uv** |\n| Simple Python scripts | pip + venv or uv |\n| Data science / ML | **conda** or **uv** |\n| Rust project | cargo (default) |\n| Go project | go mod (default) |\n| Java enterprise | maven or gradle |\n| PHP project | composer |\n| .NET project | nuget |\n\n---\n\n## Ecosystem-Specific Anti-Patterns\n\n### Node.js\n\n- [FAIL] Using `npm install` in CI (use `npm ci`)\n- [FAIL] Not committing lockfiles\n- [FAIL] Using `--force` or `--legacy-peer-deps` without understanding why\n- [FAIL] Mixing package managers (npm + yarn in same project)\n\n### Python\n\n- [FAIL] Not using virtual environments\n- [FAIL] Using `sudo pip install` (system-wide installs)\n- [FAIL] Not pinning versions in `requirements.txt`\n- [FAIL] Mixing conda and pip aggressively\n\n### Rust\n\n- [FAIL] Committing `Cargo.lock` for libraries (only for binaries)\n- [FAIL] Not using `cargo audit` for security\n- [FAIL] Ignoring `cargo clippy` warnings\n\n### Go\n\n- [FAIL] Not committing `go.sum`\n- [FAIL] Using `go get` to install tools (use `go install`)\n- [FAIL] Not running `go mod tidy` regularly\n\n---\n\n**Remember:** Each ecosystem has its own conventions and best practices. Follow the ecosystem's standards for the smoothest experience.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":18411,"content_sha256":"68cc0699068197bc0c82c94e2ce874fa3d28b6a60fd131762e9790a57bcdbe10"},{"filename":"references/lockfile-management.md","content":"# Lockfile Management Deep Dive\n\nComprehensive guide to understanding, managing, and troubleshooting lockfiles across package managers.\n\n## Table of Contents\n\n- [What Are Lockfiles?](#what-are-lockfiles)\n- [Lockfiles by Package Manager](#lockfiles-by-package-manager)\n- [Lockfile Anatomy](#lockfile-anatomy)\n- [Common Workflows](#common-workflows)\n- [Troubleshooting](#troubleshooting)\n- [Best Practices](#best-practices)\n\n---\n\n## What Are Lockfiles?\n\n**Lockfiles** are automatically generated files that record the **exact version** of every dependency (direct and transitive) installed in a project.\n\n### Purpose\n\n1. **Reproducibility:** Ensure identical dependency versions across dev, CI, and production\n2. **Consistency:** Prevent \"works on my machine\" issues\n3. **Security:** Lock known-good versions, avoid surprise updates\n4. **Performance:** Faster installs (no version resolution needed)\n\n### Without Lockfiles (Bad)\n\n```json\n// package.json\n{\n \"dependencies\": {\n \"express\": \"^4.18.2\"\n }\n}\n```\n\n**Developer A installs (Jan 2024):** `[email protected]` with `[email protected]`\n\n**Developer B installs (Mar 2024):** `[email protected]` with `[email protected]` (new patch release)\n\n**Result:** Different dependency trees, potential bugs\n\n### With Lockfiles (Good)\n\n```\n// package-lock.json (committed to git)\n\"body-parser\": {\n \"version\": \"1.20.1\", // Exact version locked\n \"resolved\": \"https://registry.npmjs.org/body-parser/-/body-parser-1.20.1.tgz\",\n \"integrity\": \"sha512-...\"\n}\n```\n\n**Both developers:** Install identical `[email protected]`\n\n**Result:** Reproducible builds\n\n---\n\n## Lockfiles by Package Manager\n\n### npm: package-lock.json\n\n**Format:** JSON\n**Introduced:** npm v5 (2017)\n**Location:** Project root\n\n**Key fields:**\n\n```json\n{\n \"name\": \"my-project\",\n \"version\": \"1.0.0\",\n \"lockfileVersion\": 3,\n \"requires\": true,\n \"packages\": {\n \"node_modules/express\": {\n \"version\": \"4.18.2\",\n \"resolved\": \"https://registry.npmjs.org/express/-/express-4.18.2.tgz\",\n \"integrity\": \"sha512-...\",\n \"dependencies\": {\n \"body-parser\": \"1.20.1\"\n }\n }\n }\n}\n```\n\n**Commands:**\n\n```bash\n# Generate/update lockfile\nnpm install\n\n# Install from lockfile (exact versions)\nnpm ci\n\n# Update specific package\nnpm update express\n\n# Regenerate lockfile\nrm package-lock.json && npm install\n```\n\n### pnpm: pnpm-lock.yaml\n\n**Format:** YAML\n**Introduced:** pnpm v1 (2017)\n**Location:** Project root\n\n**Key fields:**\n\n```yaml\nlockfileVersion: '6.0'\n\ndependencies:\n express:\n specifier: ^4.18.2\n version: 4.18.2\n\npackages:\n /[email protected]:\n resolution: {integrity: sha512-...}\n dependencies:\n body-parser: 1.20.1\n```\n\n**Advantages:**\n\n- Human-readable YAML\n- Smaller file size\n- Content-addressable storage\n\n**Commands:**\n\n```bash\n# Generate/update lockfile\npnpm install\n\n# Install from lockfile\npnpm install --frozen-lockfile\n\n# Update specific package\npnpm update express\n\n# Regenerate lockfile\npnpm install --force\n```\n\n### Yarn: yarn.lock\n\n**Format:** Custom (YAML-like)\n**Introduced:** Yarn v1 (2016)\n**Location:** Project root\n\n**Key fields:**\n\n```\n# Yarn v1 format\nexpress@^4.18.2:\n version \"4.18.2\"\n resolved \"https://registry.yarnpkg.com/express/-/express-4.18.2.tgz#...\"\n integrity sha512-...\n dependencies:\n body-parser \"1.20.1\"\n```\n\n**Commands:**\n\n```bash\n# Generate/update lockfile\nyarn install\n\n# Install from lockfile (exact versions)\nyarn install --frozen-lockfile\n\n# Update specific package\nyarn upgrade express\n\n# Regenerate lockfile\nrm yarn.lock && yarn install\n```\n\n### Poetry: poetry.lock\n\n**Format:** TOML\n**Introduced:** Poetry v0.1 (2018)\n**Location:** Project root\n\n**Key fields:**\n\n```toml\n[[package]]\nname = \"requests\"\nversion = \"2.28.2\"\ndescription = \"HTTP library\"\ncategory = \"main\"\noptional = false\npython-versions = \">=3.7\"\n\n[package.dependencies]\ncertifi = \">=2017.4.17\"\ncharset-normalizer = \">=2,\u003c4\"\n```\n\n**Commands:**\n\n```bash\n# Generate/update lockfile\npoetry lock\n\n# Install from lockfile\npoetry install\n\n# Update specific package\npoetry update requests\n\n# Regenerate lockfile\npoetry lock --no-update\n```\n\n### Cargo: Cargo.lock\n\n**Format:** TOML\n**Introduced:** Cargo v0.1 (2014)\n**Location:** Project root\n\n**Key fields:**\n\n```toml\n[[package]]\nname = \"serde\"\nversion = \"1.0.160\"\nsource = \"registry+https://github.com/rust-lang/crates.io-index\"\nchecksum = \"bb2f3770c8bce3bcda7e149193a069a0f4365bda1fa5cd88e03bca26afc1216c\"\ndependencies = [\n \"serde_derive\",\n]\n```\n\n**When to commit:**\n\n- [OK] Applications: Always commit\n- [FAIL] Libraries: Do NOT commit (allows consumers to use latest compatible versions)\n\n**Commands:**\n\n```bash\n# Generate/update lockfile\ncargo build\n\n# Update specific dependency\ncargo update serde\n\n# Update all dependencies\ncargo update\n```\n\n---\n\n## Lockfile Anatomy\n\n### Dependency Tree Flattening\n\n**package.json (logical tree):**\n\n```\nmy-app\n├── express@^4.18.2\n│ └── body-parser@^1.20.0\n└── body-parser@^1.20.0\n```\n\n**package-lock.json (flattened):**\n\n```json\n{\n \"dependencies\": {\n \"express\": {\n \"version\": \"4.18.2\",\n \"requires\": {\n \"body-parser\": \"1.20.1\"\n }\n },\n \"body-parser\": {\n \"version\": \"1.20.1\" // Single copy (deduplicated)\n }\n }\n}\n```\n\n### Integrity Hashes\n\n**Purpose:** Verify package hasn't been tampered with\n\n**SHA-512 hash format:**\n\n```json\n\"integrity\": \"sha512-5tK7EtrZ0N+OLFMthtqOj4fI2Jeb88C4CAZPu25LDVUvVLBaVsx3DdvKmjchNCd/6+Iq3YDDtdT1VrUrL8lPLg==\"\n```\n\n**Verification:**\n\n```bash\n# npm verifies automatically on install\nnpm ci\n\n# Manual verification\nshasum -a 512 -b downloaded-package.tgz\n```\n\n### Lockfile Versions\n\n**npm lockfileVersion:**\n\n- `1` - npm 5-6 (legacy)\n- `2` - npm 7+ (supports workspaces)\n- `3` - npm 9+ (current, optimized format)\n\n**Backwards compatibility:** npm 9 can read all versions\n\n---\n\n## Common Workflows\n\n### Adding a New Dependency\n\n```bash\n# npm\nnpm install lodash\n# Automatically updates package.json + package-lock.json\n\n# pnpm\npnpm add lodash\n# Updates package.json + pnpm-lock.yaml\n\n# yarn\nyarn add lodash\n# Updates package.json + yarn.lock\n\n# poetry\npoetry add requests\n# Updates pyproject.toml + poetry.lock\n```\n\n**What happens:**\n\n1. Package manager resolves version from range\n2. Downloads package + dependencies\n3. Updates lockfile with exact versions\n4. Installs to `node_modules`\n\n**Commit:**\n\n```bash\ngit add package.json package-lock.json\ngit commit -m \"feat: add lodash for utility functions\"\n```\n\n### Updating Dependencies\n\n**Update all patch/minor versions:**\n\n```bash\n# npm\nnpm update\n\n# pnpm\npnpm update\n\n# yarn\nyarn upgrade\n\n# poetry\npoetry update\n```\n\n**Update specific package:**\n\n```bash\n# npm\nnpm update express\n\n# pnpm\npnpm update express\n\n# yarn\nyarn upgrade express\n\n# poetry\npoetry update requests\n```\n\n**Update to latest (including major versions):**\n\n```bash\n# npm\nnpm install express@latest\n\n# pnpm\npnpm update express --latest\n\n# yarn\nyarn upgrade express --latest\n\n# poetry\npoetry add requests@latest\n```\n\n### CI/CD: Installing from Lockfile\n\n**Principle:** CI should install **exact** versions from lockfile, not resolve versions\n\n**npm:**\n\n```bash\n# BAD: Wrong (resolves versions from package.json)\nnpm install\n\n# GOOD: Correct (installs exact versions from lockfile)\nnpm ci\n```\n\n**pnpm:**\n\n```bash\n# GOOD: Use frozen lockfile\npnpm install --frozen-lockfile\n```\n\n**yarn:**\n\n```bash\n# GOOD: Use frozen lockfile\nyarn install --frozen-lockfile\n```\n\n**poetry:**\n\n```bash\n# GOOD: Install without updating lockfile\npoetry install --no-root\n```\n\n### Resolving Lockfile Conflicts\n\n**Scenario:** Two developers add different dependencies, merge conflict in lockfile\n\n**BAD: Wrong approach:**\n\n```bash\n# Manually edit lockfile to resolve conflict\n# (will cause corruption)\n```\n\n**GOOD: Correct approach:**\n\n```bash\n# 1. Resolve package.json conflicts first\ngit checkout --ours package.json\n# or\ngit checkout --theirs package.json\n# or manually merge\n\n# 2. Delete lockfile\nrm package-lock.json\n\n# 3. Regenerate from resolved package.json\nnpm install\n\n# 4. Commit\ngit add package.json package-lock.json\ngit commit -m \"chore: resolve dependency conflicts\"\n```\n\n---\n\n## Troubleshooting\n\n### Issue: \"Lockfile out of sync\"\n\n**Error:**\n\n```\nnpm ERR! code EUSAGE\nnpm ERR! `npm ci` can only install packages when your package.json and package-lock.json are in sync.\n```\n\n**Cause:** `package.json` was modified without updating lockfile\n\n**Fix:**\n\n```bash\n# Regenerate lockfile\nnpm install\n\n# Or delete and reinstall\nrm package-lock.json && npm install\n```\n\n### Issue: \"Different lockfile versions\"\n\n**Error:**\n\n```\nnpm WARN old lockfile\nnpm WARN old lockfile The package-lock.json file was created with an old version of npm\n```\n\n**Cause:** Lockfile created with npm 6, now using npm 9\n\n**Fix:**\n\n```bash\n# Update to latest lockfile format\nnpm install --lockfile-version=3\n```\n\n### Issue: \"Integrity checksum failed\"\n\n**Error:**\n\n```\nnpm ERR! Integrity check failed for express\nnpm ERR! sha512-... !== sha512-...\n```\n\n**Cause:** Package was modified/corrupted, or lockfile is stale\n\n**Fix:**\n\n```bash\n# Clear npm cache\nnpm cache clean --force\n\n# Reinstall\nrm -rf node_modules package-lock.json\nnpm install\n```\n\n### Issue: \"Cannot find module after install\"\n\n**Error:**\n\n```\nError: Cannot find module 'express'\n```\n\n**Cause:** Lockfile and `node_modules` out of sync\n\n**Fix:**\n\n```bash\n# Clean install\nrm -rf node_modules\nnpm ci\n```\n\n### Issue: \"Peer dependency conflicts\"\n\n**Error:**\n\n```\nnpm ERR! ERESOLVE unable to resolve dependency tree\nnpm ERR! Could not resolve dependency:\nnpm ERR! peer react@\"^18.0.0\" from [email protected]\n```\n\n**Fix Option 1: Update dependencies**\n\n```bash\nnpm install react@18 react-dom@18\n```\n\n**Fix Option 2: Use legacy peer deps (temporary)**\n\n```bash\nnpm install --legacy-peer-deps\n```\n\n**Fix Option 3: Override (npm 8.3+)**\n\n```json\n{\n \"overrides\": {\n \"react\": \"^18.0.0\"\n }\n}\n```\n\n---\n\n## Best Practices\n\n### 1. Always Commit Lockfiles\n\n```bash\n# GOOD: Commit lockfiles\ngit add package-lock.json\ngit commit -m \"chore: update dependencies\"\n\n# BAD: Never add to .gitignore\n# echo \"package-lock.json\" >> .gitignore # DON'T DO THIS\n```\n\n**Exception:** Rust libraries (Cargo.lock should NOT be committed for libraries)\n\n### 2. Use CI-Specific Install Commands\n\n```yaml\n# GitHub Actions\n- name: Install dependencies\n run: npm ci # NOT npm install\n\n# GitLab CI\nscript:\n - npm ci\n```\n\n### 3. Keep Lockfile Format Consistent\n\n**Enforce npm version in CI:**\n\n```json\n{\n \"engines\": {\n \"node\": \">=18.0.0\",\n \"npm\": \">=9.0.0\"\n }\n}\n```\n\n**Use .nvmrc:**\n\n```bash\necho \"18.16.0\" > .nvmrc\nnvm use\n```\n\n### 4. Don't Manually Edit Lockfiles\n\n```bash\n# BAD: Wrong\nvi package-lock.json # Manual edits will be overwritten\n\n# GOOD: Correct\nnpm install \u003cpackage> # Let package manager update lockfile\n```\n\n### 5. Regenerate Lockfile After Major Changes\n\n```bash\n# After switching branches with different dependencies\nrm package-lock.json\nnpm install\n\n# After upgrading Node.js major version\nrm package-lock.json\nnpm install\n```\n\n### 6. Use Lockfile in Docker Builds\n\n**Dockerfile:**\n\n```dockerfile\n# Copy lockfile first (better caching)\nCOPY package.json package-lock.json ./\nRUN npm ci --only=production\n\n# Then copy source code\nCOPY . .\nRUN npm run build\n```\n\n### 7. Verify Lockfile in CI\n\n```yaml\n# GitHub Actions\n- name: Verify lockfile\n run: |\n npm ci\n git diff --exit-code package-lock.json\n```\n\n### 8. Use Lockfile Analysis Tools\n\n```bash\n# Check for known vulnerabilities\nnpm audit\n\n# Analyze lockfile size\nnpx lockfile-lint --path package-lock.json\n\n# Check for malicious packages\nnpx socket-cli report create\n```\n\n---\n\n## Lockfile Format Comparison\n\n| Feature | npm | pnpm | yarn | poetry | cargo |\n|---------|-----|------|------|--------|-------|\n| **Format** | JSON | YAML | Custom | TOML | TOML |\n| **Human-readable** | No | Yes | Yes | Yes | Yes |\n| **File size** | Large | Small | Medium | Medium | Medium |\n| **Merge conflicts** | Frequent | Rare | Moderate | Rare | Rare |\n| **Integrity hashes** | Yes | Yes | Yes | Yes | Yes |\n| **Workspace support** | Yes | Yes | Yes | Yes | Yes |\n\n---\n\n## Resources\n\n- [npm package-lock.json](https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json)\n- [pnpm lockfile](https://pnpm.io/git#lockfiles)\n- [Yarn lockfile](https://classic.yarnpkg.com/en/docs/yarn-lock)\n- [Poetry lockfile](https://python-poetry.org/docs/basic-usage/#installing-with-poetrylock)\n- [Cargo lockfile](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html)\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":12497,"content_sha256":"c768a9d66ec93eaf592f8e1c4384419d6a3d9c67aa487e8ba56764eac2ff5fe0"},{"filename":"references/monorepo-patterns.md","content":"# Monorepo Patterns and Best Practices\n\nComprehensive guide to managing monorepos with workspaces, build optimization, and dependency management.\n\n## Table of Contents\n\n- [What is a Monorepo?](#what-is-a-monorepo)\n- [Workspace Tools](#workspace-tools)\n- [Monorepo Structure](#monorepo-structure)\n- [Dependency Management](#dependency-management)\n- [Build Optimization](#build-optimization)\n- [Common Patterns](#common-patterns)\n- [Migration Strategies](#migration-strategies)\n- [Best Practices](#best-practices)\n\n---\n\n## What is a Monorepo?\n\nA **monorepo** (monolithic repository) is a single repository containing multiple related projects or packages.\n\n### Monorepo vs Polyrepo\n\n| Aspect | Monorepo | Polyrepo |\n|--------|----------|----------|\n| **Code location** | Single repository | Multiple repositories |\n| **Dependencies** | Shared, linked locally | Published to registry |\n| **Versioning** | Coordinated or independent | Independent |\n| **Tooling** | Workspace-aware tools | Standard tools |\n| **CI/CD** | Single pipeline, affected packages | Per-repository pipelines |\n\n### When to Use a Monorepo\n\n[OK] **Good fit:**\n- Multiple packages with shared code\n- Coordinated releases across packages\n- Internal tools and applications\n- Frontend + backend in same project\n- Design system + applications using it\n\n[FAIL] **Not recommended:**\n- Completely independent projects\n- Different tech stacks with no overlap\n- External/public libraries (better as separate repos)\n\n---\n\n## Workspace Tools\n\n### pnpm (Recommended)\n\n**Why pnpm:**\n- 3x faster than npm/yarn\n- Uses 1/3 disk space (hard links)\n- Strict dependency isolation\n- Best monorepo support\n\n**Installation:**\n```bash\nnpm install -g pnpm\n```\n\n**Configuration (`pnpm-workspace.yaml`):**\n```yaml\npackages:\n - 'packages/*'\n - 'apps/*'\n```\n\n**Commands:**\n```bash\n# Install all dependencies\npnpm install\n\n# Add dependency to specific package\npnpm add lodash --filter @myorg/ui\n\n# Run script in all packages\npnpm -r build\n\n# Run script in specific package\npnpm --filter @myorg/api-client test\n\n# Run script in packages matching pattern\npnpm --filter \"./packages/*\" build\n\n# Update dependencies\npnpm update -r\n```\n\n### npm Workspaces\n\n**Configuration (`package.json`):**\n```json\n{\n \"name\": \"my-monorepo\",\n \"workspaces\": [\n \"packages/*\",\n \"apps/*\"\n ]\n}\n```\n\n**Commands:**\n```bash\n# Install all dependencies\nnpm install\n\n# Add dependency to specific workspace\nnpm install lodash --workspace=@myorg/ui\n\n# Run script in all workspaces\nnpm run build --workspaces\n\n# Run script in specific workspace\nnpm run test --workspace=@myorg/api-client\n```\n\n### Yarn Workspaces\n\n**Configuration (`package.json`):**\n```json\n{\n \"private\": true,\n \"workspaces\": {\n \"packages\": [\n \"packages/*\",\n \"apps/*\"\n ]\n }\n}\n```\n\n**Commands:**\n```bash\n# Install all dependencies\nyarn install\n\n# Add dependency to specific workspace\nyarn workspace @myorg/ui add lodash\n\n# Run script in all workspaces\nyarn workspaces run build\n\n# Run script in specific workspace\nyarn workspace @myorg/api-client test\n```\n\n---\n\n## Monorepo Structure\n\n### Recommended Directory Structure\n\n```\nmy-monorepo/\n├── package.json # Root package.json\n├── pnpm-workspace.yaml # Workspace configuration\n├── turbo.json # Turborepo configuration (optional)\n├── .github/\n│ └── workflows/\n│ └── ci.yml # CI/CD pipeline\n├── packages/ # Shared libraries\n│ ├── ui/\n│ │ ├── package.json\n│ │ ├── src/\n│ │ └── tsconfig.json\n│ ├── utils/\n│ │ ├── package.json\n│ │ └── src/\n│ └── api-client/\n│ ├── package.json\n│ └── src/\n├── apps/ # Applications\n│ ├── web/ # Next.js app\n│ │ ├── package.json\n│ │ ├── next.config.js\n│ │ └── src/\n│ └── docs/ # Documentation site\n│ ├── package.json\n│ └── src/\n├── tools/ # Build tools and scripts\n│ └── eslint-config/\n│ └── package.json\n└── docs/ # Documentation\n └── README.md\n```\n\n### Package Naming Convention\n\nUse **scoped packages** for organization:\n\n```json\n{\n \"name\": \"@myorg/ui\",\n \"name\": \"@myorg/utils\",\n \"name\": \"@myorg/api-client\",\n \"name\": \"@myorg/web-app\"\n}\n```\n\n---\n\n## Dependency Management\n\n### Hoisting Dependencies\n\nWorkspace tools **hoist** shared dependencies to the root `node_modules`:\n\n```\nmy-monorepo/\n├── node_modules/\n│ ├── react \u003c- Shared, hoisted to root\n│ ├── lodash \u003c- Shared, hoisted to root\n│ └── @myorg/\n│ ├── ui \u003c- Symlink to packages/ui\n│ └── utils \u003c- Symlink to packages/utils\n├── packages/\n│ ├── ui/\n│ │ └── node_modules/\n│ │ └── clsx \u003c- Package-specific, not hoisted\n│ └── utils/\n│ └── package.json\n```\n\n### Internal Package Dependencies\n\n**packages/web-app/package.json:**\n```json\n{\n \"name\": \"@myorg/web-app\",\n \"dependencies\": {\n \"@myorg/ui\": \"workspace:*\",\n \"@myorg/utils\": \"workspace:^1.0.0\",\n \"react\": \"^18.2.0\"\n }\n}\n```\n\n**Workspace protocol versions:**\n- `workspace:*` - Always use workspace version\n- `workspace:^1.0.0` - Use workspace version if it satisfies constraint\n- `workspace:~1.0.0` - Stricter constraint\n\n### Root vs Package Dependencies\n\n**Root `package.json` (shared devDependencies):**\n```json\n{\n \"name\": \"my-monorepo\",\n \"private\": true,\n \"devDependencies\": {\n \"typescript\": \"^5.0.0\",\n \"eslint\": \"^8.0.0\",\n \"prettier\": \"^3.0.0\",\n \"turbo\": \"^1.10.0\"\n }\n}\n```\n\n**Package-specific `package.json`:**\n```json\n{\n \"name\": \"@myorg/ui\",\n \"dependencies\": {\n \"react\": \"^18.2.0\",\n \"clsx\": \"^2.0.0\"\n },\n \"devDependencies\": {\n \"@types/react\": \"^18.2.0\"\n }\n}\n```\n\n**Rule of thumb:**\n- **Root:** Tooling used by ALL packages (ESLint, TypeScript, Prettier)\n- **Packages:** Dependencies specific to that package\n\n### Version Synchronization\n\n**Option 1: Synchronized versions (coordinated release)**\n```json\n// All packages use same version\n{\n \"name\": \"@myorg/ui\",\n \"version\": \"1.5.0\"\n}\n{\n \"name\": \"@myorg/utils\",\n \"version\": \"1.5.0\"\n}\n```\n\n**Tools:** Lerna, Changesets\n\n**Option 2: Independent versions**\n```json\n{\n \"name\": \"@myorg/ui\",\n \"version\": \"2.3.1\"\n}\n{\n \"name\": \"@myorg/utils\",\n \"version\": \"1.8.0\"\n}\n```\n\n**Recommendation:** Use synchronized versions for tightly coupled packages, independent for loosely coupled.\n\n---\n\n## Build Optimization\n\n### Turborepo (Recommended)\n\n**Why Turborepo:**\n- Incremental builds (only rebuild what changed)\n- Remote caching (share builds across CI and developers)\n- Task scheduling and parallelization\n- Excellent DX\n\n**Installation:**\n```bash\npnpm add -D turbo\n```\n\n**Configuration (`turbo.json`):**\n```json\n{\n \"$schema\": \"https://turbo.build/schema.json\",\n \"pipeline\": {\n \"build\": {\n \"dependsOn\": [\"^build\"],\n \"outputs\": [\"dist/**\", \".next/**\"]\n },\n \"test\": {\n \"dependsOn\": [\"build\"],\n \"outputs\": []\n },\n \"lint\": {\n \"outputs\": []\n },\n \"dev\": {\n \"cache\": false,\n \"persistent\": true\n }\n }\n}\n```\n\n**Commands:**\n```bash\n# Build all packages (with caching)\nturbo run build\n\n# Build specific package\nturbo run build --filter=@myorg/ui\n\n# Build with remote caching\nturbo run build --token=\u003cyour-token>\n```\n\n### Nx (Alternative)\n\n**Why Nx:**\n- Computation caching\n- Dependency graph visualization\n- Affected command (only build what changed)\n- Plugin ecosystem\n\n**Installation:**\n```bash\nnpx create-nx-workspace@latest\n```\n\n**Commands:**\n```bash\n# Build all projects\nnx run-many --target=build --all\n\n# Build only affected projects\nnx affected:build\n\n# Visualize dependency graph\nnx graph\n```\n\n---\n\n## Common Patterns\n\n### Pattern 1: Shared TypeScript Configuration\n\n**Root `tsconfig.json`:**\n```json\n{\n \"compilerOptions\": {\n \"target\": \"ES2020\",\n \"module\": \"ESNext\",\n \"lib\": [\"ES2020\", \"DOM\"],\n \"jsx\": \"react-jsx\",\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true,\n \"forceConsistentCasingInFileNames\": true\n }\n}\n```\n\n**packages/ui/tsconfig.json:**\n```json\n{\n \"extends\": \"../../tsconfig.json\",\n \"compilerOptions\": {\n \"outDir\": \"dist\",\n \"rootDir\": \"src\"\n },\n \"include\": [\"src\"],\n \"exclude\": [\"node_modules\", \"dist\"]\n}\n```\n\n### Pattern 2: Shared ESLint Configuration\n\n**packages/eslint-config/package.json:**\n```json\n{\n \"name\": \"@myorg/eslint-config\",\n \"main\": \"index.js\",\n \"dependencies\": {\n \"eslint\": \"^8.0.0\",\n \"eslint-plugin-react\": \"^7.32.0\"\n }\n}\n```\n\n**packages/eslint-config/index.js:**\n```javascript\nmodule.exports = {\n extends: ['eslint:recommended', 'plugin:react/recommended'],\n rules: {\n 'no-console': 'warn'\n }\n};\n```\n\n**packages/ui/.eslintrc.js:**\n```javascript\nmodule.exports = {\n extends: ['@myorg/eslint-config']\n};\n```\n\n### Pattern 3: Shared Build Scripts\n\n**Root `package.json`:**\n```json\n{\n \"scripts\": {\n \"build\": \"turbo run build\",\n \"test\": \"turbo run test\",\n \"lint\": \"turbo run lint\",\n \"dev\": \"turbo run dev --parallel\",\n \"clean\": \"turbo run clean && rm -rf node_modules\",\n \"format\": \"prettier --write \\\"**/*.{js,jsx,ts,tsx,json,md}\\\"\"\n }\n}\n```\n\n### Pattern 4: Cross-Package Imports\n\n**packages/web-app/src/App.tsx:**\n```typescript\nimport { Button } from '@myorg/ui';\nimport { formatDate } from '@myorg/utils';\n\nexport function App() {\n return (\n \u003cButton onClick={() => console.log(formatDate(new Date()))}>\n Click me\n \u003c/Button>\n );\n}\n```\n\nNo build step needed - imports work directly via workspace symlinks!\n\n---\n\n## Migration Strategies\n\n### Migrating from Polyrepo to Monorepo\n\n**Step 1: Create monorepo structure**\n```bash\nmkdir my-monorepo\ncd my-monorepo\nnpm init -y\n```\n\n**Step 2: Add workspace configuration**\n```json\n{\n \"name\": \"my-monorepo\",\n \"private\": true,\n \"workspaces\": [\"packages/*\", \"apps/*\"]\n}\n```\n\n**Step 3: Move repositories**\n```bash\nmkdir -p packages apps\ngit clone https://github.com/myorg/ui.git packages/ui\ngit clone https://github.com/myorg/web-app.git apps/web-app\n```\n\n**Step 4: Update package names**\n```json\n// packages/ui/package.json\n{\n \"name\": \"@myorg/ui\", // Add scope\n \"version\": \"1.0.0\"\n}\n```\n\n**Step 5: Replace published dependencies with workspace dependencies**\n```json\n// Before (apps/web-app/package.json)\n{\n \"dependencies\": {\n \"ui\": \"^1.0.0\" // Published to npm\n }\n}\n\n// After\n{\n \"dependencies\": {\n \"@myorg/ui\": \"workspace:*\" // Local workspace\n }\n}\n```\n\n**Step 6: Install and test**\n```bash\npnpm install\npnpm run build\npnpm run test\n```\n\n---\n\n## Best Practices\n\n### 1. Use pnpm for Performance\n\n```bash\n# 3x faster installs, 1/3 disk usage\npnpm install\n```\n\n### 2. Enable Turborepo/Nx for Caching\n\n```bash\n# Only rebuild what changed\nturbo run build\n```\n\n### 3. Use Workspace Protocol\n\n```json\n{\n \"dependencies\": {\n \"@myorg/ui\": \"workspace:*\" // NOT \"workspace:../packages/ui\"\n }\n}\n```\n\n### 4. Hoist Shared Dependencies\n\nLet the package manager hoist dependencies automatically:\n\n```bash\n# pnpm hoists automatically\npnpm install\n\n# Yarn requires configuration\n# .yarnrc.yml\nnmHoistingLimits: workspaces\n```\n\n### 5. Use Path Aliases for Imports\n\n**tsconfig.json:**\n```json\n{\n \"compilerOptions\": {\n \"paths\": {\n \"@myorg/*\": [\"./packages/*/src\"]\n }\n }\n}\n```\n\n### 6. Consistent Tooling Across Packages\n\n- Same TypeScript version\n- Same ESLint rules\n- Same Prettier configuration\n- Same Node.js version\n\n### 7. CI/CD: Build Only Affected Packages\n\n**GitHub Actions with Turborepo:**\n```yaml\nname: CI\n\non: [push, pull_request]\n\njobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - uses: pnpm/action-setup@v2\n - run: pnpm install\n - run: pnpm turbo run build test lint\n```\n\n**With remote caching:**\n```yaml\n- run: pnpm turbo run build --token=${{ secrets.TURBO_TOKEN }}\n```\n\n### 8. Use Changesets for Versioning\n\n**Installation:**\n```bash\npnpm add -D @changesets/cli\npnpm changeset init\n```\n\n**Workflow:**\n```bash\n# Create changeset\npnpm changeset\n\n# Version packages\npnpm changeset version\n\n# Publish\npnpm changeset publish\n```\n\n### 9. Separate Public and Private Packages\n\n```json\n// Public package (published to npm)\n{\n \"name\": \"@myorg/ui\",\n \"private\": false,\n \"publishConfig\": {\n \"access\": \"public\"\n }\n}\n\n// Private package (internal only)\n{\n \"name\": \"@myorg/web-app\",\n \"private\": true\n}\n```\n\n### 10. Document Dependencies Between Packages\n\nCreate a dependency graph diagram in your README:\n\n```mermaid\ngraph TD\n web-app --> ui\n web-app --> utils\n mobile-app --> ui\n mobile-app --> utils\n ui --> design-tokens\n```\n\n---\n\n## Troubleshooting\n\n### Issue: \"Cannot find module '@myorg/ui'\"\n\n**Cause:** Workspace symlinks not created\n\n**Fix:**\n```bash\n# Reinstall dependencies\nrm -rf node_modules packages/*/node_modules\npnpm install\n```\n\n### Issue: TypeScript can't find workspace packages\n\n**Cause:** Missing `paths` configuration\n\n**Fix (tsconfig.json):**\n```json\n{\n \"compilerOptions\": {\n \"baseUrl\": \".\",\n \"paths\": {\n \"@myorg/*\": [\"./packages/*/src\"]\n }\n }\n}\n```\n\n### Issue: Circular dependencies\n\n**Cause:** Package A depends on Package B, and Package B depends on Package A\n\n**Fix:** Refactor to extract shared code into a third package:\n\n```\nBefore:\n ui --> utils\n utils --> ui\n\nAfter:\n ui --> shared\n utils --> shared\n```\n\n### Issue: Slow builds\n\n**Cause:** Rebuilding everything on every change\n\n**Fix:** Use Turborepo or Nx for incremental builds:\n\n```bash\nturbo run build # Only rebuilds changed packages\n```\n\n---\n\n## Resources\n\n- [pnpm Workspaces](https://pnpm.io/workspaces)\n- [npm Workspaces](https://docs.npmjs.com/cli/v10/using-npm/workspaces)\n- [Yarn Workspaces](https://classic.yarnpkg.com/en/docs/workspaces/)\n- [Turborepo Documentation](https://turbo.build/repo/docs)\n- [Nx Documentation](https://nx.dev/)\n- [Changesets](https://github.com/changesets/changesets)\n- [Monorepo.tools](https://monorepo.tools/)\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":14221,"content_sha256":"d0dbf4a97c215e589aa6f466f8be628f6d680032a38b4e11419d898ddb3696cb"},{"filename":"references/security-scanning.md","content":"# Dependency Security Scanning\n\nComprehensive guide to scanning dependencies for vulnerabilities and securing your software supply chain.\n\n## Table of Contents\n\n- [Why Security Scanning Matters](#why-security-scanning-matters)\n- [Native Package Manager Audits](#native-package-manager-audits)\n- [Automated Security Tools](#automated-security-tools)\n- [CI/CD Integration](#cicd-integration)\n- [Supply Chain Security](#supply-chain-security)\n- [Incident Response](#incident-response)\n- [Best Practices](#best-practices)\n\n---\n\n## Why Security Scanning Matters\n\n**Real-world supply chain attacks:**\n- **event-stream (2018):** Compromised npm package with 2M weekly downloads, injected code to steal Bitcoin wallets\n- **ua-parser-js (2021):** Maintainer's account hijacked, malicious version published with cryptominer\n- **Log4Shell (2021):** Critical RCE vulnerability affecting millions of Java applications\n- **colors.js/faker.js (2022):** Maintainer intentionally sabotaged packages in protest\n- **PyTorch (2023):** Malicious dependency uploaded to PyPI targeting Linux systems\n\n**Impact:**\n- Data breaches and credential theft\n- Cryptominers and ransomware\n- Remote code execution (RCE)\n- Supply chain compromise\n- Reputational damage\n\n**Statistics:**\n- 245,000+ malicious packages found on npm (2018-2024)\n- 88% of organizations have at least one vulnerable dependency\n- Average time to patch: 85 days\n\n---\n\n## Native Package Manager Audits\n\n### npm audit\n\n**Basic usage:**\n```bash\n# Run security audit\nnpm audit\n\n# Show JSON output\nnpm audit --json\n\n# Only show production dependencies\nnpm audit --production\n\n# Set minimum severity level\nnpm audit --audit-level=moderate\n```\n\n**Output format:**\n```\nfound 3 vulnerabilities (1 moderate, 2 high)\n run `npm audit fix` to fix 2 of them\n\n 1 moderate severity vulnerability\n in lodash \u003c4.17.21\n Dependency of: express\n Path: express > body-parser > lodash\n More info: https://github.com/advisories/GHSA-xxxx\n```\n\n**Auto-fixing vulnerabilities:**\n```bash\n# Fix vulnerabilities (safe updates only)\nnpm audit fix\n\n# Force fix (may include breaking changes)\nnpm audit fix --force\n\n# Dry run (preview changes without applying)\nnpm audit fix --dry-run\n```\n\n**Audit levels:**\n- `info` - All vulnerabilities\n- `low` - Low, moderate, high, critical\n- `moderate` - Moderate, high, critical (recommended)\n- `high` - High and critical only\n- `critical` - Only critical vulnerabilities\n\n**CI/CD integration:**\n```bash\n# Fail build if vulnerabilities found\nnpm audit --audit-level=moderate || exit 1\n```\n\n### pip-audit (Python)\n\n**Installation:**\n```bash\npip install pip-audit\n```\n\n**Usage:**\n```bash\n# Audit installed packages\npip-audit\n\n# Audit requirements.txt\npip-audit -r requirements.txt\n\n# Output as JSON\npip-audit --format=json\n\n# Fix vulnerabilities\npip-audit --fix\n\n# Set vulnerability database\npip-audit --vulnerability-service=osv\n```\n\n### cargo audit (Rust)\n\n**Installation:**\n```bash\ncargo install cargo-audit\n```\n\n**Usage:**\n```bash\n# Audit dependencies\ncargo audit\n\n# Ignore specific advisories\ncargo audit --ignore RUSTSEC-2020-0071\n\n# JSON output\ncargo audit --json\n\n# Database update\ncargo audit --update\n```\n\n### yarn audit\n\n**Usage:**\n```bash\n# Run audit\nyarn audit\n\n# JSON format\nyarn audit --json\n\n# Set severity level\nyarn audit --level moderate\n```\n\n---\n\n## Automated Security Tools\n\n### Dependabot (GitHub)\n\n**Features:**\n- Automated security updates via pull requests\n- Version updates for dependencies\n- Supports 15+ package ecosystems\n- Native GitHub integration\n\n**Configuration (`.github/dependabot.yml`):**\n```yaml\nversion: 2\nupdates:\n - package-ecosystem: \"npm\"\n directory: \"/\"\n schedule:\n interval: \"weekly\"\n open-pull-requests-limit: 5\n labels:\n - \"dependencies\"\n - \"security\"\n reviewers:\n - \"security-team\"\n # Security updates only\n ignore:\n - dependency-name: \"*\"\n update-types: [\"version-update:semver-major\"]\n```\n\n**Enable Dependabot alerts:**\n1. Go to repository Settings → Security & analysis\n2. Enable \"Dependabot alerts\"\n3. Enable \"Dependabot security updates\"\n\n### Snyk\n\n**Features:**\n- Continuous security monitoring\n- Fix pull requests\n- License compliance\n- Container vulnerability scanning\n- IaC security scanning\n\n**Installation:**\n```bash\nnpm install -g snyk\nsnyk auth\n```\n\n**Usage:**\n```bash\n# Test project for vulnerabilities\nsnyk test\n\n# Monitor project (continuous monitoring)\nsnyk monitor\n\n# Fix vulnerabilities\nsnyk wizard\n\n# Test container images\nsnyk container test node:18-alpine\n\n# Test Kubernetes manifests\nsnyk iac test kubernetes.yaml\n```\n\n**CI/CD integration (GitHub Actions):**\n```yaml\nname: Snyk Security Scan\n\non: [push, pull_request]\n\njobs:\n security:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - uses: snyk/actions/node@master\n env:\n SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}\n with:\n args: --severity-threshold=high\n```\n\n### GitHub Advanced Security\n\n**Features:**\n- Dependency graph\n- Security advisories\n- Code scanning (CodeQL)\n- Secret scanning\n\n**Enable:**\n1. Settings → Security & analysis\n2. Enable \"Dependency graph\"\n3. Enable \"Dependabot alerts\"\n4. Enable \"Code scanning\" (requires GitHub Advanced Security)\n\n**CodeQL configuration (`.github/workflows/codeql.yml`):**\n```yaml\nname: CodeQL\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n\njobs:\n analyze:\n runs-on: ubuntu-latest\n permissions:\n security-events: write\n steps:\n - uses: actions/checkout@v3\n - uses: github/codeql-action/init@v2\n with:\n languages: javascript\n - uses: github/codeql-action/autobuild@v2\n - uses: github/codeql-action/analyze@v2\n```\n\n### Socket.dev\n\n**Features:**\n- Supply chain attack detection\n- Malicious package detection\n- Real-time alerts\n- Risk scoring\n\n**Installation:**\n```bash\nnpx socket-cli@latest\n```\n\n**Usage:**\n```bash\n# Analyze package.json\nnpx socket-cli report create --view\n\n# CI integration\nnpx socket-cli report create --strict\n```\n\n### OWASP Dependency-Check\n\n**Features:**\n- Software composition analysis (SCA)\n- CVE database scanning\n- Supports Java, .NET, Ruby, Python, JavaScript\n\n**Installation:**\n```bash\n# macOS\nbrew install dependency-check\n\n# Manual download\nwget https://github.com/jeremylong/DependencyCheck/releases/download/v8.0.0/dependency-check-8.0.0-release.zip\n```\n\n**Usage:**\n```bash\n# Scan project\ndependency-check --project \"My Project\" --scan ./\n\n# Generate HTML report\ndependency-check --project \"My Project\" --scan ./ --format HTML\n\n# Set suppression file\ndependency-check --project \"My Project\" --scan ./ --suppression suppression.xml\n```\n\n---\n\n## CI/CD Integration\n\n### GitHub Actions\n\n**Basic security workflow:**\n```yaml\nname: Security Audit\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n schedule:\n # Run weekly on Mondays at 9 AM\n - cron: '0 9 * * 1'\n\njobs:\n audit:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n\n - uses: actions/setup-node@v3\n with:\n node-version: '18'\n\n - name: Install dependencies\n run: npm ci\n\n - name: Run npm audit\n run: npm audit --audit-level=moderate\n\n - name: Check for outdated packages\n run: npm outdated || true\n\n - name: Generate SBOM\n run: npx @cyclonedx/cyclonedx-npm --output-file sbom.json\n\n - name: Upload SBOM\n uses: actions/upload-artifact@v3\n with:\n name: sbom\n path: sbom.json\n```\n\n**Advanced workflow with multiple tools:**\n```yaml\nname: Comprehensive Security Scan\n\non: [push, pull_request]\n\njobs:\n security:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - uses: actions/setup-node@v3\n\n - name: Install dependencies\n run: npm ci\n\n # npm audit\n - name: npm audit\n run: npm audit --audit-level=moderate\n continue-on-error: true\n\n # Snyk\n - name: Snyk test\n uses: snyk/actions/node@master\n env:\n SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}\n with:\n args: --severity-threshold=high\n continue-on-error: true\n\n # Socket.dev\n - name: Socket.dev scan\n run: npx socket-cli@latest report create --strict\n continue-on-error: true\n\n # License compliance\n - name: License check\n run: npx license-checker --production --onlyAllow \"MIT;Apache-2.0;BSD-2-Clause;BSD-3-Clause;ISC\"\n\n # Upload results\n - name: Upload security reports\n uses: actions/upload-artifact@v3\n with:\n name: security-reports\n path: |\n npm-audit.json\n snyk-report.json\n```\n\n### GitLab CI\n\n```yaml\nsecurity:\n stage: test\n image: node:18\n script:\n - npm ci\n - npm audit --audit-level=moderate\n allow_failure: false\n```\n\n### Jenkins\n\n```groovy\npipeline {\n agent any\n stages {\n stage('Security Audit') {\n steps {\n sh 'npm ci'\n sh 'npm audit --audit-level=moderate'\n }\n }\n }\n}\n```\n\n---\n\n## Supply Chain Security\n\n### SLSA Framework\n\n**SLSA (Supply-chain Levels for Software Artifacts)** - Security framework for build integrity.\n\n**SLSA Levels:**\n- **Level 1:** Source provenance (basic)\n- **Level 2:** Build service (tamper-proof build)\n- **Level 3:** Hardened build platform\n- **Level 4:** Two-party review (highest security)\n\n**Implementing SLSA Level 1:**\n```yaml\n# GitHub Actions with SLSA provenance\nname: Build with SLSA\n\non: push\n\njobs:\n build:\n permissions:\n id-token: write\n contents: write\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - uses: actions/setup-node@v3\n - run: npm ci\n - run: npm run build\n\n - uses: slsa-framework/[email protected]\n with:\n artifact-path: dist/\n provenance-name: provenance.intoto.jsonl\n```\n\n### SBOM (Software Bill of Materials)\n\n**Generate SBOM:**\n```bash\n# CycloneDX (OWASP standard)\nnpx @cyclonedx/cyclonedx-npm --output-file sbom.json\n\n# SPDX format\nnpm sbom --sbom-format=spdx\n\n# Syft (multi-language)\nsyft packages . -o spdx-json > sbom.json\n```\n\n**SBOM formats:**\n- **CycloneDX:** OWASP standard, JSON/XML\n- **SPDX:** ISO/IEC standard, JSON/RDF/YAML\n- **SWID:** ISO/IEC 19770-2\n\n### npm Provenance\n\n**Enable npm provenance:**\n```bash\n# Publish with provenance\nnpm publish --provenance\n```\n\n**Verify provenance:**\n```bash\nnpm audit signatures\n```\n\n### Package Signing\n\n**Verify package integrity:**\n```bash\n# npm (experimental)\nnpm audit signatures\n\n# Sigstore (Rust, Python, containers)\ncosign verify \u003cimage>\n```\n\n---\n\n## Incident Response\n\n### When a Vulnerability is Discovered\n\n**1. Assess severity:**\n- **Critical:** RCE, arbitrary code execution, data breach\n- **High:** Privilege escalation, authentication bypass\n- **Moderate:** XSS, CSRF, information disclosure\n- **Low:** Denial of service, minor information leaks\n\n**2. Check if vulnerability is exploitable:**\n```bash\n# Is the vulnerable function actually used?\ngrep -r \"vulnerableFunction\" src/\n\n# Is the vulnerable dependency in production?\nnpm ls \u003cvulnerable-package>\n```\n\n**3. Find a fix:**\n```bash\n# Check if patch exists\nnpm audit fix --dry-run\n\n# Check for alternative packages\nnpm info \u003calternative-package>\n```\n\n**4. Apply fix:**\n```bash\n# Option 1: Automated fix\nnpm audit fix\n\n# Option 2: Manual update\nnpm install \u003cpackage>@latest\n\n# Option 3: Use override/resolution\n# package.json\n{\n \"overrides\": {\n \"lodash\": \"4.17.21\"\n }\n}\n```\n\n**5. Verify fix:**\n```bash\nnpm audit\nnpm test\n```\n\n**6. Document:**\n- Update CHANGELOG.md\n- Security advisory (if public package)\n- Internal incident report\n\n### Vulnerability Disclosure Process\n\n**If you discover a vulnerability:**\n\n1. **Do NOT** open a public GitHub issue\n2. Use GitHub Security Advisories\n3. Contact maintainer privately\n4. Allow 90 days for fix before public disclosure\n5. Coordinate disclosure with maintainer\n\n---\n\n## Best Practices\n\n### 1. Run Audits Regularly\n\n```bash\n# Weekly automated scans\nnpm audit --audit-level=moderate\n\n# Before releases\nnpm audit --production\n```\n\n### 2. Enable Automated Tools\n\n- [OK] Dependabot (free for GitHub)\n- [OK] Snyk (free tier available)\n- [OK] GitHub Advanced Security (if available)\n\n### 3. Set Audit Thresholds\n\n```json\n// package.json\n{\n \"scripts\": {\n \"audit\": \"npm audit --audit-level=moderate\",\n \"audit:production\": \"npm audit --production --audit-level=high\"\n }\n}\n```\n\n### 4. Monitor Advisories\n\n- Subscribe to GitHub Security Advisories\n- Monitor CVE databases\n- Follow security mailing lists\n\n### 5. Use Lock Files\n\n```bash\n# Commit lockfiles to ensure reproducibility\ngit add package-lock.json\ngit commit -m \"chore: update dependencies\"\n```\n\n### 6. Minimize Dependencies\n\n```bash\n# Remove unused dependencies\nnpx depcheck\n\n# Check bundle size impact\nnpx bundlephobia \u003cpackage>\n```\n\n### 7. Vet New Dependencies\n\nBefore adding a dependency:\n- Check weekly downloads\n- Review GitHub activity\n- Check security audit history\n- Review open issues\n- Check license compatibility\n\n### 8. Use Private Registry for Internal Packages\n\n```bash\n# .npmrc\n@myorg:registry=https://npm.pkg.github.com/\n//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}\n```\n\n### 9. Implement Least Privilege\n\n```bash\n# Don't run npm install as root\n# Use specific Node.js versions\nnvm use 18\n```\n\n### 10. Generate and Store SBOMs\n\n```bash\n# Generate SBOM\nnpx @cyclonedx/cyclonedx-npm --output-file sbom.json\n\n# Store with release artifacts\ngh release create v1.0.0 dist/* sbom.json\n```\n\n---\n\n## Severity Level Guidelines\n\n| Severity | CVSS Score | Action | Timeline |\n|----------|------------|--------|----------|\n| **Critical** | 9.0-10.0 | Immediate patch | \u003c24 hours |\n| **High** | 7.0-8.9 | Prioritize fix | \u003c1 week |\n| **Moderate** | 4.0-6.9 | Schedule fix | \u003c1 month |\n| **Low** | 0.1-3.9 | Monitor | Next release |\n\n---\n\n## Resources\n\n- [npm audit documentation](https://docs.npmjs.com/cli/v10/commands/npm-audit)\n- [Snyk](https://snyk.io/)\n- [Dependabot](https://github.com/dependabot)\n- [OWASP Dependency-Check](https://owasp.org/www-project-dependency-check/)\n- [SLSA Framework](https://slsa.dev/)\n- [CycloneDX SBOM](https://cyclonedx.org/)\n- [GitHub Security Advisories](https://docs.github.com/en/code-security/security-advisories)\n- [CVE database](https://cve.mitre.org/)\n- [National Vulnerability Database (NVD)](https://nvd.nist.gov/)","content_type":"text/markdown; charset=utf-8","language":"markdown","size":14411,"content_sha256":"3b5760843069a3608acc7ea6248c30749a36c281dd5babf84f0561f7643654b0"},{"filename":"references/semver-guide.md","content":"# Semantic Versioning Deep Dive\n\nComprehensive guide to understanding and using semantic versioning (SemVer) for dependency management.\n\n## Table of Contents\n\n- [SemVer Basics](#semver-basics)\n- [Version Constraints Explained](#version-constraints-explained)\n- [npm/yarn/pnpm Ranges](#npmyarnpnpm-ranges)\n- [Python Version Specifiers](#python-version-specifiers)\n- [Cargo Version Requirements](#cargo-version-requirements)\n- [Pre-release and Build Metadata](#pre-release-and-build-metadata)\n- [Common Pitfalls](#common-pitfalls)\n- [Best Practices](#best-practices)\n\n---\n\n## SemVer Basics\n\nSemantic Versioning uses a three-part version number: `MAJOR.MINOR.PATCH`\n\n**Format:** `X.Y.Z` where X, Y, and Z are non-negative integers\n\n### Version Components\n\n```\n 2.14.7\n │ │ │\n │ │ └─ PATCH: Bug fixes (backward-compatible)\n │ └──── MINOR: New features (backward-compatible)\n └────── MAJOR: Breaking changes (incompatible API changes)\n```\n\n### When to Increment\n\n| Change Type | Example | Version Change |\n|-------------|---------|----------------|\n| **MAJOR** | Remove deprecated API, change function signature | `1.4.2` → `2.0.0` |\n| **MINOR** | Add new optional parameter, new feature | `1.4.2` → `1.5.0` |\n| **PATCH** | Fix bug, security patch | `1.4.2` → `1.4.3` |\n\n### Special Version 0.x.y\n\n**Versions starting with 0 (0.x.y) are considered unstable:**\n\n- `0.x.y` - Initial development, anything may change\n- `0.0.x` - Extremely unstable\n- Breaking changes can happen on **any** update in 0.x.y versions\n- Don't use 0.x.y in production without pinning exact versions\n\n---\n\n## Version Constraints Explained\n\n### Exact Version\n\n```json\n\"lodash\": \"4.17.21\"\n```\n\n- **Installs:** Exactly `4.17.21`\n- **Use when:** Mission-critical dependencies, reproducibility is paramount\n- **Risk:** Miss bug fixes and security patches\n- **Recommendation:** Use sparingly\n\n### Caret Range (^) - Recommended\n\n```json\n\"express\": \"^4.18.2\"\n```\n\n- **Installs:** `>=4.18.2 \u003c5.0.0`\n- **Allows:** Patch and minor updates\n- **Blocks:** Major version changes\n- **Use when:** Default for most dependencies\n- **Example:**\n - `^4.18.2` allows `4.18.3`, `4.19.0`, `4.99.0`\n - `^4.18.2` blocks `5.0.0`\n\n**Special case for 0.x.y versions:**\n```json\n\"package\": \"^0.3.2\"\n```\n- **Installs:** `>=0.3.2 \u003c0.4.0` (only patch updates)\n- Caret is more conservative for pre-1.0 versions\n\n### Tilde Range (~) - Conservative\n\n```json\n\"react\": \"~18.2.0\"\n```\n\n- **Installs:** `>=18.2.0 \u003c18.3.0`\n- **Allows:** Only patch updates\n- **Blocks:** Minor and major updates\n- **Use when:** You want stability but still need security patches\n- **Example:**\n - `~18.2.0` allows `18.2.1`, `18.2.2`, `18.2.99`\n - `~18.2.0` blocks `18.3.0`, `19.0.0`\n\n### Greater Than / Less Than\n\n```json\n\"next\": \">=13.0.0 \u003c14.0.0\"\n```\n\n- Explicit range specification\n- Use for complex version requirements\n- Less common than caret/tilde\n\n### Wildcard (x) - Avoid\n\n```json\n\"axios\": \"1.x\"\n```\n\n- **Installs:** `>=1.0.0 \u003c2.0.0`\n- **Equivalent to:** `^1.0.0`\n- **Recommendation:** Use caret instead for clarity\n\n### Any Version (*) - Never Use\n\n```json\n\"moment\": \"*\"\n```\n\n- **Installs:** Latest version (completely unpredictable)\n- **Risk:** Breaking changes without warning\n- **Recommendation:** **Never use in production**\n\n---\n\n## npm/yarn/pnpm Ranges\n\n### Comprehensive Examples\n\n```json\n{\n \"dependencies\": {\n \"exact-version\": \"1.2.3\", // Exactly 1.2.3\n \"caret-range\": \"^1.2.3\", // >=1.2.3 \u003c2.0.0\n \"tilde-range\": \"~1.2.3\", // >=1.2.3 \u003c1.3.0\n \"greater-than\": \">=1.2.3\", // 1.2.3 or higher\n \"less-than\": \"\u003c2.0.0\", // Below 2.0.0\n \"range\": \">=1.2.3 \u003c2.0.0\", // Between 1.2.3 and 2.0.0\n \"wildcard\": \"1.x\", // 1.0.0 - 1.99.99\n \"wildcard-minor\": \"1.2.x\", // 1.2.0 - 1.2.99\n \"hyphen-range\": \"1.2.3 - 2.3.4\", // >=1.2.3 \u003c=2.3.4\n \"OR-operator\": \"1.x || 2.x\", // 1.x.x or 2.x.x\n \"git-url\": \"git+https://github.com/user/repo.git#commit-hash\",\n \"github-shorthand\": \"user/repo\",\n \"local-path\": \"file:../local-package\"\n }\n}\n```\n\n### Advanced Ranges\n\n```json\n{\n \"dependencies\": {\n \"latest-tag\": \"latest\", // Latest npm tag (avoid)\n \"dist-tag\": \"next\", // Specific distribution tag\n \"pre-release\": \"^1.0.0-beta.1\", // Includes pre-release versions\n \"exclude-pre\": \"^1.0.0\", // Excludes pre-release\n \"complex\": \">=1.2.3 \u003c2.0.0 || >=3.0.0 \u003c4.0.0\"\n }\n}\n```\n\n---\n\n## Python Version Specifiers\n\nPython uses [PEP 440](https://peps.python.org/pep-0440/) for version specifiers.\n\n### Poetry (pyproject.toml)\n\n```toml\n[tool.poetry.dependencies]\n# Caret (default in Poetry)\nrequests = \"^2.28.0\" # >=2.28.0 \u003c3.0.0\n\n# Tilde\nfastapi = \"~0.95.0\" # >=0.95.0 \u003c0.96.0\n\n# Exact version\npydantic = \"==2.0.3\" # Exactly 2.0.3\n\n# Greater than or equal\nnumpy = \">=1.24.0\" # 1.24.0 or higher\n\n# Compatible release (roughly equivalent to caret)\npandas = \"~=1.5.0\" # >=1.5.0 \u003c2.0.0\n\n# Wildcard\ndjango = \"4.*\" # Any 4.x version\n\n# Multiple constraints\nflask = \">=2.0,\u003c3.0\" # Between 2.0 and 3.0\n```\n\n### pip (requirements.txt)\n\n```txt\n# Exact version (most common in requirements.txt)\nDjango==4.2.1\n\n# Greater than or equal\nrequests>=2.28.0\n\n# Compatible release\nnumpy~=1.24.0\n\n# Range\nfastapi>=0.95.0,\u003c1.0.0\n\n# Not equal (exclude specific versions)\nurllib3>=1.26.0,!=1.26.5\n\n# Logical OR (rarely used)\npytest==7.3.1 ; python_version >= \"3.8\"\n```\n\n---\n\n## Cargo Version Requirements\n\nRust's Cargo uses a slightly different syntax.\n\n### Cargo.toml\n\n```toml\n[dependencies]\n# Caret (default in Cargo)\nserde = \"^1.0\" # >=1.0.0 \u003c2.0.0\nserde_json = \"1.0\" # Same as ^1.0 (caret is implicit)\n\n# Tilde\nregex = \"~1.7\" # >=1.7.0 \u003c1.8.0\n\n# Exact version (use =)\ntokio = \"=1.28.0\" # Exactly 1.28.0\n\n# Wildcard\nactix-web = \"4.*\" # Any 4.x version\n\n# Greater/less than\nreqwest = \">=0.11, \u003c0.12\" # Range\n\n# Multiple requirements\nhyper = \">= 0.14, \u003c 0.15\" # Equivalent to ~0.14\n\n# Git dependencies\nrand = { git = \"https://github.com/rust-random/rand.git\", branch = \"main\" }\n```\n\n### Cargo Defaults\n\n**Important:** In Cargo, version `\"1.0\"` is shorthand for `\"^1.0\"` (caret is implicit).\n\n---\n\n## Pre-release and Build Metadata\n\n### Pre-release Versions\n\n```\n1.0.0-alpha \u003c 1.0.0-alpha.1 \u003c 1.0.0-beta \u003c 1.0.0-beta.2 \u003c 1.0.0-rc.1 \u003c 1.0.0\n```\n\n**Common pre-release identifiers:**\n- `alpha` - Early testing\n- `beta` - Feature-complete but unstable\n- `rc` (release candidate) - Ready for release, final testing\n- `next` - Next version preview\n\n**How version constraints handle pre-releases:**\n\n```json\n// npm\n\"package\": \"^1.0.0\" // Does NOT include 1.1.0-beta\n\"package\": \"^1.0.0-beta\" // Includes 1.0.0-beta.1, 1.0.0-rc, 1.0.0\n\n// Explicitly allow pre-releases\n\"package\": \"^1.0.0 || ^1.0.0-beta\"\n```\n\n### Build Metadata\n\nBuild metadata is **ignored** for version precedence:\n\n```\n1.0.0+20130313144700 == 1.0.0+exp.sha.5114f85\n```\n\n- Used for CI build numbers, commit hashes\n- Does not affect version sorting\n- Rarely used in dependency declarations\n\n---\n\n## Common Pitfalls\n\n### Pitfall 1: Using `*` or `latest`\n\n**Bad:**\n```json\n\"react\": \"*\"\n\"next\": \"latest\"\n```\n\n**Why:** Completely unpredictable. Can break production without warning.\n\n**Fix:**\n```json\n\"react\": \"^18.2.0\"\n\"next\": \"^14.0.0\"\n```\n\n### Pitfall 2: Too Many Exact Versions\n\n**Bad:**\n```json\n\"express\": \"4.18.2\",\n\"lodash\": \"4.17.21\",\n\"axios\": \"1.4.0\",\n\"moment\": \"2.29.4\"\n```\n\n**Why:** Misses critical security patches.\n\n**Fix:** Use caret for most dependencies, exact only for mission-critical ones.\n\n```json\n\"express\": \"^4.18.2\",\n\"lodash\": \"^4.17.21\",\n\"axios\": \"^1.4.0\",\n\"moment\": \"^2.29.4\" // Or better: remove and use native Date\n```\n\n### Pitfall 3: Ignoring 0.x.y Instability\n\n**Bad:**\n```json\n\"some-new-lib\": \"^0.5.2\" // Assumes stability\n```\n\n**Why:** 0.x.y versions can have breaking changes on any update.\n\n**Fix:** Pin exact version or use tilde.\n\n```json\n\"some-new-lib\": \"0.5.2\" // Exact\n// or\n\"some-new-lib\": \"~0.5.2\" // Only patch updates\n```\n\n### Pitfall 4: Misunderstanding Caret with 0.x\n\n```json\n\"package\": \"^0.3.2\"\n```\n\n**Expected:** `>=0.3.2 \u003c1.0.0`\n**Actual:** `>=0.3.2 \u003c0.4.0` (conservative for 0.x)\n\n### Pitfall 5: Lockfile Conflicts\n\n**Problem:** Merge conflicts in `package-lock.json`\n\n**Wrong fix:** Manually edit lockfile\n\n**Right fix:**\n```bash\n# Delete lockfile and regenerate\nrm package-lock.json\nnpm install\n\n# Or resolve package.json first, then:\nnpm install\n```\n\n---\n\n## Best Practices\n\n### 1. Default to Caret (`^`)\n\n```json\n\"express\": \"^4.18.2\"\n```\n\n[OK] Gets security patches and new features\n[OK] Avoids breaking changes\n[OK] Recommended by npm, yarn, pnpm\n\n### 2. Use Exact Versions Strategically\n\n**When to use exact versions:**\n- Mission-critical dependencies (payment processing, auth)\n- Known stability issues with a package\n- Deployment to production (optional, if very conservative)\n\n```json\n\"stripe\": \"12.10.0\", // Exact (payment processing)\n\"express\": \"^4.18.2\" // Caret (everything else)\n```\n\n### 3. Pin 0.x.y Versions\n\n```json\n\"experimental-lib\": \"0.5.2\" // Exact for unstable\n```\n\n### 4. Use Lockfiles\n\n**Always commit:**\n- `package-lock.json` (npm)\n- `yarn.lock` (yarn)\n- `pnpm-lock.yaml` (pnpm)\n- `poetry.lock` (poetry)\n- `Cargo.lock` (cargo applications)\n\n### 5. Update Regularly\n\n```bash\n# Check for outdated packages\nnpm outdated\n\n# Update patch versions\nnpm update\n\n# Update minor/major versions interactively\nnpx npm-check-updates -i\n```\n\n### 6. Document Exact Versions\n\nIf you pin an exact version, document why:\n\n```json\n{\n \"dependencies\": {\n \"problematic-lib\": \"2.5.3\"\n // Pinned to 2.5.3 due to memory leak in 2.6.0\n // See: https://github.com/lib/issues/123\n }\n}\n```\n\n### 7. Use Version Constraints Consistently\n\n**Good:**\n```json\n{\n \"dependencies\": {\n \"react\": \"^18.2.0\",\n \"react-dom\": \"^18.2.0\",\n \"next\": \"^14.0.0\"\n }\n}\n```\n\n**Bad (inconsistent):**\n```json\n{\n \"dependencies\": {\n \"react\": \"18.2.0\", // Exact\n \"react-dom\": \"^18.2.0\", // Caret\n \"next\": \"*\" // Wildcard\n }\n}\n```\n\n---\n\n## Quick Reference\n\n### npm/yarn/pnpm\n\n| Syntax | Meaning | Use Case |\n|--------|---------|----------|\n| `1.2.3` | Exactly 1.2.3 | Mission-critical |\n| `^1.2.3` | `>=1.2.3 \u003c2.0.0` | **Default** |\n| `~1.2.3` | `>=1.2.3 \u003c1.3.0` | Conservative |\n| `1.x` | `>=1.0.0 \u003c2.0.0` | Avoid (use caret) |\n| `*` | Latest | **Never use** |\n\n### Python (Poetry)\n\n| Syntax | Meaning | Use Case |\n|--------|---------|----------|\n| `==1.2.3` | Exactly 1.2.3 | Pin version |\n| `^1.2.3` | `>=1.2.3 \u003c2.0.0` | **Default** |\n| `~1.2.3` | `>=1.2.3 \u003c1.3.0` | Conservative |\n| `~=1.2.3` | `>=1.2.3 \u003c2.0.0` | Compatible release |\n| `>=1.2.3` | 1.2.3 or higher | Lower bound |\n\n### Rust (Cargo)\n\n| Syntax | Meaning | Use Case |\n|--------|---------|----------|\n| `=1.2.3` | Exactly 1.2.3 | Pin version |\n| `1.2` | `^1.2` (implicit) | **Default** |\n| `^1.2.3` | `>=1.2.3 \u003c2.0.0` | Explicit caret |\n| `~1.2.3` | `>=1.2.3 \u003c1.3.0` | Conservative |\n\n---\n\n## Testing Version Constraints\n\n### npm semver calculator\n\n```bash\n# Install globally\nnpm install -g semver\n\n# Test if version satisfies constraint\nsemver 1.2.3 -r \"^1.0.0\" # true\nsemver 2.0.0 -r \"^1.0.0\" # false\n\n# Find max satisfying version\nsemver -r \"^1.0.0\" 1.0.0 1.5.0 2.0.0 # 1.5.0\n```\n\n### Online tools\n\n- [npm semver calculator](https://semver.npmjs.com/)\n- [semver.org](https://semver.org/)\n\n---\n\n## Resources\n\n- [Semantic Versioning 2.0.0](https://semver.org/)\n- [npm semver documentation](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#dependencies)\n- [PEP 440 (Python)](https://peps.python.org/pep-0440/)\n- [Cargo version requirements](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html)\n- [node-semver library](https://github.com/npm/node-semver)\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":11972,"content_sha256":"baf96b9c64206131776d9679ed2a117113faf05f277a5d611bfbc3c7c8b33de7"},{"filename":"references/transitive-dependencies.md","content":"# Transitive Dependency Management\n\n**When to Use**: Dealing with dependencies of your dependencies (indirect dependencies).\n\n---\n\n## What Are Transitive Dependencies?\n\n**Definition:** Transitive dependencies are packages required by your direct dependencies, but not explicitly listed in your project's dependency file.\n\n**Example:**\n\n```\nYour Project\n └─ express (direct dependency)\n └─ body-parser (transitive dependency)\n └─ bytes (transitive dependency)\n └─ content-type (transitive dependency)\n └─ http-errors (transitive dependency)\n```\n\nYou only installed `express`, but got 4+ transitive dependencies automatically.\n\n---\n\n## Why Transitive Dependencies Matter\n\n### Security Risks\n\n**Problem:** Vulnerabilities can hide in transitive dependencies\n\n```bash\n# Your package.json\n{\n \"dependencies\": {\n \"safe-package\": \"^1.0.0\"\n }\n}\n\n# But safe-package depends on...\n# [email protected] (has CVE-2023-12345)\n```\n\n**Impact:**\n- You don't control transitive versions directly\n- Security scans may miss deep dependencies\n- Updates to direct deps may introduce vulnerabilities\n\n### Version Conflicts\n\n**Problem:** Multiple packages may depend on different versions of the same transitive dependency\n\n```\nYour Project\n ├─ [email protected]\n │ └─ [email protected]\n └─ [email protected]\n └─ [email protected]\n```\n\n**What happens:**\n- npm/yarn: Installs multiple versions (bloat)\n- pnpm: Strict resolution, may fail\n- Some tools: Use highest version (may break)\n\n### Dependency Bloat\n\n**Problem:** Deep dependency trees increase bundle size and install time\n\n```bash\n$ npm ls\[email protected]\n└─┬ [email protected]\n ├─┬ [email protected]\n ├─┬ [email protected]\n │ ├─┬ [email protected]\n │ ├─┬ [email protected]\n │ └─┬ [email protected]\n ├─┬ [email protected]\n ├─┬ [email protected]\n │ ├─┬ [email protected]\n │ └─┬ [email protected]\n ... (200+ more packages)\n```\n\nA single dependency can pull in hundreds of transitive dependencies.\n\n---\n\n## Viewing Dependency Trees\n\n### npm\n\n```bash\n# View full dependency tree\nnpm ls\n\n# View specific package\nnpm ls lodash\n\n# Limit depth\nnpm ls --depth=1\nnpm ls --depth=2\n\n# Show only production dependencies\nnpm ls --prod\n\n# Output as JSON\nnpm ls --json\n\n# Find duplicate packages\nnpm dedupe\n```\n\n**Example output:**\n\n```bash\n$ npm ls axios\[email protected]\n├─┬ [email protected]\n│ └── [email protected]\n└── [email protected] # Duplicate!\n```\n\n### yarn\n\n```bash\n# Why is this package installed?\nyarn why lodash\n\n# View dependency tree\nyarn list\n\n# Find duplicate packages\nyarn dedupe\n```\n\n**Example output:**\n\n```bash\n$ yarn why lodash\ninfo Has been hoisted to \"lodash\"\ninfo Reasons this module exists\n - \"package-a\" depends on it\n - \"package-b#dep-c\" depends on it\n```\n\n### pnpm\n\n```bash\n# View dependency tree\npnpm list\n\n# Why is this package installed?\npnpm why lodash\n\n# List all versions\npnpm list --depth Infinity\n```\n\n### Python (pip)\n\n```bash\n# Install pipdeptree\npip install pipdeptree\n\n# View tree\npipdeptree\n\n# Show only specific package\npipdeptree -p flask\n\n# Reverse tree (what depends on this?)\npipdeptree -r -p requests\n```\n\n**Example output:**\n\n```bash\n$ pipdeptree -p flask\nFlask==2.3.0\n ├── click [required: >=8.0, installed: 8.1.3]\n ├── itsdangerous [required: >=2.0, installed: 2.1.2]\n ├── Jinja2 [required: >=3.0, installed: 3.1.2]\n │ └── MarkupSafe [required: >=2.0, installed: 2.1.1]\n └── Werkzeug [required: >=2.3.0, installed: 2.3.6]\n```\n\n### Rust (Cargo)\n\n```bash\n# View dependency tree\ncargo tree\n\n# Show specific package\ncargo tree -p serde\n\n# Invert tree (what depends on this?)\ncargo tree -i serde\n```\n\n---\n\n## Resolving Transitive Conflicts\n\n### Method 1: Overrides (npm 8.3+, yarn)\n\n**package.json:**\n\n```json\n{\n \"overrides\": {\n \"lodash\": \"4.17.21\"\n }\n}\n```\n\nThis forces ALL transitive instances of `lodash` to use `4.17.21`, regardless of what direct dependencies specify.\n\n**Use cases:**\n- Security patch needed urgently\n- Version conflict resolution\n- Forcing consistent versions\n\n**Example: Security fix**\n\n```json\n{\n \"dependencies\": {\n \"old-package\": \"1.0.0\" // depends on [email protected]\n },\n \"overrides\": {\n \"vulnerable-dep\": \"1.0.1\" // Patched version\n }\n}\n```\n\n**Nested overrides:**\n\n```json\n{\n \"overrides\": {\n \"package-a\": {\n \"lodash\": \"4.17.21\" // Only override lodash within package-a\n }\n }\n}\n```\n\n### Method 2: Resolutions (yarn, pnpm)\n\n**package.json (yarn):**\n\n```json\n{\n \"resolutions\": {\n \"lodash\": \"4.17.21\"\n }\n}\n```\n\n**package.json (pnpm):**\n\n```json\n{\n \"pnpm\": {\n \"overrides\": {\n \"lodash\": \"4.17.21\"\n }\n }\n}\n```\n\nSame effect as npm overrides, but syntax differs.\n\n### Method 3: Constraints (pip-tools)\n\n**constraints.txt:**\n\n```txt\n# Pin transitive dependency\nurllib3==1.26.18\n\n# Or use range\nrequests>=2.28.0,\u003c3.0.0\n```\n\n**Install with constraints:**\n\n```bash\npip install -c constraints.txt -r requirements.txt\n```\n\n### Method 4: Update Direct Dependency\n\nSometimes the best solution is updating the direct dependency:\n\n```bash\n# Instead of overriding transitive dep\nnpm update package-a\n\n# This may pull in newer transitive deps automatically\n```\n\n---\n\n## Best Practices\n\n### 1. Monitor Transitive Dependencies\n\n**Use audit tools:**\n\n```bash\n# npm\nnpm audit\n\n# Include dev dependencies\nnpm audit --production=false\n\n# yarn\nyarn audit\n\n# pnpm\npnpm audit\n\n# Python\npip-audit\n```\n\n### 2. Use Overrides Sparingly\n\n**Only override when:**\n- [OK] Security vulnerability requires urgent patch\n- [OK] Version conflict blocking development\n- [OK] Proven fix (not speculative)\n\n**Always document why:**\n\n```json\n{\n \"overrides\": {\n \"axios\": \"1.6.0\" // CVE-2023-45857 fix\n }\n}\n```\n\nOr add comment in README:\n\n```markdown\n## Dependency Overrides\n\n- `[email protected]` - Forced upgrade to fix CVE-2023-45857 in transitive dependency\n- `[email protected]` - Resolves conflict between package-a and package-b\n```\n\n### 3. Test After Overriding\n\nOverrides can break things:\n\n```bash\n# After adding override\nnpm install\n\n# Run full test suite\nnpm test\n\n# Check for runtime errors\nnpm start\n```\n\n### 4. Deduplicate Regularly\n\nRemove duplicate versions:\n\n```bash\n# npm\nnpm dedupe\n\n# yarn\nyarn dedupe\n\n# pnpm (automatic)\npnpm install\n```\n\n**Before dedupe:**\n\n```\nnode_modules/\n├── [email protected]\n└── package-a/\n └── node_modules/\n └── [email protected]\n```\n\n**After dedupe:**\n\n```\nnode_modules/\n└── [email protected] # Single version hoisted\n```\n\n### 5. Lock Transitive Versions\n\n**Use lockfiles:**\n\n```bash\n# npm\npackage-lock.json\n\n# yarn\nyarn.lock\n\n# pnpm\npnpm-lock.yaml\n\n# pip\nrequirements.txt (with pip-tools)\n\n# poetry\npoetry.lock\n```\n\nLockfiles ensure transitive deps stay consistent across environments.\n\n---\n\n## Troubleshooting Transitive Issues\n\n### Issue 1: Peer Dependency Conflicts\n\n**Error:**\n\n```bash\nnpm ERR! peer dep missing: react@^18.0.0, required by [email protected]\n```\n\n**Cause:** Peer dependencies are transitive deps that must be installed manually.\n\n**Solution:**\n\n```bash\n# Install the peer dependency\nnpm install react@^18.0.0\n```\n\n### Issue 2: Circular Dependencies\n\n**Error:**\n\n```bash\nnpm WARN circular dependency detected: package-a -> package-b -> package-a\n```\n\n**Cause:** package-a depends on package-b, which depends back on package-a.\n\n**Solution:**\n\n1. Refactor to remove circular dependency (best)\n2. Use `--legacy-peer-deps` flag (workaround)\n\n```bash\nnpm install --legacy-peer-deps\n```\n\n### Issue 3: Conflicting Versions\n\n**Error:**\n\n```bash\nnpm ERR! Cannot resolve dependency tree\nnpm ERR! ERESOLVE unable to resolve dependency tree\n```\n\n**Cause:** Multiple packages require incompatible versions of a transitive dependency.\n\n**Solution 1: Update direct dependencies**\n\n```bash\nnpm update\n```\n\n**Solution 2: Use overrides**\n\n```json\n{\n \"overrides\": {\n \"conflicting-package\": \"1.2.3\"\n }\n}\n```\n\n**Solution 3: Force resolution**\n\n```bash\nnpm install --force\n# or\nnpm install --legacy-peer-deps\n```\n\n### Issue 4: Security Vulnerability in Transitive Dep\n\n**Error:**\n\n```bash\nnpm audit\n┌───────────────┬──────────────────────────────────────────────────────────────┐\n│ moderate │ Regular Expression Denial of Service in lodash │\n├───────────────┼──────────────────────────────────────────────────────────────┤\n│ Package │ lodash │\n├───────────────┼──────────────────────────────────────────────────────────────┤\n│ Patched in │ >=4.17.21 │\n└───────────────┴──────────────────────────────────────────────────────────────┘\n```\n\n**Solution 1: Auto-fix**\n\n```bash\nnpm audit fix\n```\n\n**Solution 2: Force fix (may break)**\n\n```bash\nnpm audit fix --force\n```\n\n**Solution 3: Manual override**\n\n```json\n{\n \"overrides\": {\n \"lodash\": \"4.17.21\"\n }\n}\n```\n\n---\n\n## Real-World Examples\n\n### Example 1: Security Patch\n\n**Scenario:** Your app uses `[email protected]`, which depends on `[email protected]` (vulnerable).\n\n**Solution:**\n\n```json\n{\n \"dependencies\": {\n \"express\": \"^4.17.1\"\n },\n \"overrides\": {\n \"qs\": \"6.11.0\" // Patched version\n }\n}\n```\n\n**Verify:**\n\n```bash\nnpm ls qs\n# Should show [email protected] everywhere\n```\n\n### Example 2: Version Conflict\n\n**Scenario:** `package-a` needs `[email protected]`, `package-b` needs `[email protected]`.\n\n**Solution 1: Update direct deps (preferred)**\n\n```bash\nnpm update package-a package-b\n# Hope newer versions are compatible\n```\n\n**Solution 2: Override to latest (risky)**\n\n```json\n{\n \"overrides\": {\n \"axios\": \"1.6.0\"\n }\n}\n```\n\n**Test thoroughly:**\n\n```bash\nnpm test\nnpm run test:e2e\n```\n\n### Example 3: Duplicate Dependencies (Bundle Bloat)\n\n**Scenario:** Multiple packages depend on different `lodash` versions.\n\n**Check:**\n\n```bash\nnpm ls lodash\[email protected]\n├─┬ [email protected]\n│ └── [email protected]\n├─┬ [email protected]\n│ └── [email protected]\n└── [email protected]\n```\n\n**Solution:**\n\n```bash\n# Deduplicate\nnpm dedupe\n\n# Or override\n{\n \"overrides\": {\n \"lodash\": \"4.17.21\"\n }\n}\n```\n\n---\n\n## Checklist: Managing Transitive Dependencies\n\n**Monitoring:**\n- [ ] Run `npm audit` weekly\n- [ ] Review `npm ls` output periodically\n- [ ] Set up Dependabot/Snyk for alerts\n- [ ] Check bundle size impact (Bundlephobia)\n\n**Resolution:**\n- [ ] Document why overrides are used\n- [ ] Test thoroughly after overriding\n- [ ] Prefer updating direct deps over overrides\n- [ ] Use overrides only when necessary\n- [ ] Keep overrides minimal (1-3 max)\n\n**Maintenance:**\n- [ ] Deduplicate dependencies monthly\n- [ ] Remove unused overrides\n- [ ] Update direct deps to resolve transitive issues\n- [ ] Review transitive deps when adding new packages\n\n---\n\n## Summary\n\n**Key Principles:**\n\n1. **Understand your tree** - Use `npm ls`, `yarn why`, `pipdeptree`\n2. **Monitor for vulnerabilities** - `npm audit` regularly\n3. **Use overrides sparingly** - Only when necessary, document why\n4. **Test after changes** - Overrides can break things\n5. **Prefer updating direct deps** - More sustainable than overrides\n\n**The Decision Tree:**\n\n```\nTransitive dependency issue?\n ├─ Security vulnerability?\n │ ├─ Direct dep update available? → Update direct dep\n │ └─ No update? → Override with patched version\n │\n ├─ Version conflict?\n │ ├─ Can update direct deps? → Update (preferred)\n │ └─ No update? → Override (test thoroughly)\n │\n └─ Duplicate dependencies?\n └─ Run `npm dedupe` or override to single version\n```\n\n**Remember:** Transitive dependencies are outside your direct control, but you're still responsible for managing them.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":12459,"content_sha256":"75117c516f956ac5ca38363997e9c817a250c080f35667c89d377712cfc09bef"},{"filename":"references/update-strategies.md","content":"# Dependency Update Strategies\n\n**When to Use**: Keeping dependencies up to date safely while minimizing breaking changes and security risks.\n\n---\n\n## Why Update Dependencies?\n\n**Benefits:**\n- Security patches for known vulnerabilities\n- Bug fixes and stability improvements\n- Performance improvements\n- New features and capabilities\n- Compatibility with newer ecosystems\n\n**Risks if you DON'T update:**\n- Accumulating technical debt\n- Security vulnerabilities exploited\n- Compatibility issues with new tools\n- Harder to update later (breaking changes pile up)\n- Loss of community support\n\n---\n\n## Update Strategies\n\n### 1. Continuous Updates (Recommended for Libraries)\n\n**What:** Update dependencies weekly or bi-weekly\n\n**Best for:**\n- Open source libraries\n- npm packages\n- Small teams with fast iteration\n\n**Pros:**\n- [OK] Small, manageable changes\n- [OK] Catch breaking changes early\n- [OK] Stay close to ecosystem\n- [OK] Easier to debug issues\n\n**Cons:**\n- [FAIL] More frequent changes\n- [FAIL] Requires good test coverage\n- [FAIL] Can distract from feature work\n\n**Setup:**\n\n```yaml\n# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: \"npm\"\n directory: \"/\"\n schedule:\n interval: \"weekly\"\n day: \"monday\"\n time: \"09:00\"\n open-pull-requests-limit: 10\n reviewers:\n - \"dev-team\"\n```\n\n### 2. Scheduled Updates (Recommended for Applications)\n\n**What:** Update monthly or quarterly in dedicated sprints\n\n**Best for:**\n- Production applications\n- Enterprise software\n- Large teams with release cycles\n\n**Pros:**\n- [OK] Predictable change windows\n- [OK] Batch updates together\n- [OK] Thorough testing before deployment\n- [OK] Coordinated with releases\n\n**Cons:**\n- [FAIL] Larger change sets\n- [FAIL] More breaking changes at once\n- [FAIL] Harder to isolate issues\n\n**Setup:**\n\n```yaml\n# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: \"npm\"\n directory: \"/\"\n schedule:\n interval: \"monthly\"\n day: \"monday\"\n labels:\n - \"dependencies\"\n - \"monthly-update\"\n```\n\n**Update workflow:**\n\n1. **Week 1**: Review available updates, plan batch\n2. **Week 2**: Update dev dependencies, test\n3. **Week 3**: Update production dependencies, test\n4. **Week 4**: Deploy to staging, verify, deploy to prod\n\n### 3. Security-Only Updates (Conservative)\n\n**What:** Only update for security patches, skip feature updates\n\n**Best for:**\n- Legacy systems\n- Risk-averse organizations\n- Apps with limited test coverage\n\n**Pros:**\n- [OK] Minimal breaking changes\n- [OK] Focuses on critical fixes\n- [OK] Less testing overhead\n\n**Cons:**\n- [FAIL] Accumulates technical debt\n- [FAIL] May miss important bug fixes\n- [FAIL] Harder to update later\n\n**Setup:**\n\n```yaml\n# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: \"npm\"\n directory: \"/\"\n schedule:\n interval: \"weekly\"\n open-pull-requests-limit: 5\n labels:\n - \"security\"\n - \"priority-high\"\n # Only open PRs for security updates\n assignees:\n - \"security-team\"\n```\n\n---\n\n## Safe Update Workflow\n\n### Step-by-Step Process\n\n**1. Check for outdated dependencies:**\n\n```bash\n# Node.js\nnpm outdated\nnpm outdated --long # Shows homepage, description\n\n# Python\npoetry show --outdated\npip list --outdated\n\n# Rust\ncargo outdated\n\n# Go\ngo list -u -m all\n```\n\n**Example output:**\n\n```bash\n$ npm outdated\nPackage Current Wanted Latest Location\naxios 0.27.2 0.27.2 1.6.0 node_modules/axios\ntypescript 4.9.5 4.9.5 5.3.2 node_modules/typescript\n```\n\n**2. Categorize updates by risk:**\n\n| Update Type | Risk | Action |\n|-------------|------|--------|\n| Patch (1.0.0 → 1.0.1) | [GREEN] Low | Update immediately |\n| Minor (1.0.0 → 1.1.0) | [YELLOW] Medium | Test thoroughly |\n| Major (1.0.0 → 2.0.0) | [RED] High | Read CHANGELOG, plan migration |\n\n**3. Update patch versions (safest):**\n\n```bash\n# Update to latest patch versions within constraints\nnpm update\n\n# This respects your package.json constraints\n# E.g., ^1.2.3 → updates to 1.2.x, not 1.3.0 or 2.0.0\n```\n\n**4. Update minor/major versions (carefully):**\n\n```bash\n# Update specific package to latest\nnpm install axios@latest\n\n# Update to specific version\nnpm install [email protected]\n\n# Update all to latest (DANGEROUS - use with caution)\nnpm install -g npm-check-updates\nncu -u\nnpm install\n```\n\n**5. Run tests:**\n\n```bash\n# Run full test suite\nnpm test\n\n# Run E2E tests\nnpm run test:e2e\n\n# Check for type errors (TypeScript)\nnpm run type-check\n\n# Run linter\nnpm run lint\n```\n\n**6. Check for breaking changes:**\n\n**Read changelogs:**\n\n```bash\n# View package changelog\nnpm info \u003cpackage> homepage\n# Click through to GitHub releases\n\n# Search for breaking changes\nnpm info axios | grep -i \"breaking\"\n```\n\n**Common breaking change indicators:**\n\n- Major version bump (1.x → 2.x)\n- Removed APIs\n- Changed function signatures\n- New required parameters\n- Dropped Node.js version support\n\n**7. Test in staging:**\n\n```bash\n# Deploy to staging environment\nnpm run deploy:staging\n\n# Run smoke tests\nnpm run test:smoke\n\n# Manual QA on critical flows\n```\n\n**8. Commit with clear message:**\n\n```bash\n# Stage changes\ngit add package.json package-lock.json\n\n# Descriptive commit message\ngit commit -m \"chore(deps): update axios 0.27.2 → 1.6.0\n\n- Fixes CVE-2023-45857\n- Adds support for new timeout options\n- BREAKING: Removed deprecated getUri method (not used in codebase)\n\nTested:\n- All unit tests passing\n- E2E tests verified\n- Staging deployment successful\"\n```\n\n**9. Monitor production:**\n\nAfter deploying updates:\n\n- Watch error tracking (Sentry, Rollbar)\n- Monitor performance metrics\n- Check logs for new errors\n- Have rollback plan ready\n\n---\n\n## Automated Update Tools\n\n### Dependabot (GitHub Native)\n\n**Pros:**\n- [OK] Free for GitHub repos\n- [OK] Auto-creates PRs\n- [OK] Security alerts integration\n- [OK] Easy configuration\n\n**Cons:**\n- [FAIL] GitHub only\n- [FAIL] Less configurable than Renovate\n- [FAIL] Can create many PRs\n\n**Configuration:**\n\n```yaml\n# .github/dependabot.yml\nversion: 2\nupdates:\n - package-ecosystem: \"npm\"\n directory: \"/\"\n schedule:\n interval: \"weekly\"\n day: \"monday\"\n time: \"09:00\"\n open-pull-requests-limit: 5\n reviewers:\n - \"dev-team\"\n assignees:\n - \"lead-developer\"\n labels:\n - \"dependencies\"\n - \"auto-update\"\n commit-message:\n prefix: \"chore(deps)\"\n include: \"scope\"\n # Grouping related updates\n groups:\n dev-dependencies:\n patterns:\n - \"@types/*\"\n - \"eslint*\"\n - \"prettier\"\n```\n\n### Renovate (Multi-Platform)\n\n**Pros:**\n- [OK] More configurable\n- [OK] Supports all package managers\n- [OK] Works with GitHub, GitLab, Bitbucket\n- [OK] Automerge capabilities\n- [OK] Smart grouping\n\n**Cons:**\n- [FAIL] More complex setup\n- [FAIL] Requires separate service\n\n**Configuration:**\n\n```json\n{\n \"$schema\": \"https://docs.renovatebot.com/renovate-schema.json\",\n \"extends\": [\"config:base\"],\n \"schedule\": [\"after 9am on monday\"],\n \"packageRules\": [\n {\n \"matchUpdateTypes\": [\"patch\"],\n \"automerge\": true,\n \"automergeType\": \"branch\"\n },\n {\n \"matchUpdateTypes\": [\"minor\"],\n \"groupName\": \"minor updates\",\n \"automerge\": false\n },\n {\n \"matchUpdateTypes\": [\"major\"],\n \"enabled\": false\n }\n ],\n \"vulnerabilityAlerts\": {\n \"enabled\": true,\n \"labels\": [\"security\"]\n }\n}\n```\n\n### npm-check-updates (Manual)\n\n**Pros:**\n- [OK] Full control\n- [OK] Interactive mode\n- [OK] Works offline\n\n**Cons:**\n- [FAIL] Manual process\n- [FAIL] No automation\n\n**Usage:**\n\n```bash\n# Install globally\nnpm install -g npm-check-updates\n\n# Check for updates\nncu\n\n# Interactive update selection\nncu -i\n\n# Update package.json (without installing)\nncu -u\n\n# Update and install\nncu -u && npm install\n```\n\n---\n\n## Update Strategies by Project Type\n\n### Open Source Library\n\n**Strategy:** Continuous updates\n\n```yaml\n# Aggressive update schedule\nschedule:\n interval: \"weekly\"\nautomerge: true for patches\n```\n\n**Why:** Stay close to ecosystem, contributors expect modern dependencies\n\n### Production SaaS Application\n\n**Strategy:** Scheduled updates (monthly)\n\n```yaml\n# Conservative schedule\nschedule:\n interval: \"monthly\"\nautomerge: false\n```\n\n**Why:** Stability critical, thorough testing required\n\n### Enterprise Application\n\n**Strategy:** Security-only + quarterly reviews\n\n```yaml\n# Security-focused\nschedule:\n interval: \"weekly\"\nvulnerabilityAlerts: true\nopen-pull-requests-limit: 3\n```\n\n**Why:** Risk-averse, extensive testing required\n\n### Early-Stage Startup\n\n**Strategy:** Continuous updates\n\n```yaml\n# Fast-paced updates\nschedule:\n interval: \"daily\"\nautomerge: true for patches and minors\n```\n\n**Why:** Move fast, iterate quickly, smaller codebase\n\n---\n\n## Handling Breaking Changes\n\n### Before Updating\n\n**1. Read the CHANGELOG:**\n\n```bash\n# Find changelog\nnpm info \u003cpackage> homepage\n# Look for CHANGELOG.md, RELEASES.md, or GitHub releases\n```\n\n**2. Search for migration guides:**\n\n```bash\n# Google: \"axios v1 migration guide\"\n# Check package docs: /docs/migration\n# Look for \"UPGRADING.md\" or \"MIGRATION.md\"\n```\n\n**3. Check for codemods:**\n\nSome libraries provide automated migration tools:\n\n```bash\n# Example: React 19 codemod\nnpx react-codemod update-react-imports\n```\n\n### After Updating\n\n**1. Fix TypeScript errors:**\n\n```bash\nnpm run type-check\n# Fix type errors in your code\n```\n\n**2. Update deprecated API usage:**\n\n```bash\n# Find deprecated warnings\nnpm run build 2>&1 | grep -i \"deprecated\"\n\n# Replace old APIs with new ones\n```\n\n**3. Run full test suite:**\n\n```bash\nnpm test\nnpm run test:e2e\nnpm run test:integration\n```\n\n**4. Update documentation:**\n\n```markdown\n# Update README.md, CHANGELOG.md\n## Dependencies Updated\n- axios: 0.27.2 → 1.6.0 (BREAKING: removed getUri method)\n```\n\n---\n\n## Rollback Plan\n\nAlways have a rollback strategy:\n\n**1. Git rollback:**\n\n```bash\n# Revert commit\ngit revert HEAD\n\n# Or reset to previous commit\ngit reset --hard HEAD~1\n\n# Push rollback\ngit push --force-with-lease\n```\n\n**2. npm rollback:**\n\n```bash\n# Reinstall previous version\nnpm install [email protected]\n\n# Commit lockfile change\ngit add package-lock.json\ngit commit -m \"chore(deps): rollback axios to 0.27.2\"\n```\n\n**3. Docker rollback:**\n\n```bash\n# Deploy previous image tag\nkubectl set image deployment/app app=myapp:v1.2.3\n\n# Or rollback in Kubernetes\nkubectl rollout undo deployment/app\n```\n\n---\n\n## Best Practices\n\n### DO:\n\n- [OK] **Update frequently** - Small changes easier to manage\n- [OK] **Read changelogs** - Understand what changed\n- [OK] **Test thoroughly** - Especially E2E tests\n- [OK] **Update in batches** - Group related dependencies\n- [OK] **Monitor production** - Watch for errors after deploy\n- [OK] **Document breaking changes** - Help future you\n- [OK] **Use semantic versioning** - Understand what updates mean\n- [OK] **Enable automated alerts** - Know when security issues arise\n\n### DON'T:\n\n- [FAIL] **Update all at once** - Risky, hard to debug\n- [FAIL] **Skip reading changelogs** - May miss breaking changes\n- [FAIL] **Blindly automerge** - At least for major updates\n- [FAIL] **Ignore test failures** - Tests exist for a reason\n- [FAIL] **Update without rollback plan** - Always have escape hatch\n- [FAIL] **Use wildcards (`*`)** - Unpredictable updates\n- [FAIL] **Skip staging deployment** - Test in production-like env first\n\n---\n\n## Checklist: Before Updating Dependencies\n\nUse this checklist for EVERY dependency update:\n\n**Preparation:**\n- [ ] Check available updates (`npm outdated`)\n- [ ] Categorize by risk (patch/minor/major)\n- [ ] Read changelogs for major/minor updates\n- [ ] Check for migration guides\n- [ ] Review test coverage (>80%)\n\n**Execution:**\n- [ ] Update lockfile (`npm update` or `npm install \u003cpkg>@latest`)\n- [ ] Run full test suite\n- [ ] Check for TypeScript errors\n- [ ] Run linter\n- [ ] Build project successfully\n\n**Testing:**\n- [ ] Deploy to staging\n- [ ] Run smoke tests\n- [ ] Manual QA on critical flows\n- [ ] Check performance metrics\n- [ ] Review error logs\n\n**Deployment:**\n- [ ] Commit with descriptive message\n- [ ] Create PR with changelog summary\n- [ ] Get code review\n- [ ] Deploy to production\n- [ ] Monitor error tracking\n- [ ] Have rollback plan ready\n\n---\n\n## Summary\n\n**The Update Workflow:**\n\n```\nCheck updates → Categorize risk → Read changelogs → Update → Test → Stage → Deploy → Monitor\n```\n\n**Golden Rules:**\n\n1. **Update frequently** - Small changes are manageable\n2. **Test thoroughly** - Trust but verify\n3. **Read changelogs** - Know what changed\n4. **Have rollback plan** - Things go wrong\n5. **Monitor production** - Catch issues early\n\n**Remember:** Updates are essential for security and stability, but should be done deliberately, not automatically.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":12769,"content_sha256":"1018c1f02508481fb97073600d9f0aff12de18dd6ab8fd1abef0ef8a30181872"},{"filename":"references/version-conflict-resolution.md","content":"# Version Conflict Resolution\n\n> Operational reference for diagnosing and resolving dependency version conflicts across package managers. Covers diamond dependencies, peer mismatches, resolution algorithms, forced overrides, and prevention patterns.\n\n**Freshness anchor:** January 2026 — aligned with npm 10.x, pnpm 9.x, Yarn 4.x (Berry), pip 24.x, Cargo 1.84, and Go 1.23 module system.\n\n---\n\n## Conflict Types Quick Reference\n\n| Conflict Type | Description | Severity | Example |\n|---|---|---|---|\n| Diamond dependency | A depends on [email protected]; B depends on [email protected] | High | `react-dom` needs `react@18`, plugin needs `react@17` |\n| Peer dependency mismatch | Package declares peer dep not met by consumer | Medium | `eslint-plugin-react` requires `eslint@^8`, project has `eslint@9` |\n| Version range incompatibility | Overlapping ranges have no intersection | High | `^1.2.0` vs `~1.1.5` with no shared version |\n| Duplicate packages | Same package at different versions in tree | Low-Medium | Two copies of `lodash` bundled |\n| Transitive conflict | Indirect deps create version collision | High | Sub-dependency of sub-dependency has conflict |\n| Platform/engine mismatch | Package requires different Node/Python/OS | Medium | `engines: { node: \">=20\" }` with Node 18 |\n\n---\n\n## Diagnostic Commands\n\n### npm\n\n```bash\n# View full dependency tree\nnpm ls\n\n# Find why a specific package is installed\nnpm explain \u003cpackage>\n# Alias: npm why \u003cpackage>\n\n# List duplicate packages\nnpm ls --all | grep \"deduped\"\n\n# Check for peer dependency issues\nnpm ls 2>&1 | grep \"ERESOLVE\\|peer dep\\|invalid\"\n\n# View resolved versions\nnpm ls \u003cpackage> --all\n\n# Audit for conflicts during install\nnpm install --dry-run 2>&1\n```\n\n### pnpm\n\n```bash\n# View dependency tree\npnpm ls --depth Infinity\n\n# Why is a package installed\npnpm why \u003cpackage>\n\n# List all versions of a package in the project\npnpm ls \u003cpackage> --depth Infinity\n\n# Check for peer dependency issues\npnpm install --fix-lockfile 2>&1\n```\n\n### Yarn (v4 Berry)\n\n```bash\n# View dependency tree\nyarn info --all --dependents\n\n# Why is a package installed\nyarn why \u003cpackage>\n\n# List duplicates\nyarn dedupe --check\n\n# Explain resolution\nyarn explain peer-requirements\n```\n\n### pip\n\n```bash\n# Check for conflicts\npip check\n\n# Show dependency tree (requires pipdeptree)\npipdeptree --warn fail\n\n# Show reverse dependencies\npipdeptree --reverse --packages \u003cpackage>\n\n# Verbose install to see resolution\npip install --dry-run -v \u003cpackage>\n```\n\n### Cargo (Rust)\n\n```bash\n# View dependency tree\ncargo tree\n\n# Find duplicates\ncargo tree --duplicates\n\n# Why is a package included\ncargo tree --invert \u003cpackage>\n\n# View feature flags\ncargo tree --edges features\n```\n\n### Go Modules\n\n```bash\n# View module graph\ngo mod graph\n\n# Why is a module required\ngo mod why \u003cmodule>\n\n# Tidy unused dependencies\ngo mod tidy\n\n# View effective versions\ngo list -m all\n```\n\n---\n\n## Resolution Algorithm Differences\n\n| Manager | Strategy | Hoisting | Lockfile | Peer Dep Handling |\n|---|---|---|---|---|\n| npm | Nested with hoisting | Yes (flat by default) | `package-lock.json` | Warning, auto-install in v7+ |\n| pnpm | Content-addressable store + symlinks | No (strict by default) | `pnpm-lock.yaml` | Strict by default, error on mismatch |\n| Yarn Berry | Plug'n'Play (no `node_modules`) or node_modules | Configurable | `yarn.lock` | Configurable strictness |\n| pip | Latest compatible version, backtracking | N/A (flat install) | `requirements.txt` / `poetry.lock` | N/A |\n| Cargo | SemVer-compatible unification | N/A | `Cargo.lock` | N/A (feature unification) |\n| Go | Minimum version selection (MVS) | N/A | `go.sum` | N/A |\n\n### Decision Tree: Choosing Resolution Strategy\n\n```\nWhat package manager are you using?\n├── npm\n│ └── Conflict on install?\n│ ├── Peer dep warning → Check if compatible, use --legacy-peer-deps as last resort\n│ └── ERESOLVE error → Use overrides in package.json\n├── pnpm\n│ └── Strict mode failing?\n│ ├── Peer dep → Add to peerDependencyRules in .npmrc\n│ └── Version conflict → Use pnpm.overrides\n├── Yarn Berry\n│ └── Use resolutions in package.json\n├── pip\n│ └── Use pip-compile with constraints file\n├── Cargo\n│ └── Use [patch] section in Cargo.toml\n└── Go\n └── Use replace directive in go.mod\n```\n\n---\n\n## Forced Resolution Strategies\n\n### npm overrides\n\n```json\n{\n \"overrides\": {\n \"lodash\": \"4.17.21\",\n \"react\": \"$react\",\n \"some-package\": {\n \"vulnerable-dep\": \"2.0.1\"\n }\n }\n}\n```\n\n- `\"$react\"` references the version declared in top-level `dependencies`\n- Nested overrides target specific dependency paths\n- Use sparingly — overrides bypass semver safety\n\n### pnpm overrides\n\n```json\n{\n \"pnpm\": {\n \"overrides\": {\n \"lodash\": \"4.17.21\",\n \"foo>bar\": \"2.0.0\"\n },\n \"peerDependencyRules\": {\n \"ignoreMissing\": [\"@babel/*\"],\n \"allowedVersions\": {\n \"react\": \"18\"\n }\n }\n }\n}\n```\n\n### Yarn resolutions\n\n```json\n{\n \"resolutions\": {\n \"lodash\": \"4.17.21\",\n \"package-a/lodash\": \"4.17.21\",\n \"**/@types/node\": \"22.0.0\"\n }\n}\n```\n\n### pip constraints\n\n```bash\n# constraints.txt\ncryptography==43.0.0\nrequests>=2.31.0,\u003c3.0.0\n```\n\n```bash\npip install -c constraints.txt -r requirements.txt\n```\n\n### Cargo patch\n\n```toml\n# Cargo.toml\n[patch.crates-io]\n# Use a fixed fork\nsome-crate = { git = \"https://github.com/user/some-crate\", branch = \"fix\" }\n# Use local path during development\nsome-crate = { path = \"../some-crate\" }\n```\n\n### Go replace\n\n```go\n// go.mod\nreplace (\n example.com/broken/module v1.0.0 => example.com/fixed/module v1.1.0\n example.com/local/module => ../local-module\n)\n```\n\n---\n\n## Diamond Dependency Resolution\n\n### Diagnosis Workflow\n\n```\nTwo or more packages require different versions of the same dependency\n│\n├── Step 1: Identify the conflicting versions\n│ └── npm: `npm explain \u003cpackage>`\n│ └── pnpm: `pnpm why \u003cpackage>`\n│\n├── Step 2: Check if ranges overlap\n│ ├── YES (ranges overlap) → Deduplicate\n│ │ └── npm: `npm dedupe`\n│ │ └── Yarn: `yarn dedupe`\n│ └── NO (ranges incompatible) → Continue\n│\n├── Step 3: Can either dependent package be updated?\n│ ├── YES → Update to version with compatible range\n│ └── NO → Continue\n│\n├── Step 4: Is the conflicting package side-effect-free?\n│ ├── YES → Allow duplicate versions (npm does this by default)\n│ └── NO (e.g., React, singleton libraries) → Continue\n│\n└── Step 5: Force resolution\n ├── Use overrides/resolutions to pin single version\n ├── Test thoroughly — forced version may break dependents\n └── Document override with reason and review date\n```\n\n### Singleton Libraries (Cannot Duplicate)\n\n| Library | Why singleton | Symptom of duplication |\n|---|---|---|\n| React | Hooks require single instance | \"Invalid hook call\" error |\n| Angular | DI container must be single | \"Multiple platforms\" error |\n| Webpack | Plugin system assumes single | Build errors, duplicate modules |\n| styled-components | Theme context must be single | Styles not applying |\n\n---\n\n## Conflict Prevention Patterns\n\n### Proactive Measures\n\n- [ ] Pin exact versions in production applications (`\"lodash\": \"4.17.21\"`)\n- [ ] Use ranges in libraries (`\"lodash\": \"^4.17.0\"`)\n- [ ] Run `npm ls` / `pnpm why` in CI to detect new duplicates\n- [ ] Renovate/Dependabot configured with grouping for related packages\n- [ ] Lockfile committed and reviewed in PRs\n- [ ] `engines` field set in `package.json` to prevent Node.js mismatches\n- [ ] `.npmrc` configured with `strict-peer-dependencies=true` (pnpm)\n- [ ] Regular deduplication runs (`npm dedupe`, `yarn dedupe`)\n\n### Lockfile Hygiene\n\n| Action | When | Command |\n|---|---|---|\n| Regenerate lockfile | After major upgrades | Delete lockfile, run install |\n| Deduplicate | After adding new deps | `npm dedupe` / `yarn dedupe` |\n| Audit lockfile diff | Every PR | Review lockfile changes in code review |\n| Verify integrity | CI pipeline | `npm ci` (fails if lockfile out of sync) |\n\n### Monorepo-Specific Strategies\n\n| Tool | Strategy | Config |\n|---|---|---|\n| npm workspaces | Hoisted shared deps | `workspaces` in root `package.json` |\n| pnpm workspaces | Strict isolation with catalog | `pnpm-workspace.yaml` + `catalogs` |\n| Yarn workspaces | PnP with shared deps | `workspaces` in root `package.json` |\n| Nx / Turborepo | Single version policy | Root `package.json` manages all versions |\n\n### pnpm Catalogs (Monorepo Version Alignment)\n\n```yaml\n# pnpm-workspace.yaml\npackages:\n - \"packages/*\"\n\ncatalogs:\n default:\n react: ^18.3.0\n react-dom: ^18.3.0\n typescript: ^5.6.0\n```\n\n```json\n// packages/app/package.json\n{\n \"dependencies\": {\n \"react\": \"catalog:default\"\n }\n}\n```\n\n---\n\n## Debugging Workflow: Step-by-Step\n\n### \"It works locally but not in CI\"\n\n```\n1. Compare lockfile: is CI using the same lockfile as local?\n └── CI must use `npm ci` (not `npm install`)\n\n2. Compare Node.js/runtime version\n └── Pin in `.nvmrc`, `.node-version`, or `engines`\n\n3. Compare registry: is CI using a private registry?\n └── Check `.npmrc` for registry overrides\n\n4. Clean local state and reproduce\n └── rm -rf node_modules && npm ci\n```\n\n### \"Package X breaks after updating Package Y\"\n\n```\n1. Check if X and Y share a transitive dependency\n └── npm explain \u003cshared-dep>\n\n2. Compare resolved versions before and after\n └── git diff package-lock.json | grep \u003cshared-dep>\n\n3. Check if shared dep had a breaking change\n └── Review changelog of shared dep\n\n4. Resolution:\n ├── Pin shared dep to previous working version via overrides\n ├── OR update X to version compatible with new shared dep\n └── OR open issue upstream\n```\n\n---\n\n## Anti-Patterns\n\n| Anti-Pattern | Problem | Fix |\n|---|---|---|\n| `--legacy-peer-deps` as default | Hides real conflicts, causes runtime errors | Fix peer deps properly, use as last resort |\n| `--force` on every install | Bypasses all safety checks | Investigate and resolve the actual conflict |\n| Not committing lockfiles | Non-reproducible builds | Always commit lockfiles for applications |\n| Overrides without documentation | Future maintainers don't know why | Add comment with reason and review date |\n| Ignoring duplicate warnings | Larger bundles, potential runtime bugs | Run dedupe, investigate singletons |\n| Manual lockfile editing | Corruption, desync | Use CLI commands, never hand-edit lockfiles |\n| Pinning everything in libraries | Prevents consumers from deduplicating | Use ranges in libraries, pin in applications |\n| Updating all deps at once | Hard to isolate breakage | Update in small batches, test between each |\n| No `engines` field | Works on dev's Node 22, breaks on CI's Node 18 | Declare minimum engine requirements |\n\n---\n\n## Cross-References\n\n- `dev-dependency-management/references/container-dependency-patterns.md` — lockfiles in Docker builds\n- `dev-dependency-management/references/license-compliance.md` — scanning resolved dependency trees\n- `software-clean-code-standard/references/code-complexity-metrics.md` — dependency complexity as a metric\n- `software-backend/references/nodejs-best-practices.md` — Node.js-specific dependency management\n- `qa-refactoring/references/strangler-fig-migration.md` — managing deps during incremental migration\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":11558,"content_sha256":"5fdf9631154cd7fd72d31526e1d146792ee1351db66d4a2136cc38e34100125d"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Dependency Management — Production Patterns","type":"text"}]},{"type":"paragraph","content":[{"text":"Modern Best Practices (January 2026)","type":"text","marks":[{"type":"strong"}]},{"text":": Lockfile-first workflows, automated security scanning (Dependabot, Snyk, Socket.dev), semantic versioning, minimal dependencies principle, monorepo workspaces (pnpm, Nx, Turborepo), supply chain security (SBOM, AI BOM, Sigstore), reproducible builds, and AI-generated code validation.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"When to Use This Skill","type":"text"}]},{"type":"paragraph","content":[{"text":"The agent should invoke this skill when a user requests:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Adding new dependencies to a project","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Updating existing dependencies safely","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Resolving dependency conflicts or version mismatches","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auditing dependencies for security vulnerabilities","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Understanding lockfile management and reproducible builds","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Setting up monorepo workspaces (pnpm, npm, yarn)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Managing transitive dependencies and overrides","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Choosing between similar packages (bundle size, maintenance, security)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Dependency version constraints and semantic versioning","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Dependency security best practices and supply chain security","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Troubleshooting \"dependency hell\" scenarios","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Package manager configuration and optimization","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Creating reproducible builds across environments","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Quick Reference","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Task","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Tool/Command","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Key Action","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"When to Use","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Install from lockfile","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"npm ci","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"poetry install","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"cargo build","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Clean install, reproducible","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"CI/CD, production deployments","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Add dependency","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"npm install \u003cpkg>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"poetry add \u003cpkg>","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Updates lockfile automatically","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"New feature needs library","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Update dependencies","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"npm update","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"poetry update","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"cargo update","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Updates within version constraints","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Monthly/quarterly maintenance","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Check for vulnerabilities","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"npm audit","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"pip-audit","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"cargo audit","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Scans for known CVEs","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Before releases, weekly","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"View dependency tree","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"npm ls","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"pnpm why","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"pipdeptree","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Shows transitive dependencies","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Debugging conflicts","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Override transitive dep","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"overrides","type":"text","marks":[{"type":"code_inline"}]},{"text":" (npm), ","type":"text"},{"text":"pnpm.overrides","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Force specific version","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Security patch, conflict resolution","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Monorepo setup","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"pnpm workspaces","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"npm workspaces","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Shared dependencies, cross-linking","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Multi-package projects","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Check outdated","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"npm outdated","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"poetry show --outdated","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Lists available updates","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Planning update sprints","type":"text"}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Decision Tree: Dependency Management","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"text"},"content":[{"text":"User needs: [Dependency Task]\n ├─ Adding new dependency?\n │ ├─ Check: Do I really need this? (Can implement in \u003c100 LOC?)\n │ ├─ Check: Is it well-maintained? (Last commit \u003c6 months, >10k downloads/week)\n │ ├─ Check: Bundle size impact? (Use Bundlephobia for JS)\n │ ├─ Check: Security risks? (`npm audit`, Snyk)\n │ └─ If all checks pass → Add with `npm install \u003cpkg>` → Commit lockfile\n │\n ├─ Updating dependencies?\n │ ├─ Security vulnerability? → `npm audit fix` → Test → Deploy immediately\n │ ├─ Routine update?\n │ ├─ Patch versions → `npm update` → Safe, do frequently\n │ ├─ Minor/major → Check CHANGELOG → Test in staging → Update gradually\n │ └─ All at once → [FAIL] RISKY → Update in batches instead\n │\n ├─ Dependency conflict?\n │ ├─ Transitive dependency issue?\n │ ├─ View tree: `npm ls \u003cpackage>`\n │ ├─ Use overrides sparingly: `overrides` in package.json\n │ └─ Document why override is needed\n │ └─ Peer dependency mismatch?\n │ └─ Check version compatibility → Update parent or child\n │\n\t├─ Monorepo project?\n\t│ ├─ Use pnpm workspaces (recommended default)\n\t│ ├─ Shared deps → Root package.json\n\t│ ├─ Package-specific → Package directories\n\t│ └─ Use Nx or Turborepo for task caching\n\t│\n\t└─ Choosing package manager?\n\t ├─ New JS project → **pnpm** (recommended default) or **Bun** (often faster; verify ecosystem maturity)\n\t ├─ Enterprise monorepo → **pnpm** (mature workspace support)\n\t ├─ Speed-focused experimentation → **Bun** (verify ecosystem maturity)\n\t ├─ Existing npm project → Migrate to pnpm or stay (check team preference)\n\t ├─ Python → **uv** (fast), Poetry (mature), pip+venv (simple)\n\t └─ Data science → **conda** or **uv** (faster environment setup)","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Navigation: Core Patterns","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Lockfile Management","type":"text"}]},{"type":"paragraph","content":[{"text":"references/lockfile-management.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/lockfile-management.md","title":null}},{"type":"code_inline"},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Lockfiles ensure reproducible builds by recording exact versions of all dependencies (direct + transitive). Essential for preventing \"works on my machine\" issues.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Golden rules (always commit, never edit manually, regenerate on changes)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Commands by ecosystem (npm ci, poetry install, cargo build)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Troubleshooting lockfile conflicts","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CI/CD integration patterns","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Semantic Versioning (SemVer)","type":"text"}]},{"type":"paragraph","content":[{"text":"references/semver-guide.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/semver-guide.md","title":null}},{"type":"code_inline"},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Understanding version constraints (","type":"text"},{"text":"^","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"~","type":"text","marks":[{"type":"code_inline"}]},{"text":", exact) and how to specify dependency ranges safely.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"SemVer format (MAJOR.MINOR.PATCH)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Version constraint syntax (caret, tilde, exact)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Recommended strategies by project type","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cross-ecosystem version management","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Dependency Security Auditing","type":"text"}]},{"type":"paragraph","content":[{"text":"references/security-scanning.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/security-scanning.md","title":null}},{"type":"code_inline"},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Automated security scanning, vulnerability management, and supply chain security best practices.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Automated tools (Dependabot, Snyk, GitHub Advanced Security)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Running audits (npm audit, pip-audit, cargo audit)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CI integration and alert configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Incident response workflows","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Dependency Selection","type":"text"}]},{"type":"paragraph","content":[{"text":"references/dependency-selection-guide.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/dependency-selection-guide.md","title":null}},{"type":"code_inline"},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Deciding whether to add a new dependency and choosing between similar packages.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Minimal dependencies principle (best dependency is the one you don't add)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Evaluation checklist (maintenance, bundle size, security, alternatives)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Choosing between similar packages (comparison matrix)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When to reject a dependency","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Update Strategies","type":"text"}]},{"type":"paragraph","content":[{"text":"references/update-strategies.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/update-strategies.md","title":null}},{"type":"code_inline"},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Keeping dependencies up to date safely while minimizing breaking changes and security risks.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update strategies (continuous, scheduled, security-only)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Safe update workflow (check outdated, categorize risk, test, deploy)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Automated update tools (Dependabot, Renovate, npm-check-updates)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Handling breaking changes and rollback plans","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Monorepo Management","type":"text"}]},{"type":"paragraph","content":[{"text":"references/monorepo-patterns.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/monorepo-patterns.md","title":null}},{"type":"code_inline"},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Managing multiple related packages in a single repository with shared dependencies.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Workspace tools (pnpm, npm, yarn workspaces)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Monorepo structure and organization","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Build optimization (Nx, Turborepo)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Versioning and publishing strategies","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Transitive Dependencies","type":"text"}]},{"type":"paragraph","content":[{"text":"references/transitive-dependencies.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/transitive-dependencies.md","title":null}},{"type":"code_inline"},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Dealing with dependencies of your dependencies (indirect dependencies).","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Viewing dependency trees (npm ls, pnpm why, pipdeptree)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Resolving transitive conflicts (overrides, resolutions, constraints)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Security risks and version conflicts","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Best practices (use sparingly, document, test)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Ecosystem-Specific Guides","type":"text"}]},{"type":"paragraph","content":[{"text":"references/ecosystem-guides.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/ecosystem-guides.md","title":null}},{"type":"code_inline"},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Language and package-manager-specific best practices.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Node.js (npm, yarn, pnpm comparison and best practices)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Python (pip, poetry, conda)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Rust (cargo), Go (go mod), Java (maven, gradle)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"PHP (composer), .NET (nuget)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Anti-Patterns","type":"text"}]},{"type":"paragraph","content":[{"text":"references/anti-patterns.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/anti-patterns.md","title":null}},{"type":"code_inline"},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Common mistakes to avoid when managing dependencies.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Critical anti-patterns (not committing lockfiles, wildcards, ignoring audits)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Dangerous anti-patterns (never updating, deprecated packages)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Moderate anti-patterns (overusing overrides, ignoring peer deps)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Container Dependency Patterns","type":"text"}]},{"type":"paragraph","content":[{"text":"references/container-dependency-patterns.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/container-dependency-patterns.md","title":null}},{"type":"code_inline"},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Managing dependencies in containerized environments (Docker, OCI).","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Multi-stage builds, layer caching, base image selection","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Runtime vs build dependencies, image scanning, reproducible images","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Version Conflict Resolution","type":"text"}]},{"type":"paragraph","content":[{"text":"references/version-conflict-resolution.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/version-conflict-resolution.md","title":null}},{"type":"code_inline"},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Systematic approaches to resolving dependency version conflicts.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Diamond dependency problems, resolution algorithms by ecosystem","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Override strategies, compatibility matrices, migration paths","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"License Compliance","type":"text"}]},{"type":"paragraph","content":[{"text":"references/license-compliance.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/license-compliance.md","title":null}},{"type":"code_inline"},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Open-source license management and compliance automation.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"License compatibility matrix, copyleft vs permissive, SPDX identifiers","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Automated scanning (FOSSA, license-checker), policy enforcement in CI","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Navigation: Templates","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Node.js","type":"text"}]},{"type":"paragraph","content":[{"text":"assets/nodejs/","type":"text","marks":[{"type":"link","attrs":{"href":"assets/nodejs/","title":null}},{"type":"code_inline"},{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"package-json-template.json","type":"text","marks":[{"type":"link","attrs":{"href":"assets/nodejs/package-json-template.json","title":null}},{"type":"code_inline"}]},{"text":" - Production-ready package.json with best practices","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"npmrc-template.txt","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Team configuration for npm","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"pnpm-workspace-template.yaml","type":"text","marks":[{"type":"link","attrs":{"href":"assets/nodejs/pnpm-workspace-template.yaml","title":null}},{"type":"code_inline"}]},{"text":" - Monorepo workspace setup","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Python","type":"text"}]},{"type":"paragraph","content":[{"text":"assets/python/","type":"text","marks":[{"type":"link","attrs":{"href":"assets/python/","title":null}},{"type":"code_inline"},{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"pyproject-toml-template.toml","type":"text","marks":[{"type":"link","attrs":{"href":"assets/python/pyproject-toml-template.toml","title":null}},{"type":"code_inline"}]},{"text":" - Poetry configuration with best practices","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Automation","type":"text"}]},{"type":"paragraph","content":[{"text":"assets/automation/","type":"text","marks":[{"type":"link","attrs":{"href":"assets/automation/","title":null}},{"type":"code_inline"},{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"dependabot-config.yml","type":"text","marks":[{"type":"link","attrs":{"href":"assets/automation/dependabot-config.yml","title":null}},{"type":"code_inline"}]},{"text":" - GitHub Dependabot configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"renovate-config.json","type":"text","marks":[{"type":"link","attrs":{"href":"assets/automation/renovate-config.json","title":null}},{"type":"code_inline"}]},{"text":" - Renovate Bot configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"audit-checklist.md","type":"text","marks":[{"type":"link","attrs":{"href":"assets/automation/audit-checklist.md","title":null}},{"type":"code_inline"}]},{"text":" - Security audit workflow","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"template-supply-chain-security.md","type":"text","marks":[{"type":"link","attrs":{"href":"assets/automation/template-supply-chain-security.md","title":null}},{"type":"code_inline"},{"type":"strong"}]},{"text":" - ","type":"text"},{"text":"NEW","type":"text","marks":[{"type":"strong"}]},{"text":" SBOM, provenance, vulnerability management","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"template-dependency-upgrade-playbook.md","type":"text","marks":[{"type":"link","attrs":{"href":"assets/automation/template-dependency-upgrade-playbook.md","title":null}},{"type":"code_inline"}]},{"text":" - Upgrade batching, rollout, rollback","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"template-sbom-vuln-triage-checklist.md","type":"text","marks":[{"type":"link","attrs":{"href":"assets/automation/template-sbom-vuln-triage-checklist.md","title":null}},{"type":"code_inline"}]},{"text":" - SBOM mapping + vulnerability triage","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Supply Chain Security","type":"text"}]},{"type":"paragraph","content":[{"text":"assets/automation/template-supply-chain-security.md","type":"text","marks":[{"type":"link","attrs":{"href":"assets/automation/template-supply-chain-security.md","title":null}},{"type":"strong"}]},{"text":" — Production-grade dependency security covering SBOM generation (CycloneDX/SPDX), provenance and attestation (SLSA, Sigstore), vulnerability management SLAs, upgrade playbooks, and EU Cyber Resilience Act requirements.","type":"text"}]},{"type":"paragraph","content":[{"text":"Key rules: generate SBOM per release, sign artifacts (Sigstore/cosign), run audit scans in CI, fix critical CVEs within 24 hours, use ","type":"text"},{"text":"npm ci","type":"text","marks":[{"type":"code_inline"}]},{"text":" (never ","type":"text"},{"text":"npm install","type":"text","marks":[{"type":"code_inline"}]},{"text":") in pipelines, batch non-security updates by risk level.","type":"text"}]},{"type":"paragraph","content":[{"text":"Related templates:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"assets/automation/template-dependency-upgrade-playbook.md","type":"text","marks":[{"type":"link","attrs":{"href":"assets/automation/template-dependency-upgrade-playbook.md","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"assets/automation/template-sbom-vuln-triage-checklist.md","type":"text","marks":[{"type":"link","attrs":{"href":"assets/automation/template-sbom-vuln-triage-checklist.md","title":null}}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"AI-Generated Dependency Risks","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"WARNING","type":"text","marks":[{"type":"strong"}]},{"text":": AI coding agents can introduce vulnerable or non-existent packages at scale (Endor Labs, 2025).","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"The Problem","type":"text"}]},{"type":"paragraph","content":[{"text":"AI tools accelerate coding but introduce supply chain risks:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Hallucinated packages","type":"text","marks":[{"type":"strong"}]},{"text":" — AI suggests packages that don't exist (typosquatting vectors)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Vulnerable dependencies","type":"text","marks":[{"type":"strong"}]},{"text":" — AI recommends outdated or CVE-affected versions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Unnecessary dependencies","type":"text","marks":[{"type":"strong"}]},{"text":" — AI over-relies on packages for simple tasks","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Best Practices","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Do","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Don't","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Treat AI-generated code as untrusted third-party input","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Blindly accept AI dependency suggestions","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Enforce same SAST/SCA scanning for AI-generated code","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Skip security review for \"AI-written\" code","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Verify all AI-suggested packages actually exist","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Trust AI to know current package versions","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Integrate security tools into AI workflows (MCP)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Allow AI to add dependencies without review","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Vet MCP servers as part of supply chain","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use unvetted AI integrations","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Validation Checklist","type":"text"}]},{"type":"paragraph","content":[{"text":"Before accepting AI-suggested dependencies:","type":"text"}]},{"type":"checkbox_list","attrs":{"id":null},"content":[{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Package exists on registry (npm, PyPI, crates.io)","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Package name is spelled correctly (no typosquatting)","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Version is current and maintained","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"npm audit","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"pip-audit","type":"text","marks":[{"type":"code_inline"}]},{"text":" shows no vulnerabilities","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Weekly downloads >1000 (established package)","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Last commit \u003c6 months (actively maintained)","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Optional: AI/Automation","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Note","type":"text","marks":[{"type":"strong"}]},{"text":": AI assists with triage but security decisions need human judgment.","type":"text"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Automated PR triage","type":"text","marks":[{"type":"strong"}]},{"text":" — Categorize dependency updates by risk","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Changelog summarization","type":"text","marks":[{"type":"strong"}]},{"text":" — Summarize breaking changes in updates","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Vulnerability correlation","type":"text","marks":[{"type":"strong"}]},{"text":" — Link CVEs to affected packages","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Bounded Claims","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"AI cannot determine business risk acceptance","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Automated fixes require security team review","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Vulnerability severity context needs human validation","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Quick Decision Matrix","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Scenario","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Recommendation","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Adding new dependency","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Check Bundlephobia, npm audit, weekly downloads, last commit","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Updating dependencies","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"npm outdated","type":"text","marks":[{"type":"code_inline"}]},{"text":", update in batches, test in staging","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Security vulnerability found","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"npm audit fix","type":"text","marks":[{"type":"code_inline"}]},{"text":", review CHANGELOG, test, deploy immediately","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Monorepo setup","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"pnpm workspaces","type":"text","marks":[{"type":"strong"}]},{"text":" or Nx/Turborepo for build caching","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Transitive conflict","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"overrides","type":"text","marks":[{"type":"code_inline"}]},{"text":" sparingly, document why, test thoroughly","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Choosing JS package manager","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"pnpm","type":"text","marks":[{"type":"strong"}]},{"text":" (fastest, disk-efficient), ","type":"text"},{"text":"Bun","type":"text","marks":[{"type":"strong"}]},{"text":" (7× faster), npm (most compatible)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Python environment","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"uv","type":"text","marks":[{"type":"strong"}]},{"text":" (10-100× faster), Poetry (mature), pip+venv (simple), conda (data science)","type":"text"}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Core Principles","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"1. Always Commit Lockfiles","type":"text"}]},{"type":"paragraph","content":[{"text":"Lockfiles ensure reproducible builds across environments. Never add them to ","type":"text"},{"text":".gitignore","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Exception","type":"text","marks":[{"type":"strong"}]},{"text":": Don't commit ","type":"text"},{"text":"Cargo.lock","type":"text","marks":[{"type":"code_inline"}]},{"text":" for Rust libraries (only for applications).","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"2. Use Semantic Versioning","type":"text"}]},{"type":"paragraph","content":[{"text":"Use caret (","type":"text"},{"text":"^","type":"text","marks":[{"type":"code_inline"}]},{"text":") for most dependencies, exact versions for mission-critical, avoid wildcards (","type":"text"},{"text":"*","type":"text","marks":[{"type":"code_inline"}]},{"text":"). See ","type":"text"},{"text":"references/semver-guide.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/semver-guide.md","title":null}},{"type":"code_inline"}]},{"text":" for constraint syntax and strategies.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"3. Audit Dependencies Regularly","type":"text"}]},{"type":"paragraph","content":[{"text":"Run ","type":"text"},{"text":"npm audit","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"pip-audit","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"cargo audit","type":"text","marks":[{"type":"code_inline"}]},{"text":" weekly; fix critical vulnerabilities immediately. See ","type":"text"},{"text":"references/security-scanning.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/security-scanning.md","title":null}},{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"4. Minimize Dependencies","type":"text"}]},{"type":"paragraph","content":[{"text":"The best dependency is the one you don't add. Ask: Can I implement this in \u003c100 LOC? See ","type":"text"},{"text":"references/dependency-selection-guide.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/dependency-selection-guide.md","title":null}},{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"5. Update Regularly","type":"text"}]},{"type":"paragraph","content":[{"text":"Update monthly or quarterly in batches — do not update all at once. See ","type":"text"},{"text":"references/update-strategies.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/update-strategies.md","title":null}},{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"6. Use Overrides Sparingly","type":"text"}]},{"type":"paragraph","content":[{"text":"Only override transitive dependencies for security patches or conflicts. Document why in a comment (","type":"text"},{"text":"// CVE-2023-xxxxx fix","type":"text","marks":[{"type":"code_inline"}]},{"text":"). See ","type":"text"},{"text":"references/transitive-dependencies.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/transitive-dependencies.md","title":null}},{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Related Skills","type":"text"}]},{"type":"paragraph","content":[{"text":"For complementary workflows and deeper dives:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"dev-api-design","type":"text","marks":[{"type":"link","attrs":{"href":"../dev-api-design/SKILL.md","title":null}},{"type":"code_inline"}]},{"text":" - API versioning strategies, dependency injection patterns","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"dev-git-workflow","type":"text","marks":[{"type":"link","attrs":{"href":"../dev-git-workflow/SKILL.md","title":null}},{"type":"code_inline"}]},{"text":" - Git workflows for managing lockfile conflicts, branching strategies","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"qa-testing-strategy","type":"text","marks":[{"type":"link","attrs":{"href":"../qa-testing-strategy/SKILL.md","title":null}},{"type":"code_inline"}]},{"text":" - Testing strategies for dependency updates, integration testing","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"software-security-appsec","type":"text","marks":[{"type":"link","attrs":{"href":"../software-security-appsec/SKILL.md","title":null}},{"type":"code_inline"}]},{"text":" - OWASP Top 10, cryptography standards, authentication patterns","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ops-devops-platform","type":"text","marks":[{"type":"link","attrs":{"href":"../ops-devops-platform/SKILL.md","title":null}},{"type":"code_inline"}]},{"text":" - CI/CD pipelines, Docker containerization, DevSecOps, deployment automation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"docs-codebase","type":"text","marks":[{"type":"link","attrs":{"href":"../docs-codebase/SKILL.md","title":null}},{"type":"code_inline"}]},{"text":" - Documenting dependency choices, ADRs, changelogs","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"External Resources","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"data/sources.json","type":"text","marks":[{"type":"link","attrs":{"href":"data/sources.json","title":null}},{"type":"code_inline"}]},{"text":" for curated resources:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Package managers","type":"text","marks":[{"type":"strong"}]},{"text":": npm, pnpm, Yarn, pip, Poetry, Cargo, Go modules, Maven, Composer","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Semantic versioning","type":"text","marks":[{"type":"strong"}]},{"text":": SemVer spec, version calculators, constraint references","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Security tools","type":"text","marks":[{"type":"strong"}]},{"text":": Snyk, Dependabot, GitHub Advanced Security, OWASP Dependency-Check, pip-audit, cargo-audit, Socket.dev, Renovate","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Lockfile management","type":"text","marks":[{"type":"strong"}]},{"text":": Official docs for package-lock.json, poetry.lock, Cargo.lock, pnpm-lock.yaml","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Monorepo tools","type":"text","marks":[{"type":"strong"}]},{"text":": pnpm workspaces, npm workspaces, Yarn workspaces, Nx, Turborepo, Lerna, Bazel","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Analysis tools","type":"text","marks":[{"type":"strong"}]},{"text":": Bundlephobia, npm-check-updates, depcheck, pipdeptree, cargo tree","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Supply chain security","type":"text","marks":[{"type":"strong"}]},{"text":": SLSA framework, SBOM (CISA), Sigstore, npm provenance, OpenSSF Scorecard","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Best practices","type":"text","marks":[{"type":"strong"}]},{"text":": npm/Poetry/Cargo guides, ACM Queue articles, dependency hell references","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Version management","type":"text","marks":[{"type":"strong"}]},{"text":": nvm, pyenv, rustup, asdf","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Learning resources","type":"text","marks":[{"type":"strong"}]},{"text":": npm guides, Python Packaging User Guide, Rust Book, Monorepo.tools","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Usage Notes","type":"text"}]},{"type":"paragraph","content":[{"text":"For Codex / Claude Code:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use this skill when users need dependency management guidance","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reference specific resources based on the task (lockfiles, security, updates)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Provide ecosystem-specific guidance (Node.js, Python, Rust)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Always recommend security audits and reproducible builds","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Encourage minimal dependencies and regular updates","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Link to templates for common configurations","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Best Practices:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Always commit lockfiles (except Cargo.lock for libraries)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use semantic versioning (caret for most deps, exact for critical)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Audit dependencies weekly (","type":"text"},{"text":"npm audit","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"pip-audit","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"cargo audit","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update dependencies monthly or quarterly (not all at once)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Choose package manager based on project needs (pnpm for speed, Poetry for Python apps)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Document dependency choices in ADRs (Architecture Decision Records)","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Success Criteria:","type":"text","marks":[{"type":"strong"}]},{"text":" Dependencies are minimal, well-maintained, secure, reproducible across environments, and regularly audited for vulnerabilities.","type":"text"}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Trend Awareness Protocol","type":"text"}]},{"type":"paragraph","content":[{"text":"IMPORTANT","type":"text","marks":[{"type":"strong"}]},{"text":": When users ask recommendation questions about package managers, dependency tools, or supply chain security, you MUST use WebSearch to check current trends before answering.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Trigger Conditions","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"What's the best package manager for [ecosystem]?\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"What should I use for [dependency management/security]?\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"What's the latest in dependency management?\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Current best practices for [npm/pnpm/Poetry]?\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Is [tool/approach] still relevant in 2026?\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"[pnpm] vs [npm] vs [yarn]?\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Best dependency security scanner?\"","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Required Searches","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Search: ","type":"text"},{"text":"\"dependency management best practices 2026\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Search: ","type":"text"},{"text":"\"[specific tool] vs alternatives 2026\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Search: ","type":"text"},{"text":"\"supply chain security trends January 2026\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Search: ","type":"text"},{"text":"\"[package manager] features 2026\"","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"What to Report","type":"text"}]},{"type":"paragraph","content":[{"text":"After searching, provide:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Current landscape","type":"text","marks":[{"type":"strong"}]},{"text":": What dependency tools are popular NOW","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Emerging trends","type":"text","marks":[{"type":"strong"}]},{"text":": New package managers, security tools, or patterns gaining traction","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Deprecated/declining","type":"text","marks":[{"type":"strong"}]},{"text":": Tools/approaches losing relevance or support","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Recommendation","type":"text","marks":[{"type":"strong"}]},{"text":": Based on fresh data, not just static knowledge","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example Topics (verify with fresh search)","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Package managers (pnpm, npm, yarn, Poetry, uv for Python)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Security scanning (Snyk, Dependabot, Socket.dev)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Supply chain security (SBOM, Sigstore, SLSA)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Monorepo tools (Nx, Turborepo, Bazel)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Lockfile and reproducibility patterns","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Automated dependency updates (Renovate, Dependabot)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Ops Preflight: Dependency and Toolchain Health (for LLM Agents)","type":"text"}]},{"type":"paragraph","content":[{"text":"Run this before build/test/edit loops to prevent avoidable churn such as ","type":"text"},{"text":"next: command not found","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# 1) Runtime + package manager sanity\nnode -v\nnpm -v\n\n# 2) Lockfile and install mode\nls -1 package-lock.json pnpm-lock.yaml yarn.lock 2>/dev/null\ntest -d node_modules || npm ci\n\n# 3) Verify framework binaries resolve\nnpx next --version 2>/dev/null || echo \"next missing\"\nnpx eslint --version 2>/dev/null || echo \"eslint missing\"\n\n# 4) Surface dependency graph issues early\nnpm ls --depth=0","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Remediation Rules","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If binary missing: install from lockfile, do not ad-hoc install random versions.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If lockfile drift detected: re-install using project standard tool (","type":"text"},{"text":"npm ci","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"pnpm install --frozen-lockfile","type":"text","marks":[{"type":"code_inline"}]},{"text":", etc).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If peer dependency conflict appears, fix root cause before continuing broad edits.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cache these checks at session start for long agent runs.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Fact-Checking","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prefer primary sources; report source links and dates for volatile information.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If web access is unavailable, state the limitation and mark guidance as unverified.","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"dev-dependency-management","author":"@skillopedia","source":{"stars":60,"repo_name":"ai-agents-public","origin_url":"https://github.com/vasilyu1983/ai-agents-public/blob/HEAD/frameworks/shared-skills/skills/dev-dependency-management/SKILL.md","repo_owner":"vasilyu1983","body_sha256":"929369e4d3a5c0ce529735d8c4d3c8de897bee69ae930c6e754a40420cdb08df","cluster_key":"06f388f4fe9b12e2ec44d04ed1229506d62f96bb06ec65682bed585fe263b7da","clean_bundle":{"format":"clean-skill-bundle-v1","source":"vasilyu1983/ai-agents-public/frameworks/shared-skills/skills/dev-dependency-management/SKILL.md","attachments":[{"id":"53ffaa86-1e0b-5adb-b080-ddc03aeee3dd","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/53ffaa86-1e0b-5adb-b080-ddc03aeee3dd/attachment.md","path":"assets/automation/audit-checklist.md","size":7823,"sha256":"ed008a4a26360a70786077a82f82d2a03974b166a8f3ce39d6cf6bb0ba725589","contentType":"text/markdown; charset=utf-8"},{"id":"9d537df9-7787-5e0a-a151-5afe32f7d890","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9d537df9-7787-5e0a-a151-5afe32f7d890/attachment.yml","path":"assets/automation/dependabot-config.yml","size":2028,"sha256":"068a74f90bd3bf8b284e83c2ca903406e0bcf8892aabee518274dca159b657f5","contentType":"application/yaml; charset=utf-8"},{"id":"4f8d3da4-2872-5ceb-9d09-72a21bac138c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4f8d3da4-2872-5ceb-9d09-72a21bac138c/attachment.json","path":"assets/automation/renovate-config.json","size":3857,"sha256":"04ed6c51e374213f5476ffae6fd896f8a55901a462dd8e79122061f39bf65e1b","contentType":"application/json; charset=utf-8"},{"id":"1936c7ca-68ba-52e8-8c61-60795d05f6a5","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/1936c7ca-68ba-52e8-8c61-60795d05f6a5/attachment.md","path":"assets/automation/template-dependency-upgrade-playbook.md","size":2951,"sha256":"6de9398118171639f6c0114840872c3136812afb97083b86a98882390df235a1","contentType":"text/markdown; charset=utf-8"},{"id":"d187ab74-222a-5dba-b205-eb8d5c9a112b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d187ab74-222a-5dba-b205-eb8d5c9a112b/attachment.md","path":"assets/automation/template-sbom-vuln-triage-checklist.md","size":2930,"sha256":"7ac73afea206ca9a0f9220a2e87478c84bc9faa5d9c1a6c796cca2cde4d32002","contentType":"text/markdown; charset=utf-8"},{"id":"94142dc6-c4db-5fef-962a-116374c4f495","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/94142dc6-c4db-5fef-962a-116374c4f495/attachment.md","path":"assets/automation/template-supply-chain-security.md","size":10160,"sha256":"fb3b26601ab076513dc2d22471e2872bf9e8ee097aa6251c3c7cbe55cdc88de0","contentType":"text/markdown; charset=utf-8"},{"id":"5d45cc72-a87b-5a71-8302-b615694f5cc2","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5d45cc72-a87b-5a71-8302-b615694f5cc2/attachment.txt","path":"assets/nodejs/npmrc-template.txt","size":2919,"sha256":"42610910b54ecd23cc1c01c94708c1efff116102c5f7183d8ad24dacfbbe081f","contentType":"text/plain; charset=utf-8"},{"id":"3d491619-2bd9-5c77-8948-336ab565092b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/3d491619-2bd9-5c77-8948-336ab565092b/attachment.json","path":"assets/nodejs/package-json-template.json","size":1525,"sha256":"f612e3a666d5c65adef25a30f3ab67609015eaa9af34da623d44b4c2f390c419","contentType":"application/json; charset=utf-8"},{"id":"abe4f832-40d5-5b53-9411-c6ea5ede1a14","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/abe4f832-40d5-5b53-9411-c6ea5ede1a14/attachment.yaml","path":"assets/nodejs/pnpm-workspace-template.yaml","size":408,"sha256":"bc5207004e8061a504ab61ea20cea6abdadfc34adb06ac4b21da1f9d7f3e2a26","contentType":"application/yaml; charset=utf-8"},{"id":"2e5a8e3b-c2e1-5791-ac9c-5383accb0137","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/2e5a8e3b-c2e1-5791-ac9c-5383accb0137/attachment.toml","path":"assets/python/pyproject-toml-template.toml","size":3161,"sha256":"3a4efafc4cb0b76a1e5e2dbf70188ccfc188b342c83ef1cd94f5f3f29ecae466","contentType":"text/plain; charset=utf-8"},{"id":"ab7e2f57-2ec3-5662-a2ee-60fa0c949eb3","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/ab7e2f57-2ec3-5662-a2ee-60fa0c949eb3/attachment.json","path":"data/sources.json","size":6767,"sha256":"2793533de84a8dd714ee76cac22ec5b6dbf4e4840b527c2aab7ac6c62d4c8eac","contentType":"application/json; charset=utf-8"},{"id":"d82268fa-5782-5abd-9184-1b5948ffe16b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d82268fa-5782-5abd-9184-1b5948ffe16b/attachment.md","path":"references/anti-patterns.md","size":13125,"sha256":"3b258338d097e0076610fd5886ee119b4c40451f1fdd9c3d947c1b54abb87089","contentType":"text/markdown; charset=utf-8"},{"id":"b96a8708-2416-5622-aad5-fb3994f062e6","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b96a8708-2416-5622-aad5-fb3994f062e6/attachment.md","path":"references/container-dependency-patterns.md","size":11906,"sha256":"a3685dbc55f44344324f22970571690b9a94b313b4497773b3f2626fdfb7e635","contentType":"text/markdown; charset=utf-8"},{"id":"8a2b2cce-2ce8-5559-807b-eb300bad26fb","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/8a2b2cce-2ce8-5559-807b-eb300bad26fb/attachment.md","path":"references/dependency-selection-guide.md","size":10898,"sha256":"d332b8a2dc9e320c03b3b94c5bfb5e9ed18ff434c6774830081af728c16c0747","contentType":"text/markdown; charset=utf-8"},{"id":"15faf180-d5f4-59fe-ad62-a483db88fb3c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/15faf180-d5f4-59fe-ad62-a483db88fb3c/attachment.md","path":"references/ecosystem-guides.md","size":18411,"sha256":"68cc0699068197bc0c82c94e2ce874fa3d28b6a60fd131762e9790a57bcdbe10","contentType":"text/markdown; charset=utf-8"},{"id":"aa6c2ae9-697d-5ab6-b39d-c8ef7bdc5918","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/aa6c2ae9-697d-5ab6-b39d-c8ef7bdc5918/attachment.md","path":"references/lockfile-management.md","size":12497,"sha256":"c768a9d66ec93eaf592f8e1c4384419d6a3d9c67aa487e8ba56764eac2ff5fe0","contentType":"text/markdown; charset=utf-8"},{"id":"1e8ba16c-7b04-5a05-8add-9bef128dc474","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/1e8ba16c-7b04-5a05-8add-9bef128dc474/attachment.md","path":"references/monorepo-patterns.md","size":14221,"sha256":"d0dbf4a97c215e589aa6f466f8be628f6d680032a38b4e11419d898ddb3696cb","contentType":"text/markdown; charset=utf-8"},{"id":"131b8ecb-d61b-578c-b0f6-709c198576d6","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/131b8ecb-d61b-578c-b0f6-709c198576d6/attachment.md","path":"references/security-scanning.md","size":14411,"sha256":"3b5760843069a3608acc7ea6248c30749a36c281dd5babf84f0561f7643654b0","contentType":"text/markdown; charset=utf-8"},{"id":"a3aff3cc-3e88-55f0-a012-5fefff139594","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a3aff3cc-3e88-55f0-a012-5fefff139594/attachment.md","path":"references/semver-guide.md","size":11972,"sha256":"baf96b9c64206131776d9679ed2a117113faf05f277a5d611bfbc3c7c8b33de7","contentType":"text/markdown; charset=utf-8"},{"id":"5822f7c2-98fa-5994-a5e6-7f727357ab01","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5822f7c2-98fa-5994-a5e6-7f727357ab01/attachment.md","path":"references/transitive-dependencies.md","size":12459,"sha256":"75117c516f956ac5ca38363997e9c817a250c080f35667c89d377712cfc09bef","contentType":"text/markdown; charset=utf-8"},{"id":"46cd3956-c9f9-56e6-b8f0-ec8db821d716","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/46cd3956-c9f9-56e6-b8f0-ec8db821d716/attachment.md","path":"references/update-strategies.md","size":12769,"sha256":"1018c1f02508481fb97073600d9f0aff12de18dd6ab8fd1abef0ef8a30181872","contentType":"text/markdown; charset=utf-8"},{"id":"a954997b-e2db-5f51-aea7-08bfbd97dfd6","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a954997b-e2db-5f51-aea7-08bfbd97dfd6/attachment.md","path":"references/version-conflict-resolution.md","size":11558,"sha256":"5fdf9631154cd7fd72d31526e1d146792ee1351db66d4a2136cc38e34100125d","contentType":"text/markdown; charset=utf-8"}],"bundle_sha256":"0243bb23de5cbd561a98c469e04bd55a2a4ff68c80660eac977e92a98b34e183","attachment_count":22,"text_attachments":22,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"frameworks/shared-skills/skills/dev-dependency-management/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"security","category_label":"Security"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"security","import_tag":"clean-skills-v1","description":"Dependency management across npm, pip, cargo, and maven. Use when managing lockfiles, security scanning, versioning, or monorepo workspaces."}},"renderedAt":1782979615529}

Dependency Management — Production Patterns Modern Best Practices (January 2026) : Lockfile-first workflows, automated security scanning (Dependabot, Snyk, Socket.dev), semantic versioning, minimal dependencies principle, monorepo workspaces (pnpm, Nx, Turborepo), supply chain security (SBOM, AI BOM, Sigstore), reproducible builds, and AI-generated code validation. --- When to Use This Skill The agent should invoke this skill when a user requests: - Adding new dependencies to a project - Updating existing dependencies safely - Resolving dependency conflicts or version mismatches - Auditing de…