Support an ignore directive to ignore an entire file.

This is intentionally a different ignore directive (`swift-format-ignore-file` instead of `swift-format-ignore`) so that there won't be any confusion if someone wants to ignore formatting on the first node in a file (e.g. ignore the first import) but wants to format the rest of the file. If ignore file used the same comment as ignore a node, users would need to artificially structure their code in a way that avoids putting an ignore on the first node in the file when they want part of the file to be formatted.

Author: dylansturg

Documentation/IgnoringSource.md

@@ -6,6 +6,22 @@ technical limitations of the formatter's implementation. When an ignore comment
 is present, the next ["node"](#understanding-nodes) in the source's AST
 representation is ignored by the formatter.
 
+## Ignore A File
+
+In the event that an entire file cannot be formatted, add a comment that contains 
+`swift-format-ignore-file` at the top of the file and the formatter will leave 
+the file completely unchanged.
+
+```swift
+// swift-format-ignore-file
+import Zoo
+import Arrays
+
+struct Foo {
+  func foo() { bar();baz(); }
+}
+```
+
 ## Ignoring Formatting (aka indentation, line breaks, line length, etc.)
 
 The formatter applies line length to add line breaks and indentation throughout

Sources/SwiftFormatCore/RuleMask.swift

@@ -22,6 +22,11 @@ import SwiftSyntax
 ///   2. |  let a = 123
 ///   Ignores all rules for line 2.
 ///
+///   1. |  // swift-format-ignore-file
+///   2. |  let a = 123
+///   3. | class Foo { }
+///   Ignores all rules for an entire file (lines 2-3).
+///
 ///   1. |  // swift-format-ignore: RuleName
 ///   2. |  let a = 123
 ///   Ignores `RuleName` for line 2.
@@ -108,6 +113,12 @@ fileprivate class RuleStatusCollectionVisitor: SyntaxVisitor {
   /// Rule ignore regex object.
   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$"#
+
+  /// Rule ignore regex object.
+  private let ignoreFileRegex: NSRegularExpression
+
   /// Stores the source ranges in which all rules are ignored.
   var allRulesIgnoredRanges: [SourceRange] = []
 
@@ -116,12 +127,36 @@ fileprivate class RuleStatusCollectionVisitor: SyntaxVisitor {
 
   init(sourceLocationConverter: SourceLocationConverter) {
     ignoreRegex = try! NSRegularExpression(pattern: ignorePattern, options: [])
+    ignoreFileRegex = try! NSRegularExpression(pattern: ignoreFilePattern, options: [])
 
     self.sourceLocationConverter = sourceLocationConverter
   }
 
   // MARK: - Syntax Visitation Methods
 
+  override func visit(_ node: SourceFileSyntax) -> SyntaxVisitorContinueKind {
+    guard let firstToken = node.firstToken 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
+  }
+
   override func visit(_ node: CodeBlockItemSyntax) -> SyntaxVisitorContinueKind {
     guard let firstToken = node.firstToken else {
       return .visitChildren

Sources/SwiftFormatPrettyPrint/TokenStreamCreator.swift

@@ -1143,6 +1143,10 @@ fileprivate final class TokenStreamCreator: SyntaxVisitor {
   }
 
   override func visit(_ node: SourceFileSyntax) -> SyntaxVisitorContinueKind {
+    if shouldFormatterIgnore(file: node) {
+      appendFormatterIgnored(node: Syntax(node))
+      return .skipChildren
+    }
     after(node.eofToken, tokens: .break(.same, newlines: .soft))
     return .visitChildren
   }
@@ -3191,6 +3195,13 @@ class CommentMovingRewriter: SyntaxRewriter {
   /// Map of tokens to alternate trivia to use as the token's leading trivia.
   var rewriteTokenTriviaMap: [TokenSyntax: Trivia] = [:]
 
+  override func visit(_ node: SourceFileSyntax) -> Syntax {
+    if shouldFormatterIgnore(file: node) {
+      return Syntax(node)
+    }
+    return super.visit(node)
+  }
+
   override func visit(_ node: CodeBlockItemSyntax) -> Syntax {
     if shouldFormatterIgnore(node: Syntax(node)) {
       return Syntax(node)
@@ -3280,14 +3291,18 @@ extension TriviaPiece {
 
 /// Returns whether the given trivia includes a directive to ignore formatting for the next node.
 ///
-/// - Parameter trivia: Leading trivia for a node that the formatter supports ignoring.
-fileprivate func isFormatterIgnorePresent(inTrivia trivia: Trivia) -> Bool {
+/// - Parameters:
+///   - trivia: Leading trivia for a node that the formatter supports ignoring.
+///   - isWholeFile: Whether to search for a whole-file ignore directive or per node ignore.
+/// - Returns: Whether the trivia contains the specified type of ignore directive.
+fileprivate func isFormatterIgnorePresent(inTrivia trivia: Trivia, isWholeFile: Bool) -> Bool {
   func isFormatterIgnore(in commentText: String, prefix: String, suffix: String) -> Bool {
     let trimmed =
       commentText.dropFirst(prefix.count)
         .dropLast(suffix.count)
         .trimmingCharacters(in: .whitespaces)
-    return trimmed == "swift-format-ignore"
+    let pattern = isWholeFile ? "swift-format-ignore-file" : "swift-format-ignore"
+    return trimmed == pattern
   }
 
   for piece in trivia {
@@ -3317,7 +3332,19 @@ fileprivate func shouldFormatterIgnore(node: Syntax) -> Bool {
   // Regardless of the level of nesting, if the ignore directive is present on the first token
   // contained within the node then the entire node is eligible for ignoring.
   if let firstTrivia = node.firstToken?.leadingTrivia {
-    return isFormatterIgnorePresent(inTrivia: firstTrivia)
+    return isFormatterIgnorePresent(inTrivia: firstTrivia, isWholeFile: false)
+  }
+  return false
+}
+
+/// Returns whether the formatter should ignore the given file by printing it without changing the
+/// any if its nodes' internal text representation (i.e. print all text inside of the file as it was
+/// in the original source).
+///
+/// - Parameter file: The root syntax node for a source file.
+fileprivate func shouldFormatterIgnore(file: SourceFileSyntax) -> Bool {
+  if let firstTrivia = file.firstToken?.leadingTrivia {
+    return isFormatterIgnorePresent(inTrivia: firstTrivia, isWholeFile: true)
   }
   return false
 }

Tests/SwiftFormatCoreTests/RuleMaskTests.swift

@@ -171,4 +171,62 @@ final class RuleMaskTests: XCTestCase {
     XCTAssertEqual(mask.ruleState("TotallyMadeUpRule", at: location(ofLine: 3)), .default)
     XCTAssertEqual(mask.ruleState("rule1", at: location(ofLine: 4)), .default)
   }
+
+  func testAllRulesWholeFileIgnore() {
+    let text =
+      """
+      // This file has important contents.
+      // 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)
+    }
+  }
+
+  func testAllRulesWholeFileIgnoreNestedInNode() {
+    let text =
+      """
+      // This file has important contents.
+      // Everything in this file is ignored.
+
+      let a = 5
+      let b = 4
+
+      class Foo {
+        // swift-format-ignore-file
+        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)), .default)
+    }
+  }
 }

Tests/SwiftFormatCoreTests/XCTestManifests.swift

@@ -6,6 +6,8 @@ extension RuleMaskTests {
     //   `swift test --generate-linuxmain`
     // to regenerate.
     static let __allTests__RuleMaskTests = [
+        ("testAllRulesWholeFileIgnore", testAllRulesWholeFileIgnore),
+        ("testAllRulesWholeFileIgnoreNestedInNode", testAllRulesWholeFileIgnoreNestedInNode),
         ("testDirectiveWithRulesList", testDirectiveWithRulesList),
         ("testDuplicateNested", testDuplicateNested),
         ("testIgnoreTwoRules", testIgnoreTwoRules),

Tests/SwiftFormatPrettyPrintTests/IgnoreNodeTests.swift

@@ -289,4 +289,126 @@ final class IgnoreNodeTests: PrettyPrintTestCase {
 
     assertPrettyPrintEqual(input: input, expected: expected, linelength: 50)
   }
+
+  func testIgnoreWholeFile() {
+    let input =
+      """
+      // swift-format-ignore-file
+      import Zoo
+      import Aoo
+      import foo
+
+          struct Foo {
+            private var baz: Bool {
+                return foo +
+                 bar + // poorly placed comment
+                  false
+            }
+
+            var a = true    // line comment
+                            // aligned line comment
+            var b = false  // correct trailing comment
+
+      var c = 0 +
+          1
+          + (2 + 3)
+      }
+
+            class Bar
+      {
+        var bazzle = 0 }
+      """
+
+    let expected =
+      """
+      // swift-format-ignore-file
+      import Zoo
+      import Aoo
+      import foo
+
+          struct Foo {
+            private var baz: Bool {
+                return foo +
+                 bar + // poorly placed comment
+                  false
+            }
+
+            var a = true    // line comment
+                            // aligned line comment
+            var b = false  // correct trailing comment
+
+      var c = 0 +
+          1
+          + (2 + 3)
+      }
+
+            class Bar
+      {
+        var bazzle = 0 }
+      """
+
+    assertPrettyPrintEqual(input: input, expected: expected, linelength: 50)
+  }
+
+  func testIgnoreWholeFileInNestedNode() {
+    let input =
+      """
+      import Zoo
+      import Aoo
+      import foo
+
+      // swift-format-ignore-file
+          struct Foo {
+            private var baz: Bool {
+                return foo +
+                 bar + // poorly placed comment
+                  false
+            }
+
+            var a = true    // line comment
+                            // aligned line comment
+            var b = false  // correct trailing comment
+
+      var c = 0 +
+          1
+          + (2 + 3)
+      }
+
+            class Bar
+      {
+      // swift-format-ignore-file
+        var bazzle = 0 }
+      """
+
+    let expected =
+      """
+      import Zoo
+      import Aoo
+      import foo
+
+      // swift-format-ignore-file
+      struct Foo {
+        private var baz: Bool {
+          return foo + bar  // poorly placed comment
+            + false
+        }
+
+        var a = true  // line comment
+        // aligned line comment
+        var b = false  // correct trailing comment
+
+        var c =
+          0 + 1
+          + (2 + 3)
+      }
+
+      class Bar {
+        // swift-format-ignore-file
+        var bazzle = 0
+      }
+
+      """
+
+    assertPrettyPrintEqual(input: input, expected: expected, linelength: 50)
+  }
 }

Tests/SwiftFormatPrettyPrintTests/XCTestManifests.swift

@@ -396,6 +396,8 @@ extension IgnoreNodeTests {
         ("testIgnoreInvalidAfterFirstToken", testIgnoreInvalidAfterFirstToken),
         ("testIgnoreMemberDeclListItems", testIgnoreMemberDeclListItems),
         ("testIgnoresNestedMembers", testIgnoresNestedMembers),
+        ("testIgnoreWholeFile", testIgnoreWholeFile),
+        ("testIgnoreWholeFileInNestedNode", testIgnoreWholeFileInNestedNode),
         ("testInvalidComment", testInvalidComment),
         ("testValidComment", testValidComment),
     ]