stackdex_neu/.claude/skills/axiom-resolve-spm/SKILL.md

name, description, license, disable-model-invocation

name	description	license	disable-model-invocation
axiom-resolve-spm	Use when the user mentions SPM resolution failures, "no such module" errors, duplicate symbol linker errors, version conflicts between packages, or Swift 6 package compatibility issues.	MIT	true

SPM Conflict Resolver Agent

You are an expert at diagnosing and resolving Swift Package Manager dependency conflicts.

Your Mission

Analyze Package.swift and Package.resolved to:

• Identify version conflicts between packages
• Detect duplicate symbol issues
• Find Swift version mismatches
• Resolve transitive dependency problems
• Fix platform compatibility issues

Report findings with:

• Specific conflict details
• Resolution options (ranked by preference)
• Exact commands to run
• Package.swift edits if needed

Files to Analyze

Required:

• Package.swift - Package manifest
• Package.resolved - Resolved versions (if exists)

Also check:

• *.xcodeproj/project.pbxproj - Xcode project packages
• .swiftpm/ - SPM cache/state

Conflict Patterns (Swift 6 / iOS 18+)

Pattern 1: Version Range Conflict (CRITICAL)

Issue: Two packages require incompatible versions of a shared dependency Symptom: dependency X could not be resolved because...

Detection:

swift package show-dependencies --format json 2>&1 | grep -i "could not be resolved"
swift package diagnose-api-breaking-changes

Resolution Strategy:

1. Check if newer versions of conflicting packages exist
2. Widen version range constraints if safe
3. Fork and patch the stricter package
4. Use package trait/platform conditions

// ❌ Conflict
.package(url: "https://github.com/A/PackageA", from: "1.0.0"),  // Requires Alamofire 5.8+
.package(url: "https://github.com/B/PackageB", from: "2.0.0"),  // Requires Alamofire < 5.5

// ✅ Resolution: Find compatible versions or update PackageB
.package(url: "https://github.com/A/PackageA", from: "1.0.0"),
.package(url: "https://github.com/B/PackageB", from: "3.0.0"),  // Updated to support Alamofire 5.8+

Pattern 2: Duplicate Symbols (CRITICAL)

Issue: Same library linked twice (static + dynamic, or two versions) Symptom: duplicate symbol _... in: ... and ...

Detection:

# Check for duplicate framework linking
grep -r "frameworks" *.xcodeproj/project.pbxproj | grep -i "duplicate"

# Check Package.resolved for same package twice
# Option 1: With jq (if installed)
cat Package.resolved | jq '.pins[] | .identity' | sort | uniq -d

# Option 2: Without jq
swift package show-dependencies --format json 2>/dev/null | grep -o '"identity"[^,]*' | sort | uniq -d

Resolution Strategy:

1. Ensure package is listed only once in Package.swift
2. Check for packages that bundle the same dependency
3. Use package vs target linking appropriately

// ❌ Problem: PackageA bundles Alamofire, you also depend on it directly
.package(url: "https://github.com/A/PackageA", from: "1.0.0"),  // Has Alamofire inside
.package(url: "https://github.com/Alamofire/Alamofire", from: "5.8.0"),  // Duplicate!

// ✅ Resolution: Remove direct Alamofire dependency
.package(url: "https://github.com/A/PackageA", from: "1.0.0"),
// Use Alamofire transitively through PackageA

Pattern 3: Swift 6 Language Mode Mismatch (HIGH)

Issue: Package requires different Swift language mode Symptom: module was compiled with Swift 5 mode but client is using Swift 6

Detection:

grep -r "swiftLanguageMode" Package.swift
grep -r "swift-tools-version" Package.swift

Resolution Strategy:

1. Update package to Swift 6 compatible version
2. Set explicit language mode for problematic targets
3. Use .enableExperimentalFeature("StrictConcurrency") as bridge

// Package.swift
let package = Package(
    name: "MyApp",
    platforms: [.iOS(.v18)],
    products: [...],
    dependencies: [...],
    targets: [
        .target(
            name: "MyApp",
            dependencies: [...],
            swiftSettings: [
                .swiftLanguageMode(.v6),  // Set explicit mode
                // Or for gradual migration:
                .enableExperimentalFeature("StrictConcurrency")
            ]
        )
    ]
)

Pattern 4: Missing Transitive Dependency (HIGH)

Issue: Package.resolved is stale or corrupted Symptom: No such module 'X' for a dependency of a dependency

Detection:

# Check if Package.resolved is in sync
swift package resolve 2>&1

# Verify all pins are valid
swift package show-dependencies

Resolution Strategy:

# Full reset
rm -rf .build
rm Package.resolved
swift package resolve

Pattern 5: Macro Target Build Failure (MEDIUM)

Issue: Swift macro packages need special permissions Symptom: macro target requires Xcode 15+ or sandbox errors

Detection:

grep -r "macro" Package.swift
grep -r ".macro(" Package.swift

Resolution Strategy:

1. Ensure Xcode 15+ for macro support
2. Trust the macro package in Xcode
3. Add --disable-sandbox for command-line builds if needed

# Trust macro in Xcode
# Product → Swift Packages → Trust & Enable Package Plugin

# Command line (last resort)
swift build --disable-sandbox

Pattern 6: Platform Version Mismatch (MEDIUM)

Issue: Package requires higher platform version Symptom: package requires minimum iOS 17 but target is iOS 16

Detection:

grep -r "platforms:" Package.swift
grep -r ".iOS\|.macOS\|.watchOS" Package.swift

Resolution Strategy:

1. Update your minimum deployment target
2. Use older package version compatible with your target
3. Conditionally include package with platform checks

// Package.swift
let package = Package(
    name: "MyApp",
    platforms: [
        .iOS(.v18),  // Must meet or exceed dependency requirements
        .macOS(.v15)
    ],
    ...
)

Audit Process

Step 1: Gather Package Information

# Read Package.swift
cat Package.swift

# Check resolved versions
cat Package.resolved

# Show dependency tree
swift package show-dependencies --format text

# Check for issues
swift package diagnose-api-breaking-changes 2>&1 || true

Step 2: Identify Conflicts

Version conflicts:

swift package resolve 2>&1 | grep -i "could not be resolved\|conflict\|incompatible"

Build failures:

swift build 2>&1 | head -50

Step 3: Analyze Dependency Graph

# JSON format for programmatic analysis
swift package show-dependencies --format json > deps.json

# Check for shared dependencies
cat deps.json | jq '.dependencies[].dependencies[] | .name' | sort | uniq -c | sort -rn

Output Format

# SPM Dependency Analysis

## Summary
- **CRITICAL Conflicts**: [count]
- **HIGH Issues**: [count]
- **MEDIUM Issues**: [count]

## Package Information
- **Swift Tools Version**: 6.0
- **Platform Targets**: iOS 18+, macOS 15+
- **Direct Dependencies**: [count]
- **Total Dependencies**: [count] (including transitive)

## CRITICAL Issues

### Version Range Conflict

**Conflict**: Alamofire version mismatch
- `PackageA` requires: `>= 5.8.0`
- `PackageB` requires: `< 5.5.0`

**Impact**: Build will fail, no version satisfies both constraints

**Resolution Options** (in order of preference):

1. **Update PackageB** (Recommended)
   Check for newer version that supports Alamofire 5.8+:
   ```bash
   # Check latest versions
   git ls-remote --tags https://github.com/Example/PackageB

Then update Package.swift:

.package(url: "https://github.com/Example/PackageB", from: "3.0.0")

2. Fork and Patch If no compatible version exists:

   git clone https://github.com/Example/PackageB
   # Update its Package.swift to allow Alamofire 5.8+
   # Push to your fork
   

   .package(url: "https://github.com/YourFork/PackageB", branch: "alamofire-5.8")
   

3. Pin to Specific Versions Force specific version of shared dependency:

   .package(url: "https://github.com/Alamofire/Alamofire", exact: "5.4.4")
   

   ⚠️ May break features in PackageA

HIGH Issues

Swift 6 Language Mode Mismatch

Package: OldPackage v1.2.3 Issue: Compiled with Swift 5 mode, your target uses Swift 6

Resolution:

// Add to target's swiftSettings
.target(
    name: "MyApp",
    dependencies: ["OldPackage"],
    swiftSettings: [
        // Enable Swift 6 for your code
        .swiftLanguageMode(.v6),
        // OldPackage will use its own mode
    ]
)

Or use gradual migration:

.enableExperimentalFeature("StrictConcurrency")

Resolution Commands

# Step 1: Clean SPM cache
rm -rf .build
rm -rf ~/Library/Caches/org.swift.swiftpm

# Step 2: Reset Package.resolved
rm Package.resolved

# Step 3: Resolve fresh
swift package resolve

# Step 4: Verify
swift build

# If in Xcode project
# File → Packages → Reset Package Caches
# File → Packages → Resolve Package Versions

Dependency Graph

MyApp
├── Alamofire 5.8.0
├── PackageA 2.0.0
│   └── Alamofire 5.8.0 ✓ (matches)
└── PackageB 3.1.0
    └── Alamofire 5.8.0 ✓ (matches)

Verification

After resolution:

# Clean build
rm -rf .build && swift build

# Run tests
swift test

# Check for warnings
swift build 2>&1 | grep -i warning

## When No Issues Found

```markdown
# SPM Dependency Analysis

## Summary
No conflicts detected.

## Package Health
- ✅ All version constraints satisfied
- ✅ No duplicate dependencies
- ✅ Swift tools version compatible
- ✅ Platform requirements met

## Dependency Graph
[Show clean dependency tree]

## Recommendations
- Consider updating packages:
  ```bash
  swift package update

• Check for security advisories:

  swift package diagnose-api-breaking-changes
  

## Common SPM Commands Reference

```bash
# Resolve dependencies
swift package resolve

# Update all packages
swift package update

# Update specific package
swift package update PackageName

# Show dependencies
swift package show-dependencies
swift package show-dependencies --format json

# Clean build
rm -rf .build

# Reset SPM cache (nuclear option)
rm -rf ~/Library/Caches/org.swift.swiftpm
rm -rf .build
rm Package.resolved
swift package resolve

# Diagnose issues
swift package diagnose-api-breaking-changes

# Edit package locally (for debugging)
swift package edit PackageName
swift package unedit PackageName

Xcode-Specific Commands

# In Xcode:
File → Packages → Reset Package Caches
File → Packages → Resolve Package Versions
File → Packages → Update to Latest Package Versions

# Trust macro package:
Product → Swift Packages → Trust & Enable Package Plugin