Migrate Custom Rules from SourceKit to SwiftSyntax #6129
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Generated by 🚫 Danger |
jpsim
force-pushed
the
migrate-custom-rules-from-sourcekit-to-swiftsyntax
branch
2 times, most recently
from
601c496 to
8fa1fb6
Compare
jpsim
force-pushed
the
migrate-custom-rules-from-sourcekit-to-swiftsyntax
branch
from
8fa1fb6 to
27a6b2a
Compare
Naveen-C-Ramachandrappa
approved these changes
Jun 24, 2025
**Breaking Change**: Custom rules now default to SwiftSyntax mode for pattern matching.
This provides significant performance improvements but may have subtle behavioral differences
from the previous SourceKit implementation. Users should test their custom rules and adjust
as needed. A temporary `sourcekit` mode is available for rules that cannot be migrated yet.
## Breaking Change Details
- **New Default**: Custom rules now use `swiftsyntax` mode by default
- **Legacy Option**: Set `mode: sourcekit` or `default_execution_mode: sourcekit` to
restore previous behavior temporarily
- **Action Required**: Test your custom rules after upgrading and migrate to SwiftSyntax
mode where possible
## Configuration
Control execution mode at two levels:
```yaml
custom_rules:
# To restore previous behavior for all rules (temporary):
default_execution_mode: sourcekit
my_rule:
regex: "pattern"
# Defaults to swiftsyntax now
legacy_rule:
regex: "pattern"
mode: sourcekit # Use legacy mode for specific rules
```
## Why This Change?
- **Performance**: SwiftSyntax mode eliminates SourceKit process overhead
- **Reliability**: No more SourceKit crashes or hangs
- **Future-Proof**: SwiftLint is migrating away from SourceKit entirely
## Migration Guide
1. **Test First**: Run your existing custom rules and check for differences
2. **Adjust Rules**: Most rules should work identically in SwiftSyntax mode
3. **Use Legacy Mode**: For rules that must maintain exact SourceKit behavior,
set `mode: sourcekit` temporarily
4. **Report Issues**: Help us improve SwiftSyntax mode by reporting incompatibilities
## Technical Implementation
### SwiftSyntaxKindBridge
Enables kind filtering (`match_kinds`/`excluded_match_kinds`) without SourceKit:
- Maps SwiftSyntax classifications to SourceKit syntax kinds
- Covers common use cases with best-effort compatibility
- Some edge cases may differ from SourceKit behavior
### ConditionallySourceKitFree Protocol
Allows CustomRules to skip SourceKit initialization when all rules use SwiftSyntax:
- Dramatic performance improvement when SourceKit isn't needed
- Maintains SourceKit availability for legacy rules
## Important Notes
- **Not Full Compatibility**: While we've worked to maintain compatibility, differences
exist. Test thoroughly.
- **Temporary Legacy Support**: The `sourcekit` mode is a temporary measure. Plan to
migrate all rules to SwiftSyntax.
- **Future Deprecation**: SourceKit mode will be removed in a future version.
## Benefits of Migrating
- Faster linting (no SourceKit startup cost)
- Lower memory usage
- Better reliability (no SourceKit crashes)
- Future-proof your configuration
This change represents a major step in SwiftLint's evolution toward a fully SwiftSyntax-based
architecture. We encourage all users to test and migrate their custom rules to the new
SwiftSyntax mode, using the legacy SourceKit mode only as a temporary measure for rules
that cannot yet be migrated.
jpsim
force-pushed
the
migrate-custom-rules-from-sourcekit-to-swiftsyntax
branch
from
27a6b2a to
f281814
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Breaking Change: Custom rules now default to SwiftSyntax mode for pattern matching.
This provides significant performance improvements but may have subtle behavioral differences
from the previous SourceKit implementation. Users should test their custom rules and adjust
as needed. A temporary
sourcekitmode is available for rules that cannot be migrated yet.Breaking Change Details
swiftsyntaxmode by defaultexecution_mode: sourcekitordefault_execution_mode: sourcekittorestore previous behavior temporarily
mode where possible
Configuration
Control execution mode at two levels:
Why This Change?
Migration Guide
set
execution_mode: sourcekittemporarilyTechnical Implementation
SwiftSyntaxKindBridge
Enables kind filtering (
match_kinds/excluded_match_kinds) without SourceKit:ConditionallySourceKitFree Protocol
Allows CustomRules to skip SourceKit initialization when all rules use SwiftSyntax:
Important Notes
exist. Test thoroughly.
sourcekitmode is a temporary measure. Plan tomigrate all rules to SwiftSyntax.
Benefits of Migrating
This change represents a major step in SwiftLint's evolution toward a fully SwiftSyntax-based
architecture. We encourage all users to test and migrate their custom rules to the new
SwiftSyntax mode, using the legacy SourceKit mode only as a temporary measure for rules
that cannot yet be migrated.