dependency-conflict-resolver
在安装前检测并解决跨npm/yarn/pnpm、pip/poetry、cargo和composer的包依赖冲突。安装/升级包时自动触发。验证对等依赖、版本兼容性、安全漏洞。自动解决安全冲突(补丁、开发依赖),建议手动审查破坏性更改。防止冲突版本、安全漏洞、构建失败。
name: dependency-conflict-resolver description: Detect and resolve package dependency conflicts before installation across npm/yarn/pnpm, pip/poetry, cargo, and composer. Auto-trigger when installing/upgrading packages. Validates peer dependencies, version compatibility, security vulnerabilities. Auto-resolves safe conflicts (patches, dev deps), suggests manual review for breaking changes. Prevents conflicting versions, security vulnerabilities, broken builds.
Proactively detect and resolve dependency conflicts before package installation to prevent broken builds, security vulnerabilities, and version incompatibilities across JavaScript, Python, Rust, and PHP ecosystems. **Pre-installation check workflow:**- Detect package manager: Identify ecosystem from lockfiles (package-lock.json, requirements.txt, Cargo.lock, composer.lock)
- Scan for conflicts: Check peer dependencies, version ranges, transitive dependencies
- Security audit: Run ecosystem-specific audit tools (npm audit, pip-audit, cargo-audit, composer audit)
- Analyze severity: Classify conflicts by risk level (safe auto-fix, manual review, blocking)
- Present resolution: Auto-apply safe fixes, suggest alternatives for breaking changes, block critical vulnerabilities with alternatives
[CONFLICT DETECTED] Package: react@18.0.0 Conflict: react-dom@17.0.0 requires react ^17.0.0 Risk: MEDIUM (breaking change)
[RECOMMENDED ACTION] Option 1: Upgrade react-dom to ^18.0.0 (recommended) npm install react@18.0.0 react-dom@18.0.0
Option 2: Downgrade react to ^17.0.0 npm install react@17.0.0
[SECURITY CHECK] ✓ No known vulnerabilities in react@18.0.0 ✓ No known vulnerabilities in react-dom@18.0.0
</quick_example>
</quick_start>
<workflow>
<detection_phase>
**1. Identify Package Manager and Context**
Scan current directory for lockfiles and package manifests:
- **JavaScript**: package.json + (package-lock.json | yarn.lock | pnpm-lock.yaml)
- **Python**: requirements.txt | Pipfile | pyproject.toml + (Pipfile.lock | poetry.lock)
- **Rust**: Cargo.toml + Cargo.lock
- **PHP**: composer.json + composer.lock
Extract:
- Current dependency versions (from lockfile)
- Requested package and version (from user command)
- Version constraints (from manifest)
</detection_phase>
<conflict_analysis>
**2. Analyze Dependency Conflicts**
Check for conflicts in order of severity:
**A. Peer Dependency Conflicts**
- Compare requested version against peer dependency requirements
- Identify which packages will be incompatible
- Calculate semver compatibility ranges
**B. Transitive Dependency Conflicts**
- Build dependency graph of all transitive dependencies
- Detect duplicate packages with incompatible versions
- Identify shared dependencies requiring specific versions
**C. Version Constraint Violations**
- Validate against existing version constraints in manifest
- Check for semver range compatibility (^, ~, >=, etc.)
- Detect locked versions that prevent resolution
**D. Platform/Runtime Conflicts**
- Check Node.js, Python, PHP version requirements
- Validate feature flags (Rust features)
- Check platform-specific dependencies
</conflict_analysis>
<security_audit>
**3. Security Vulnerability Scan**
Run ecosystem-specific security audits:
**JavaScript (npm/yarn/pnpm):**
```bash
npm audit --json
# Parse output for HIGH/CRITICAL vulnerabilities
# Check: GHSA IDs, CVE numbers, severity scores
Python (pip/poetry):
pip-audit --format json
# Or: poetry audit --json
# Parse PyPA Advisory Database results
Rust (cargo):
cargo audit --json
# Check RustSec Advisory Database
# Identify RUSTSEC-YYYY-NNNN advisories
PHP (composer):
composer audit --format json
# Parse security advisories
# Check for blocked insecure packages
For each vulnerability found:
- Extract severity (LOW, MODERATE, HIGH, CRITICAL)
- Identify patched versions
- Find alternative packages if no patch available
- Assess exploitability and context
Auto-resolve (apply without asking):
- Patch version updates (1.2.3 → 1.2.4)
- Dev dependency conflicts with no production impact
- Security patches within same minor version
- Compatible semver range adjustments (^1.2.0 allows 1.2.4)
Suggest manual review (present options):
- Minor version updates (1.2.x → 1.3.x)
- Production dependency conflicts
- Peer dependency mismatches requiring upgrades
- Multiple resolution paths with tradeoffs
Block with alternatives (prevent installation):
- Major version conflicts requiring breaking changes
- Critical/High security vulnerabilities without patches
- Incompatible platform/runtime requirements
- Circular dependency deadlocks
Resolution output format:
[CONFLICT TYPE] Brief description
Package: package-name@requested-version
Current: package-name@current-version
Conflict: dependency-name requires version-constraint
[IMPACT ASSESSMENT]
Risk: LOW | MEDIUM | HIGH | CRITICAL
Scope: dev-only | production | peer-dependency | transitive
[RECOMMENDED ACTIONS]
1. [Primary recommendation with command]
2. [Alternative approach with tradeoffs]
3. [Fallback option if applicable]
[SECURITY STATUS]
✓ No vulnerabilities | ⚠ Vulnerabilities found (details below)
**5. Execute Resolution**
For auto-resolvable conflicts:
- Generate updated install command with resolved versions
- Execute installation with resolved dependencies
- Verify lockfile updates
- Log changes for review
For manual review conflicts:
- Present options with AskUserQuestion tool
- Explain tradeoffs for each option
- Execute user-selected resolution
- Confirm successful installation
For blocking conflicts:
- Prevent installation
- Display detailed error explanation
- Suggest alternative packages or version ranges
- Provide documentation links for further investigation
Common conflict patterns:
- React version mismatches between react and react-dom
- Peer dependency warnings for plugin ecosystems (Babel, ESLint, Webpack)
- Duplicate packages at different major versions in monorepos
Resolution tools:
npm ls <package>- Show dependency tree for packagenpm why <package>- Explain why package is installednpm audit fix- Auto-fix vulnerabilitiesnpm overrides(package.json) - Force specific versions globally
See references/javascript-patterns.md for detailed examples.
Python (pip/poetry)
Common conflict patterns:
- Platform-specific wheels causing resolution failures
- Conflicting constraints from multiple requirements files
- Python version incompatibilities (3.8 vs 3.9+ features)
Resolution tools:
pip check- Verify installed packages have compatible dependenciespip install --dry-run- Simulate installation without applyingpoetry show --tree- Display dependency treepoetry update --dry-run- Preview updates without applying
See references/python-patterns.md for detailed examples.
Rust (cargo)
Common conflict patterns:
- Feature flag conflicts across workspace members
- Git dependencies with conflicting version constraints
- Platform-specific dependencies (Windows vs Linux)
Resolution tools:
cargo tree -d- Show duplicate dependenciescargo tree -i <package>- Show inverse dependenciescargo update --dry-run- Preview updatescargo outdated- Check for newer versions
See references/rust-patterns.md for detailed examples.
PHP (composer)
Common conflict patterns:
- Platform requirements (PHP version, extensions)
- Symfony component version mismatches
- Security advisories blocking updates
Resolution tools:
composer why <package>- Show why package is installedcomposer why-not <package> <version>- Explain why version can't be installedcomposer outdated- List available updatescomposer audit- Security vulnerability scan
See references/php-patterns.md for detailed examples.
**Semver Compatibility Analysis**Understand version constraint symbols:
^1.2.3→ >=1.2.3 <2.0.0 (compatible changes)~1.2.3→ >=1.2.3 <1.3.0 (patch updates only)>=1.2.3 <2.0.0→ Explicit range1.2.x→ Any patch version in 1.2.x*→ Any version (avoid in production)
Lockfile Strategy:
- Always commit lockfiles (package-lock.json, poetry.lock, etc.)
- Use
npm ci/poetry installin CI/CD (installs exact versions) - Regularly update dependencies to avoid security debt
- Use automated tools (Dependabot, Renovate) for monitoring
Monorepo Considerations:
- Check workspace/sub-package dependencies
- Ensure consistent versions across workspace
- Use workspace protocols (pnpm workspace:, yarn workspace:)
- Validate peer dependencies across workspace packages
Security Best Practices:
- Prioritize CRITICAL and HIGH vulnerabilities
- Assess vulnerability context (dev vs production runtime)
- Check if vulnerability is exploitable in your usage
- Subscribe to security advisories for your ecosystem
- Integrate audit checks into CI/CD pipelines
See references/advanced-resolution.md for complex scenarios.
**Avoid these common mistakes:**1. Blindly using --force or --legacy-peer-deps
- Problem: Bypasses conflict detection, hides real issues
- Alternative: Investigate root cause, resolve properly
2. Ignoring security warnings
- Problem: Leaves known vulnerabilities in production
- Alternative: Assess severity, update or find alternatives
3. Using wildcard versions (*) in production
- Problem: Unpredictable builds, potential breaking changes
- Alternative: Use specific version ranges (^, ~)
4. Deleting lockfiles to "fix" conflicts
- Problem: Loses reproducible builds, may install incompatible versions
- Alternative: Resolve conflicts properly, regenerate lockfile
5. Installing packages without checking compatibility
- Problem: Breaks existing functionality, wastes debugging time
- Alternative: Use this skill to check before installing
6. Mixing package managers (npm + yarn)
- Problem: Conflicting lockfiles, inconsistent dependency resolution
- Alternative: Standardize on one package manager per project
7. Upgrading all dependencies at once
- Problem: Hard to identify which upgrade caused breakage
- Alternative: Update incrementally, test between updates
8. Using outdated audit tools
- Problem: Misses recent vulnerabilities and advisories
- Alternative: Keep audit tools updated, use latest patterns
- ✓ All peer dependencies are satisfied
- ✓ No version constraint violations
- ✓ Security audit passes (or vulnerabilities acknowledged)
- ✓ Lockfile updated consistently
- ✓ Installation completes without errors
- ✓ Dependency tree has no duplicate incompatible versions
- ✓ Platform/runtime requirements met
- ✓ Tests pass after installation (if applicable)
Blocked installation when:
- ✗ Critical security vulnerabilities without patches
- ✗ Circular dependency deadlock
- ✗ Incompatible platform requirements (Node 14 vs Node 18)
- ✗ Breaking changes without user approval
- references/javascript-patterns.md - npm/yarn/pnpm conflict examples and solutions
- references/python-patterns.md - pip/poetry conflict examples and solutions
- references/rust-patterns.md - cargo conflict examples and solutions
- references/php-patterns.md - composer conflict examples and solutions
- references/advanced-resolution.md - Complex scenarios (monorepos, workspaces, feature flags)
- references/security-audit-guide.md - Security vulnerability assessment and remediation