Add preferFinalClasses rule (#2196)

Author: calda

Rules.md

@@ -111,6 +111,7 @@
 * [noExplicitOwnership](#noExplicitOwnership)
 * [noGuardInTests](#noGuardInTests)
 * [organizeDeclarations](#organizeDeclarations)
+* [preferFinalClasses](#preferFinalClasses)
 * [preferSwiftTesting](#preferSwiftTesting)
 * [privateStateVariables](#privateStateVariables)
 * [propertyTypes](#propertyTypes)
@@ -1917,6 +1918,39 @@ Prefer `count(where:)` over `filter(_:).count`.
 </details>
 <br/>
 
+## preferFinalClasses
+
+Prefer defining `final` classes. To suppress this rule, add "Base" to the class name, add a doc comment with mentioning "base class" or "subclass", make the class `open`, or use a `// swiftformat:disable:next preferFinalClasses` directive.
+
+<details>
+<summary>Examples</summary>
+
+```diff
+- class Foo {}
++ final class Foo {}
+```
+
+```diff
+- public class Bar {}
++ public final class Bar {}
+```
+
+```diff
+  // Preserved classes:
+  open class Baz {}
+
+  class BaseClass {}
+
+  class MyClass {} // Subclassed in this file
+  class MySubclass: MyClass {}
+
+  /// Base class to be subclassed by other features
+  class MyCustomizationPoint {}
+```
+
+</details>
+<br/>
+
 ## preferForLoop
 
 Convert functional `forEach` calls to for loops.

Sources/Declaration.swift

@@ -176,6 +176,11 @@ extension Declaration {
         }
     }
 
+    /// The range of the doc comment or regular comment immediately preceding this declaration
+    var docCommentRange: ClosedRange<Int>? {
+        formatter.parseDocCommentRange(forDeclarationAt: keywordIndex)
+    }
+
     /// The `CustomDebugStringConvertible` representation of this declaration
     var debugDescription: String {
         guard isValid else {

Sources/ParsingHelpers.swift

@@ -2612,6 +2612,29 @@ extension Formatter {
         return matches
     }
 
+    /// Parses the range of the doc comment or regular comment immediately preceding the declaration
+    func parseDocCommentRange(forDeclarationAt keywordIndex: Int) -> ClosedRange<Int>? {
+        let startOfModifiers = startOfModifiers(at: keywordIndex, includingAttributes: true)
+
+        var parseIndex = startOfModifiers
+        var endOfComment: Int?
+
+        while let endOfPreviousLine = index(of: .linebreak, before: parseIndex),
+              let endOfPreviousLineContent = index(of: .nonSpace, before: endOfPreviousLine),
+              tokens[endOfPreviousLineContent].isComment,
+              let startOfScope = startOfScope(at: endOfPreviousLineContent)
+        {
+            parseIndex = startOfScope
+
+            if endOfComment == nil {
+                endOfComment = endOfPreviousLineContent
+            }
+        }
+
+        guard let endOfComment else { return nil }
+        return parseIndex ... endOfComment
+    }
+
     /// Parses the prorocol composition typealias declaration starting at the given `typealias` keyword index.
     /// Returns `nil` if the given index isn't a protocol composition typealias.
     func parseProtocolCompositionTypealias(at typealiasIndex: Int)

Sources/RuleRegistry.generated.swift

@@ -60,6 +60,7 @@ let ruleRegistry: [String: FormatRule] = [
     "opaqueGenericParameters": .opaqueGenericParameters,
     "organizeDeclarations": .organizeDeclarations,
     "preferCountWhere": .preferCountWhere,
+    "preferFinalClasses": .preferFinalClasses,
     "preferForLoop": .preferForLoop,
     "preferKeyPath": .preferKeyPath,
     "preferSwiftTesting": .preferSwiftTesting,

Sources/Rules/PreferFinalClasses.swift

@@ -0,0 +1,110 @@
+//
+//  PreferFinalClasses.swift
+//  SwiftFormat
+//
+//  Created by Cal Stephens on 2025-08-25.
+//  Copyright © 2024 Nick Lockwood. All rights reserved.
+//
+
+import Foundation
+
+public extension FormatRule {
+    /// Add the `final` keyword to all classes that are not declared as `open`
+    static let preferFinalClasses = FormatRule(
+        help: """
+        Prefer defining `final` classes. To suppress this rule, add "Base" to the class name, \
+        add a doc comment with mentioning "base class" or "subclass", make the class `open`, \
+        or use a `// swiftformat:disable:next preferFinalClasses` directive.
+        """,
+        disabledByDefault: true
+    ) { formatter in
+        // Parse all declarations to understand inheritance relationships
+        let declarations = formatter.parseDeclarations()
+
+        // Find all class names that are inherited from in this file
+        var classesWithSubclasses = Set<String>()
+        declarations.forEachRecursiveDeclaration { declaration in
+            guard declaration.keyword == "class" else { return }
+
+            // Check all conformances - any of them could be a superclass
+            let conformances = formatter.parseConformancesOfType(atKeywordIndex: declaration.keywordIndex)
+            for conformance in conformances {
+                // Extract base class name from generic types like "Container<String>" -> "Container"
+                let baseClassName = conformance.conformance.tokens.first?.string ?? conformance.conformance.string
+                classesWithSubclasses.insert(baseClassName)
+            }
+        }
+
+        // Now process each class declaration
+        declarations.forEachRecursiveDeclaration { declaration in
+            guard declaration.keyword == "class",
+                  let className = declaration.name else { return }
+
+            let keywordIndex = declaration.keywordIndex
+
+            // Check if class already has final or open modifiers
+            let hasFinalModifier = formatter.modifiersForDeclaration(at: keywordIndex, contains: "final")
+            let hasOpenModifier = formatter.modifiersForDeclaration(at: keywordIndex, contains: "open")
+
+            // Only add final if the class doesn't already have final or open
+            guard !hasFinalModifier, !hasOpenModifier else { return }
+
+            // Don't add final if this class is inherited from in the same file
+            guard !classesWithSubclasses.contains(className) else { return }
+
+            // Don't add final to classes that contain "Base" (they're likely meant to be subclassed)
+            guard !className.contains("Base") else { return }
+
+            // Don't add final to classes with a comment like "// Base class for XYZ functionality"
+            if let docCommentRange = declaration.docCommentRange {
+                let subclassRelatedTerms = ["base", "subclass"]
+                let docComment = formatter.tokens[docCommentRange].string.lowercased()
+
+                for term in subclassRelatedTerms {
+                    if docComment.contains(term) {
+                        return
+                    }
+                }
+            }
+
+            formatter.insert(tokenize("final "), at: keywordIndex)
+
+            // Convert any open direct child declarations to public (since final classes can't have open members)
+            if let classBody = declaration.body {
+                for childDeclaration in classBody {
+                    guard formatter.modifiersForDeclaration(at: childDeclaration.keywordIndex, contains: "open") else { continue }
+
+                    // Replace "open" with "public" for direct child declarations
+                    if let openIndex = formatter.indexOfModifier("open", forDeclarationAt: childDeclaration.keywordIndex) {
+                        formatter.replaceToken(at: openIndex, with: .keyword("public"))
+                    }
+                }
+            }
+        }
+    } examples: {
+        """
+        ```diff
+        - class Foo {}
+        + final class Foo {}
+        ```
+
+        ```diff
+        - public class Bar {}
+        + public final class Bar {}
+        ```
+
+        ```diff
+          // Preserved classes:
+          open class Baz {}
+
+          class BaseClass {}
+
+          class MyClass {} // Subclassed in this file
+          class MySubclass: MyClass {}
+
+          /// Base class to be subclassed by other features
+          class MyCustomizationPoint {}
+        ```
+        """
+    }
+}

Tests/ParsingHelpersTests.swift

@@ -2965,4 +2965,33 @@ class ParsingHelpersTests: XCTestCase {
             "baaz: baaz.quux",
         ])
     }
+
+    func testParseCommentRange() throws {
+        let input = """
+        import FooLib
+
+        // Class declaration
+        class MyClass {}
+
+        // Other comment
+
+        /// Foo bar
+        /// baaz quux
+        @Foo
+        struct MyStruct {}
+        """
+
+        let formatter = Formatter(tokenize(input))
+        let classCommentRange = try XCTUnwrap(formatter.parseDocCommentRange(forDeclarationAt: 9)) // class
+        let structCommentRange = try XCTUnwrap(formatter.parseDocCommentRange(forDeclarationAt: 30)) // struct
+
+        XCTAssertEqual(formatter.tokens[classCommentRange].string, """
+        // Class declaration
+        """)
+
+        XCTAssertEqual(formatter.tokens[structCommentRange].string, """
+        /// Foo bar
+        /// baaz quux
+        """)
+    }
 }