Support file-level ignore directive for specific rules

Author: TTOzzi

Documentation/IgnoringSource.md

@@ -77,6 +77,22 @@ var a = foo+bar+baz
 These ignore comments also apply to all children of the node, identical to the
 behavior of the formatting ignore directive described above.
 
+You can also disable specific source transforming rules for an entire file
+by using the file-level ignore directive with a list of rule names. For example:
+
+```swift
+// swift-format-ignore-file: DoNotUseSemicolons, FullyIndirectEnum
+import Zoo
+import Arrays
+
+struct Foo {
+  func foo() { bar();baz(); }
+}
+```
+In this case, only the DoNotUseSemicolons and FullyIndirectEnum rules are disabled
+throughout the file, while all other formatting rules (such as line breaking and 
+indentation) remain active.
+
 ## Understanding Nodes
 
 `swift-format` parses Swift into an abstract syntax tree, where each element of

Sources/SwiftFormat/Core/RuleMask.swift

@@ -35,6 +35,16 @@ import SwiftSyntax
 ///   2. |  let a = 123
 ///   Ignores `RuleName` and `OtherRuleName` for line 2.
 ///
+///   1. |  // swift-format-ignore-file: RuleName
+///   2. |  let a = 123
+///   3. | class Foo { }
+///   Ignores `RuleName` for the entire file (lines 2-3).
+///
+///   1. |  // swift-format-ignore-file: RuleName, OtherRuleName
+///   2. |  let a = 123
+///   3. | class Foo { }
+///   Ignores `RuleName` and `OtherRuleName` for the entire file (lines 2-3).
+///
 /// The rules themselves reference RuleMask to see if it is disabled for the line it is currently
 /// examining.
 @_spi(Testing)
@@ -115,7 +125,7 @@ fileprivate class RuleStatusCollectionVisitor: SyntaxVisitor {
   private let ignoreRegex: NSRegularExpression
 
   /// Regex pattern to match an ignore comment that applies to an entire file.
-  private let ignoreFilePattern = #"^\s*\/\/\s*swift-format-ignore-file$"#
+  private let ignoreFilePattern = #"^\s*\/\/\s*swift-format-ignore-file((:\s+(([A-z0-9]+[,\s]*)+))?$|\s+$)"#
 
   /// Rule ignore regex object.
   private let ignoreFileRegex: NSRegularExpression
@@ -140,40 +150,28 @@ fileprivate class RuleStatusCollectionVisitor: SyntaxVisitor {
     guard let firstToken = node.firstToken(viewMode: .sourceAccurate) else {
       return .visitChildren
     }
-    let comments = loneLineComments(in: firstToken.leadingTrivia, isFirstToken: true)
-    var foundIgnoreFileComment = false
-    for comment in comments {
-      let range = NSRange(comment.startIndex..<comment.endIndex, in: comment)
-      if ignoreFileRegex.firstMatch(in: comment, options: [], range: range) != nil {
-        foundIgnoreFileComment = true
-        break
-      }
-    }
-    guard foundIgnoreFileComment else {
-      return .visitChildren
-    }
-
     let sourceRange = node.sourceRange(
       converter: sourceLocationConverter,
       afterLeadingTrivia: false,
       afterTrailingTrivia: true
     )
-    allRulesIgnoredRanges.append(sourceRange)
-    return .skipChildren
+    return appendRuleStatusDirectives(from: firstToken, of: sourceRange, using: ignoreFileRegex)
   }
 
   override func visit(_ node: CodeBlockItemSyntax) -> SyntaxVisitorContinueKind {
     guard let firstToken = node.firstToken(viewMode: .sourceAccurate) else {
       return .visitChildren
     }
-    return appendRuleStatusDirectives(from: firstToken, of: Syntax(node))
+    let sourceRange = node.sourceRange(converter: sourceLocationConverter)
+    return appendRuleStatusDirectives(from: firstToken, of: sourceRange, using: ignoreRegex)
   }
 
   override func visit(_ node: MemberBlockItemSyntax) -> SyntaxVisitorContinueKind {
     guard let firstToken = node.firstToken(viewMode: .sourceAccurate) else {
       return .visitChildren
     }
-    return appendRuleStatusDirectives(from: firstToken, of: Syntax(node))
+    let sourceRange = node.sourceRange(converter: sourceLocationConverter)
+    return appendRuleStatusDirectives(from: firstToken, of: sourceRange, using: ignoreRegex)
   }
 
   // MARK: - Helper Methods
@@ -183,17 +181,19 @@ fileprivate class RuleStatusCollectionVisitor: SyntaxVisitor {
   ///
   /// - Parameters:
   ///   - token: A token that may have comments that modify the status of rules.
-  ///   - node: The node to which the token belongs.
+  ///   - sourceRange: The range covering the node to which `token` belongs. If an ignore directive
+  ///     is found among the comments, this entire range is used to ignore the specified rules.
+  ///   - regex: The regular expression used to detect ignore directives.
   private func appendRuleStatusDirectives(
     from token: TokenSyntax,
-    of node: Syntax
+    of sourceRange: SourceRange,
+    using regex: NSRegularExpression
   ) -> SyntaxVisitorContinueKind {
     let isFirstInFile = token.previousToken(viewMode: .sourceAccurate) == nil
-    let matches = loneLineComments(in: token.leadingTrivia, isFirstToken: isFirstInFile)
-      .compactMap(ruleStatusDirectiveMatch)
-    let sourceRange = node.sourceRange(converter: sourceLocationConverter)
-    for match in matches {
-      switch match {
+    let comments = loneLineComments(in: token.leadingTrivia, isFirstToken: isFirstInFile)
+    for comment in comments {
+      guard let matchResult = ruleStatusDirectiveMatch(in: comment, using: regex) else { continue }
+      switch matchResult {
       case .all:
         allRulesIgnoredRanges.append(sourceRange)
 
@@ -210,9 +210,12 @@ fileprivate class RuleStatusCollectionVisitor: SyntaxVisitor {
 
   /// Checks if a comment containing the given text matches a rule status directive. When it does
   /// match, its contents (e.g. list of rule names) are returned.
-  private func ruleStatusDirectiveMatch(in text: String) -> RuleStatusDirectiveMatch? {
+  private func ruleStatusDirectiveMatch(
+    in text: String,
+    using regex: NSRegularExpression
+  ) -> RuleStatusDirectiveMatch? {
     let textRange = NSRange(text.startIndex..<text.endIndex, in: text)
-    guard let match = ignoreRegex.firstMatch(in: text, options: [], range: textRange) else {
+    guard let match = regex.firstMatch(in: text, options: [], range: textRange) else {
       return nil
     }
     guard match.numberOfRanges == 5 else { return .all }

Tests/SwiftFormatTests/Core/RuleMaskTests.swift

@@ -230,4 +230,175 @@ final class RuleMaskTests: XCTestCase {
       XCTAssertEqual(mask.ruleState("rule1", at: location(ofLine: i)), .default)
     }
   }
+
+  func testSingleRuleWholeFileIgnore() {
+    let text =
+      """
+      // This file has important contents.
+      // swift-format-ignore-file: rule1
+      // Everything in this file is ignored.
+
+      let a = 5
+      let b = 4
+
+      class Foo {
+        let member1 = 0
+        func foo() {
+          baz()
+        }
+      }
+
+      struct Baz {
+      }
+      """
+
+    let mask = createMask(sourceText: text)
+
+    let lineCount = text.split(separator: "\n").count
+    for i in 0..<lineCount {
+      XCTAssertEqual(mask.ruleState("rule1", at: location(ofLine: i)), .disabled)
+      XCTAssertEqual(mask.ruleState("rule2", at: location(ofLine: i)), .default)
+    }
+  }
+
+  func testMultipleRulesWholeFileIgnore() {
+    let text =
+      """
+      // This file has important contents.
+      // swift-format-ignore-file: rule1, rule2, rule3
+      // Everything in this file is ignored.
+
+      let a = 5
+      let b = 4
+
+      class Foo {
+        let member1 = 0
+        func foo() {
+          baz()
+        }
+      }
+
+      struct Baz {
+      }
+      """
+
+    let mask = createMask(sourceText: text)
+
+    let lineCount = text.split(separator: "\n").count
+    for i in 0..<lineCount {
+      XCTAssertEqual(mask.ruleState("rule1", at: location(ofLine: i)), .disabled)
+      XCTAssertEqual(mask.ruleState("rule2", at: location(ofLine: i)), .disabled)
+      XCTAssertEqual(mask.ruleState("rule3", at: location(ofLine: i)), .disabled)
+      XCTAssertEqual(mask.ruleState("rule4", at: location(ofLine: i)), .default)
+    }
+  }
+
+  func testFileAndLineIgnoresMixed() {
+    let text =
+      """
+      // This file has important contents.
+      // swift-format-ignore-file: rule1, rule2
+      // Everything in this file is ignored.
+
+      let a = 5
+      // swift-format-ignore: rule3
+      let b = 4
+
+      class Foo {
+        // swift-format-ignore: rule3, rule4
+        let member1 = 0
+
+        func foo() {
+          baz()
+        }
+      }
+
+      struct Baz {
+      }
+      """
+
+    let mask = createMask(sourceText: text)
+
+    let lineCount = text.split(separator: "\n").count
+    for i in 0..<lineCount {
+      XCTAssertEqual(mask.ruleState("rule1", at: location(ofLine: i)), .disabled)
+      XCTAssertEqual(mask.ruleState("rule2", at: location(ofLine: i)), .disabled)
+      if i == 7 {
+        XCTAssertEqual(mask.ruleState("rule3", at: location(ofLine: i)), .disabled)
+        XCTAssertEqual(mask.ruleState("rule4", at: location(ofLine: i)), .default)
+      } else if i == 11 {
+        XCTAssertEqual(mask.ruleState("rule3", at: location(ofLine: i, column: 3)), .disabled)
+        XCTAssertEqual(mask.ruleState("rule4", at: location(ofLine: i, column: 3)), .disabled)
+      } else {
+        XCTAssertEqual(mask.ruleState("rule3", at: location(ofLine: i)), .default)
+        XCTAssertEqual(mask.ruleState("rule4", at: location(ofLine: i)), .default)
+      }
+    }
+  }
+
+  func testMultipleSubsetFileIgnoreDirectives() {
+    let text =
+      """
+      // This file has important contents.
+      // swift-format-ignore-file: rule1
+      // swift-format-ignore-file: rule2
+      // Everything in this file is ignored.
+
+      let a = 5
+      let b = 4
+
+      class Foo {
+        let member1 = 0
+
+        func foo() {
+          baz()
+        }
+      }
+
+      struct Baz {
+      }
+      """
+
+    let mask = createMask(sourceText: text)
+
+    let lineCount = text.split(separator: "\n").count
+    for i in 0..<lineCount {
+      XCTAssertEqual(mask.ruleState("rule1", at: location(ofLine: i)), .disabled)
+      XCTAssertEqual(mask.ruleState("rule2", at: location(ofLine: i)), .disabled)
+      XCTAssertEqual(mask.ruleState("rule3", at: location(ofLine: i)), .default)
+    }
+  }
+
+  func testSubsetAndAllFileIgnoreDirectives() {
+    let text =
+      """
+      // This file has important contents.
+      // swift-format-ignore-file: rule1
+      // swift-format-ignore-file
+      // Everything in this file is ignored.
+
+      let a = 5
+      let b = 4
+
+      class Foo {
+        let member1 = 0
+
+        func foo() {
+          baz()
+        }
+      }
+
+      struct Baz {
+      }
+      """
+
+    let mask = createMask(sourceText: text)
+
+    let lineCount = text.split(separator: "\n").count
+    for i in 0..<lineCount {
+      XCTAssertEqual(mask.ruleState("rule1", at: location(ofLine: i)), .disabled)
+      XCTAssertEqual(mask.ruleState("rule2", at: location(ofLine: i)), .disabled)
+      XCTAssertEqual(mask.ruleState("rule3", at: location(ofLine: i)), .disabled)
+    }
+  }
 }