Migrate FileHeaderRule from SourceKit to SwiftSyntax (#6112)

## Summary

Convert FileHeaderRule to use SwiftSyntax instead of SourceKit for
improved performance and better handling of file header comments,
shebangs, and doc comments.

## Key Technical Improvements

- **Enhanced shebang support** properly skipping past `#!/usr/bin/env swift` lines
- **Better comment type discrimination** excluding doc comments from header analysis
- **Accurate position calculation** converting between UTF-8 and UTF-16 offsets for regex matching
- **Improved trivia traversal** for comprehensive header comment collection
- **SwiftLint command filtering** to exclude directive comments from header content

## Migration Details

- Replaced `OptInRule` with `@SwiftSyntaxRule(optIn: true)` annotation
- Implemented `ViolationsSyntaxVisitor` pattern for file-level analysis
- Added logic to start header collection after shebang.endPosition if present
- Distinguished between regular comments and doc comments (///, /** */)
- Maintained UTF-16 offset calculations for NSRegularExpression compatibility
- Added `skipDisableCommandTests: true` for SwiftSyntax disable command behavior
- Removed unnecessary SourceKittenFramework import

Author: jpsim

CHANGELOG.md

@@ -32,6 +32,7 @@
   * `accessibility_trait_for_button`
   * `closure_end_indentation`
   * `expiring_todo`
+  * `file_header`
   * `file_length`
   * `line_length`
   * `vertical_whitespace`

Source/SwiftLintBuiltInRules/Rules/RuleConfigurations/FileHeaderConfiguration.swift

@@ -1,5 +1,4 @@
 import Foundation
-import SourceKittenFramework
 import SwiftLintCore
 
 struct FileHeaderConfiguration: SeverityBasedRuleConfiguration {

Source/SwiftLintBuiltInRules/Rules/Style/FileHeaderRule.swift

@@ -1,7 +1,9 @@
 import Foundation
 import SourceKittenFramework
+import SwiftSyntax
 
-struct FileHeaderRule: OptInRule {
+@SwiftSyntaxRule(optIn: true)
+struct FileHeaderRule: Rule {
     var configuration = FileHeaderConfiguration()
 
     static let description = RuleDescription(
@@ -30,80 +32,200 @@ struct FileHeaderRule: OptInRule {
             """),
         ].skipWrappingInCommentTests()
     )
+}
+
+private struct ProcessTriviaResult {
+    let foundNonComment: Bool
+}
+
+private extension FileHeaderRule {
+    final class Visitor: ViolationsSyntaxVisitor<ConfigurationType> {
+        override func visit(_ node: SourceFileSyntax) -> SyntaxVisitorContinueKind {
+            let headerRange = collectHeaderComments(from: node)
+
+            let requiredRegex = configuration.requiredRegex(for: file)
+
+            // If no header comments found
+            guard let headerRange else {
+                if requiredRegex != nil {
+                    let violationPosition = node.shebang?.endPosition ?? node.position
+                    violations.append(ReasonedRuleViolation(
+                        position: violationPosition,
+                        reason: requiredReason()
+                    ))
+                }
+                return .skipChildren
+            }
+
+            // Extract header content
+            guard let headerContent = extractHeaderContent(from: headerRange) else {
+                return .skipChildren
+            }
 
-    func validate(file: SwiftLintFile) -> [StyleViolation] {
-        var firstToken: SwiftLintSyntaxToken?
-        var lastToken: SwiftLintSyntaxToken?
-        var firstNonCommentToken: SwiftLintSyntaxToken?
-
-        for token in file.syntaxTokensByLines.lazy.joined() {
-            guard let kind = token.kind, kind.isFileHeaderKind else {
-                // found a token that is not a comment, which means it's not the top of the file
-                // so we can just skip the remaining tokens
-                firstNonCommentToken = token
-                break
+            // Check patterns
+            checkForbiddenPattern(in: headerContent, startingAt: headerRange.start)
+            checkRequiredPattern(requiredRegex, in: headerContent, startingAt: headerRange.start)
+
+            return .skipChildren
+        }
+
+        private func collectHeaderComments(
+            from node: SourceFileSyntax
+        ) -> (start: AbsolutePosition, end: AbsolutePosition)? {
+            var firstHeaderCommentStart: AbsolutePosition?
+            var lastHeaderCommentEnd: AbsolutePosition?
+
+            // Skip past shebang if present
+            var currentPosition = node.position
+            if let shebang = node.shebang {
+                currentPosition = shebang.endPosition
             }
 
-            // skip SwiftLint commands
-            guard !isSwiftLintCommand(token: token, file: file) else {
-                continue
+            // Collect header comments from tokens' trivia
+            for token in node.tokens(viewMode: .sourceAccurate) {
+                // Skip tokens before the start position (e.g., shebang)
+                if token.endPosition <= currentPosition {
+                    continue
+                }
+
+                let triviaResult = processTrivia(
+                    token.leadingTrivia,
+                    startingAt: &currentPosition,
+                    firstStart: &firstHeaderCommentStart,
+                    lastEnd: &lastHeaderCommentEnd
+                )
+
+                if triviaResult.foundNonComment || token.tokenKind != .endOfFile {
+                    break
+                }
+
+                // Update current position past the token
+                currentPosition = token.endPositionBeforeTrailingTrivia
+
+                // Process trailing trivia if it's EOF
+                if token.tokenKind == .endOfFile {
+                    _ = processTrivia(token.trailingTrivia,
+                                      startingAt: &currentPosition,
+                                      firstStart: &firstHeaderCommentStart,
+                                      lastEnd: &lastHeaderCommentEnd)
+                }
             }
 
-            if firstToken == nil {
-                firstToken = token
+            guard let start = firstHeaderCommentStart,
+                  let end = lastHeaderCommentEnd,
+                  start < end else {
+                return nil
             }
-            lastToken = token
+
+            return (start: start, end: end)
         }
 
-        let requiredRegex = configuration.requiredRegex(for: file)
+        private func processTrivia(_ trivia: Trivia,
+                                   startingAt currentPosition: inout AbsolutePosition,
+                                   firstStart: inout AbsolutePosition?,
+                                   lastEnd: inout AbsolutePosition?) -> ProcessTriviaResult {
+            for piece in trivia {
+                let pieceStart = currentPosition
+                currentPosition += piece.sourceLength
 
-        var violationsOffsets = [Int]()
-        if let firstToken, let lastToken {
-            let start = firstToken.offset
-            let length = lastToken.offset + lastToken.length - firstToken.offset
-            let byteRange = ByteRange(location: start, length: length)
-            guard let range = file.stringView.byteRangeToNSRange(byteRange) else {
-                return []
+                if isSwiftLintCommand(piece: piece) {
+                    continue
+                }
+
+                if piece.isComment && !piece.isDocComment {
+                    if firstStart == nil {
+                        firstStart = pieceStart
+                    }
+                    lastEnd = currentPosition
+                } else if !piece.isWhitespace {
+                    return ProcessTriviaResult(foundNonComment: true)
+                }
             }
+            return ProcessTriviaResult(foundNonComment: false)
+        }
+
+        private func extractHeaderContent(from range: (start: AbsolutePosition, end: AbsolutePosition)) -> String? {
+            let headerByteRange = ByteRange(
+                location: ByteCount(range.start.utf8Offset),
+                length: ByteCount(range.end.utf8Offset - range.start.utf8Offset)
+            )
+
+            return file.stringView.substringWithByteRange(headerByteRange)
+        }
 
-            if let regex = configuration.forbiddenRegex(for: file),
-                let firstMatch = regex.matches(in: file.contents, options: [], range: range).first {
-                violationsOffsets.append(firstMatch.range.location)
+        private func checkForbiddenPattern(in headerContent: String, startingAt headerStart: AbsolutePosition) {
+            guard
+                let forbiddenRegex = configuration.forbiddenRegex(for: file),
+                let firstMatch = forbiddenRegex.firstMatch(
+                    in: headerContent,
+                    options: [],
+                    range: headerContent.fullNSRange
+                )
+            else {
+                return
             }
 
-            if let regex = requiredRegex,
-                case let matches = regex.matches(in: file.contents, options: [], range: range),
-                matches.isEmpty {
-                violationsOffsets.append(file.stringView.location(fromByteOffset: start))
+            // Calculate violation position
+            let matchLocationUTF16 = firstMatch.range.location
+            let headerPrefix = String(headerContent.utf16.prefix(matchLocationUTF16)) ?? ""
+            let utf8OffsetInHeader = headerPrefix.utf8.count
+            let violationPosition = AbsolutePosition(utf8Offset: headerStart.utf8Offset + utf8OffsetInHeader)
+
+            violations.append(ReasonedRuleViolation(
+                position: violationPosition,
+                reason: forbiddenReason()
+            ))
+        }
+
+        private func checkRequiredPattern(_ requiredRegex: NSRegularExpression?,
+                                          in headerContent: String,
+                                          startingAt headerStart: AbsolutePosition) {
+            guard
+                let requiredRegex,
+                requiredRegex.firstMatch(in: headerContent, options: [], range: headerContent.fullNSRange) == nil
+            else {
+                return
             }
-        } else if requiredRegex != nil {
-            let location = firstNonCommentToken.map {
-                Location(file: file, byteOffset: $0.offset)
-            } ?? Location(file: file.path, line: 1)
-            return [makeViolation(at: location)]
+
+            violations.append(ReasonedRuleViolation(
+                position: headerStart,
+                reason: requiredReason()
+            ))
         }
 
-        return violationsOffsets.map { makeViolation(at: Location(file: file, characterOffset: $0)) }
-    }
+        private func isSwiftLintCommand(piece: TriviaPiece) -> Bool {
+            guard let text = piece.commentText else { return false }
+            return text.contains("swiftlint:")
+        }
 
-    private func isSwiftLintCommand(token: SwiftLintSyntaxToken, file: SwiftLintFile) -> Bool {
-        guard let range = file.stringView.byteRangeToNSRange(token.range) else {
-            return false
+        private func forbiddenReason() -> String {
+            "Header comments should be consistent with project patterns"
         }
 
-        return file.commands(in: range).isNotEmpty
+        private func requiredReason() -> String {
+            "Header comments should be consistent with project patterns"
+        }
     }
+}
 
-    private func makeViolation(at location: Location) -> StyleViolation {
-        StyleViolation(ruleDescription: Self.description,
-                       severity: configuration.severityConfiguration.severity,
-                       location: location,
-                       reason: "Header comments should be consistent with project patterns")
+// Helper extensions
+private extension TriviaPiece {
+    var isDocComment: Bool {
+        switch self {
+        case .docLineComment, .docBlockComment:
+            return true
+        default:
+            return false
+        }
     }
-}
 
-private extension SyntaxKind {
-    var isFileHeaderKind: Bool {
-        self == .comment || self == .commentURL
+    var commentText: String? {
+        switch self {
+        case .lineComment(let text), .blockComment(let text),
+             .docLineComment(let text), .docBlockComment(let text):
+            return text
+        default:
+            return nil
+        }
     }
 }

Tests/BuiltInRulesTests/FileHeaderRuleTests.swift

@@ -5,12 +5,6 @@ import XCTest
 private let fixturesDirectory = "\(TestResources.path())/FileHeaderRuleFixtures"
 
 final class FileHeaderRuleTests: SwiftLintTestCase {
-    override func invokeTest() {
-        CurrentRule.$allowSourceKitRequestWithoutRule.withValue(true) {
-            super.invokeTest()
-        }
-    }
-
     private func validate(fileName: String, using configuration: Any) throws -> [StyleViolation] {
         let file = SwiftLintFile(path: fixturesDirectory.stringByAppendingPathComponent(fileName))!
         let rule = try FileHeaderRule(configuration: configuration)
@@ -39,7 +33,8 @@ final class FileHeaderRuleTests: SwiftLintTestCase {
 
         verifyRule(description, ruleConfiguration: ["required_string": "**Header"],
                    stringDoesntViolate: false, skipCommentTests: true,
-                   testMultiByteOffsets: false, testShebang: false)
+                   skipDisableCommandTests: true, testMultiByteOffsets: false,
+                   testShebang: false)
     }
 
     func testFileHeaderWithRequiredPattern() {