fix: Add compile-time warning for disabled CloudKit on Swift 6.3+

[doozMen]

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com

[doozMen]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• ci: Add Swift version matrix for 6.0, 6.2, and 6.3 testing #10
• docs: Add Swift 6.3 compatibility limitations to README #9
• fix: Add compile-time warning for disabled CloudKit on Swift 6.3+ #8 👈 (View in Graphite)
• workaround for compiler crash - no cloudkit for swift 6.3 at the moment #7
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Pull Request Review

Summary

This PR adds a compile-time warning for Swift 6.3+ users to inform them that CloudKit functionality is disabled due to compiler crashes. This is a pragmatic workaround for issue #2.

---

✅ Strengths

1. Appropriate Solution: Using a compile-time #warning is the right approach to inform developers without blocking compilation.

2. Clear Documentation: The warning message is helpful and provides:

   • What the issue is (CloudKit disabled)
   • Why it's happening (compiler crashes)
   • Where to learn more (issue Swift 6.3-dev compiler crashes - workarounds applied #2 link)
   • What to do about it (use Swift 6.2.x)

3. Consistent with Existing Patterns: The use of #if compiler(>=6.3) aligns with the conditional compilation already present in PrimaryKeyMigration.swift.

4. No Breaking Changes: This is purely informational and doesn't break any existing functionality.

---

🔍 Code Quality

File Location: ✅ Good

• Placing the warning in a dedicated file (CloudKitAvailability.swift) in the CloudKit directory is clean and discoverable.

Formatting: ✅ Consistent

• Follows the codebase style (2-space indentation, file header comment)
• Multi-line warning string uses proper Swift string literal formatting

Naming: ✅ Appropriate

• CloudKitAvailability.swift clearly conveys the file's purpose

---

💡 Suggestions for Improvement

1. Consider Version Specificity

The current check uses compiler(>=6.3), but according to PrimaryKeyMigration.swift:1 and PrimaryKeyMigration.swift:14, the actual implementation uses:

• #if !compiler(>=6.3) for the outer guard
• #if !compiler(>=6.2.3) for the feature implementation

Question: Should this warning also trigger for Swift 6.2.3? Based on the comments in PrimaryKeyMigration.swift:5-9, it appears Swift 6.2.3 also has the issue.

Suggestion: Consider updating line 4 to:

#if compiler(>=6.2.3)

2. Enhance Warning Message

Consider adding information about what specific CloudKit features are affected:

#if compiler(>=6.3)
  #warning("""
    CloudKit functionality is disabled on Swift 6.3+ due to compiler crashes.
    
    Affected features:
    - SyncEngine.migratePrimaryKeys() 
    - PrimaryKeyedTable.migratePrimaryKeyToUUID()
    - SelectStatement.find(_:key:)
    
    See https://github.com/doozMen/sqlite-data/issues/2 for details.
    Use Swift 6.2.x if you need CloudKit synchronization features.
    """)
#endif

3. Add File Header Documentation

Consider adding a brief doc comment at the top:

// CloudKitAvailability.swift
// Compile-time warnings for known CloudKit limitations on specific Swift versions

4. Consider Test Coverage

While compile-time warnings can't be tested directly, consider:

• Adding a note in CompileTimeTests.swift that references this file
• Or documenting this in the PR that it's expected behavior for Swift 6.3+

---

🔒 Security Concerns

✅ None - This is purely a compile-time diagnostic.

---

🚀 Performance Considerations

✅ None - Compile-time only, zero runtime impact.

---

🧪 Test Coverage

Current State: No tests added (expected for compile-time warnings)

Observation: The warning will only appear when:

1. CloudKit is available (canImport(CloudKit))
2. CryptoKit is available (canImport(CryptoKit))
3. Swift version is 6.3 or higher

Suggestion: Consider adding a comment in the PR description or code indicating that this has been manually verified with Swift 6.3.

---

🐛 Potential Issues

Minor: Platform Specificity

The warning is only shown when CloudKit is available (Apple platforms). This is correct, but users on Linux/Windows building with Swift 6.3+ won't see the warning even though some CloudKit code is conditionally disabled.

Impact: Low - CloudKit isn't available on those platforms anyway, so it's not a real issue.

---

📝 Documentation

Issue Link: ✅ Correctly references issue #2
Commit Message: ✅ Follows conventional commits format
PR Description: ✅ Includes Claude Code attribution

Suggestion: Consider updating the CloudKit documentation articles to mention this limitation:

• Sources/SQLiteData/Documentation.docc/Articles/CloudKit.md
• Sources/SQLiteData/Documentation.docc/Articles/CloudKitSharing.md

Add a note like:

Note: On Swift 6.2.3+, CloudKit primary key migration features are temporarily disabled due to a compiler bug. See issue #2 for details.

---

✅ Overall Assessment

Verdict: ✅ Approve with minor suggestions

This PR successfully addresses the immediate need to inform developers about the Swift 6.3+ limitation. The implementation is clean, follows existing patterns, and doesn't introduce any breaking changes.

The main improvement would be aligning the version check with the actual affected version (6.2.3 vs 6.3) and potentially enhancing the warning message with more specific details.

---

🎯 Recommendation

Merge Status: Ready to merge after considering the version alignment question (6.2.3 vs 6.3).

Priority: This is a good improvement that helps developer experience, especially as Swift 6.3 becomes more widely adopted.

Great work on addressing this proactively! 🚀