Add scan flow MVP and local Axiom skill workspace
This snapshot establishes the camera-to-result recognition flow and related tests while checking in the project skill/docs assets required for the configured local tooling.
This commit is contained in:
Matthias
450
.claude/skills/axiom-resolve-spm/SKILL.md
Normal file
450
.claude/skills/axiom-resolve-spm/SKILL.md
Normal file
@@ -0,0 +1,450 @@
|
||||
---
|
||||
name: axiom-resolve-spm
|
||||
description: 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.
|
||||
license: MIT
|
||||
disable-model-invocation: 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**:
|
||||
```bash
|
||||
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
|
||||
|
||||
```swift
|
||||
// ❌ 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**:
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```swift
|
||||
// ❌ 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**:
|
||||
```bash
|
||||
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
|
||||
|
||||
```swift
|
||||
// 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**:
|
||||
```bash
|
||||
# Check if Package.resolved is in sync
|
||||
swift package resolve 2>&1
|
||||
|
||||
# Verify all pins are valid
|
||||
swift package show-dependencies
|
||||
```
|
||||
|
||||
**Resolution Strategy**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
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
|
||||
|
||||
```swift
|
||||
// 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
|
||||
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
swift package resolve 2>&1 | grep -i "could not be resolved\|conflict\|incompatible"
|
||||
```
|
||||
|
||||
**Build failures**:
|
||||
```bash
|
||||
swift build 2>&1 | head -50
|
||||
```
|
||||
|
||||
### Step 3: Analyze Dependency Graph
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```markdown
|
||||
# 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:
|
||||
```swift
|
||||
.package(url: "https://github.com/Example/PackageB", from: "3.0.0")
|
||||
```
|
||||
|
||||
2. **Fork and Patch**
|
||||
If no compatible version exists:
|
||||
```bash
|
||||
git clone https://github.com/Example/PackageB
|
||||
# Update its Package.swift to allow Alamofire 5.8+
|
||||
# Push to your fork
|
||||
```
|
||||
```swift
|
||||
.package(url: "https://github.com/YourFork/PackageB", branch: "alamofire-5.8")
|
||||
```
|
||||
|
||||
3. **Pin to Specific Versions**
|
||||
Force specific version of shared dependency:
|
||||
```swift
|
||||
.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**:
|
||||
```swift
|
||||
// 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:
|
||||
```swift
|
||||
.enableExperimentalFeature("StrictConcurrency")
|
||||
```
|
||||
|
||||
## Resolution Commands
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user