dependency-conflict-resolver

<objective> 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. </objective> <quick_start> <workflow> **Pre-installation check workflow:**

1. Detect package manager: Identify ecosystem from lockfiles (package-lock.json, requirements.txt, Cargo.lock, composer.lock)
2. Scan for conflicts: Check peer dependencies, version ranges, transitive dependencies
3. Security audit: Run ecosystem-specific audit tools (npm audit, pip-audit, cargo-audit, composer audit)
4. Analyze severity: Classify conflicts by risk level (safe auto-fix, manual review, blocking)
5. Present resolution: Auto-apply safe fixes, suggest alternatives for breaking changes, block critical vulnerabilities with alternatives</workflow>

<trigger_detection> **Auto-invoke when detecting these commands:** - `npm install`, `npm i`, `yarn add`, `pnpm add` - `pip install`, `poetry add` - `cargo add`, `cargo install` - `composer require`, `composer install` </trigger_detection> <quick_example> ```bash # User attempts: npm install react@18.0.0 # Skill detects: Peer dependency conflict with react-dom@17.0.0

[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</security_audit>

<resolution_strategy> **4. Classify Conflicts and Generate Resolutions**

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)

</resolution_strategy> <execution_phase> **5. Execute Resolution**

For auto-resolvable conflicts:

1. Generate updated install command with resolved versions
2. Execute installation with resolved dependencies
3. Verify lockfile updates
4. Log changes for review

For manual review conflicts:

1. Present options with AskUserQuestion tool
2. Explain tradeoffs for each option
3. Execute user-selected resolution
4. Confirm successful installation

For blocking conflicts:

1. Prevent installation
2. Display detailed error explanation
3. Suggest alternative packages or version ranges
4. Provide documentation links for further investigation</execution_phase> </workflow>

<ecosystem_specific_patterns> **JavaScript (npm/yarn/pnpm)**

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 package
• npm why <package> - Explain why package is installed
• npm audit fix - Auto-fix vulnerabilities
• npm 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 dependencies
• pip install --dry-run - Simulate installation without applying
• poetry show --tree - Display dependency tree
• poetry 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 dependencies
• cargo tree -i <package> - Show inverse dependencies
• cargo update --dry-run - Preview updates
• cargo 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 installed
• composer why-not <package> <version> - Explain why version can't be installed
• composer outdated - List available updates
• composer audit - Security vulnerability scan

See references/php-patterns.md for detailed examples. </ecosystem_specific_patterns>

<advanced_features> **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 range
• 1.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 install in 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. </advanced_features>

<anti_patterns> **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</anti_patterns>

<success_criteria> **Conflict successfully resolved when:**

• ✓ 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</success_criteria>

<reference_guides> For ecosystem-specific details and advanced scenarios:

• 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</reference_guides>