Migrate Custom Rules from SourceKit to SwiftSyntax

**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.

Author: jpsim

CHANGELOG.md

@@ -11,6 +11,14 @@
 * SwiftLint now requires macOS 13 or higher to run.  
   [JP Simard](https://github.com/jpsim)
 
+* Custom rules now default to SwiftSyntax mode for pattern matching instead of SourceKit.
+  This may result in subtle behavioral differences. While performance is significantly improved,
+  rules that rely on specific SourceKit behaviors may need adjustment. Users can temporarily
+  revert to the legacy SourceKit behavior by setting `default_execution_mode: sourcekit` in
+  their custom rules configuration or `execution_mode: sourcekit` for individual rules.
+  The SourceKit mode is deprecated and will be removed in a future version.  
+  [JP Simard](https://github.com/jpsim)
+
 ### Experimental
 
 * None.

Source/SwiftLintCore/Extensions/StringView+SwiftLint.swift

@@ -1,3 +1,4 @@
+import Foundation
 import SourceKittenFramework
 
 public extension StringView {
@@ -12,4 +13,17 @@ public extension StringView {
         }
         return lines[Int(line) - 1].byteRange.location + ByteCount(bytePosition - 1)
     }
+
+    /// Matches a pattern in the string view and returns ranges for the specified capture group.
+    /// This method does not use SourceKit and is suitable for SwiftSyntax mode.
+    /// - Parameters:
+    ///   - pattern: The regular expression pattern to match.
+    ///   - captureGroup: The capture group index to extract (0 for the full match).
+    /// - Returns: An array of NSRange objects for the matched capture groups.
+    func match(pattern: String, captureGroup: Int = 0) -> [NSRange] {
+        regex(pattern).matches(in: self).compactMap { match in
+            let range = match.range(at: captureGroup)
+            return range.location != NSNotFound ? range : nil
+        }
+    }
 }

Source/SwiftLintFramework/Rules/CustomRules.swift

@@ -1,4 +1,5 @@
 import Foundation
+import SourceKittenFramework
 
 // MARK: - CustomRulesConfiguration
 
@@ -103,7 +104,49 @@ struct CustomRules: Rule, CacheDescriptionProvider, ConditionallySourceKitFree {
             let pattern = configuration.regex.pattern
             let captureGroup = configuration.captureGroup
             let excludingKinds = configuration.excludedMatchKinds
-            return file.match(pattern: pattern, excludingSyntaxKinds: excludingKinds, captureGroup: captureGroup).map({
+
+            // Determine effective execution mode (defaults to swiftsyntax if not specified)
+            let effectiveMode = configuration.executionMode == .default
+                ? (self.configuration.defaultExecutionMode ?? .swiftsyntax)
+                : configuration.executionMode
+            let needsKindMatching = !excludingKinds.isEmpty
+
+            let matches: [NSRange]
+            if effectiveMode == .swiftsyntax {
+                if needsKindMatching {
+                    // SwiftSyntax mode WITH kind filtering
+                    // CRITICAL: This path must not trigger any SourceKit requests
+                    guard let bridgedTokens = file.swiftSyntaxDerivedSourceKittenTokens else {
+                        // Log error/warning: Bridging failed
+                        queuedPrintError(
+                            "Warning: SwiftSyntax bridging failed for custom rule '\(configuration.identifier)'"
+                        )
+                        return []
+                    }
+                    let syntaxMapFromBridgedTokens = SwiftLintSyntaxMap(
+                        value: SyntaxMap(tokens: bridgedTokens.map(\.value))
+                    )
+
+                    // Use the performMatchingWithSyntaxMap helper that operates on stringView and syntaxMap ONLY
+                    matches = performMatchingWithSyntaxMap(
+                        stringView: file.stringView,
+                        syntaxMap: syntaxMapFromBridgedTokens,
+                        pattern: pattern,
+                        excludingSyntaxKinds: excludingKinds,
+                        captureGroup: captureGroup
+                    )
+                } else {
+                    // SwiftSyntax mode WITHOUT kind filtering
+                    // This path must not trigger any SourceKit requests
+                    matches = file.stringView.match(pattern: pattern, captureGroup: captureGroup)
+                }
+            } else {
+                // SourceKit mode
+                // SourceKit calls ARE EXPECTED AND PERMITTED here because CustomRules is not SourceKitFreeRule
+                matches = file.match(pattern: pattern, excludingSyntaxKinds: excludingKinds, captureGroup: captureGroup)
+            }
+
+            return matches.map({
                 StyleViolation(ruleDescription: configuration.description,
                                severity: configuration.severity,
                                location: Location(file: file, characterOffset: $0.location),
@@ -134,3 +177,42 @@ struct CustomRules: Rule, CacheDescriptionProvider, ConditionallySourceKitFree {
             && !region.disabledRuleIdentifiers.contains(.all)
     }
 }
+
+// MARK: - Helpers
+
+private func performMatchingWithSyntaxMap(
+    stringView: StringView,
+    syntaxMap: SwiftLintSyntaxMap,
+    pattern: String,
+    excludingSyntaxKinds: Set<SyntaxKind>,
+    captureGroup: Int
+) -> [NSRange] {
+    // This helper method must not access any part of SwiftLintFile that could trigger SourceKit requests
+    // It operates only on the provided stringView and syntaxMap
+
+    let regex = regex(pattern)
+    let range = stringView.range
+    let matches = regex.matches(in: stringView, options: [], range: range)
+
+    return matches.compactMap { match in
+        let matchRange = match.range(at: captureGroup)
+
+        // Get tokens in the match range
+        guard let byteRange = stringView.NSRangeToByteRange(
+            start: matchRange.location,
+            length: matchRange.length
+        ) else {
+            return nil
+        }
+
+        let tokensInRange = syntaxMap.tokens(inByteRange: byteRange)
+        let kindsInRange = Set(tokensInRange.kinds)
+
+        // Check if any excluded kinds are present
+        if excludingSyntaxKinds.isDisjoint(with: kindsInRange) {
+            return matchRange
+        }
+
+        return nil
+    }
+}

Tests/FrameworkTests/CustomRulesTests.swift

@@ -11,12 +11,6 @@ final class CustomRulesTests: SwiftLintTestCase {
 
     private var testFile: SwiftLintFile { SwiftLintFile(path: "\(TestResources.path())/test.txt")! }
 
-    override func invokeTest() {
-        CurrentRule.$allowSourceKitRequestWithoutRule.withValue(true) {
-            super.invokeTest()
-        }
-    }
-
     func testCustomRuleConfigurationSetsCorrectlyWithMatchKinds() {
         let configDict = [
             "my_custom_rule": [