Add solutions to remove invalid metadata directives in documentation comments

Sources/SwiftDocC/Semantics/Metadata/Metadata.swift

@@ -223,18 +223,38 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
             .map { (type(of: $0).directiveName, $0.originalMarkup.range) }
 
         problems.append(
-            contentsOf: namesAndRanges.map { (name, range) in
-                Problem(
+            contentsOf: namesAndRanges.compactMap { (name, range) in
+                guard let range = range else {
+                    // If we don't have a range, we can't provide a solution, so just create a problem without solutions
+                    return Problem(
+                        diagnostic: Diagnostic(
+                            source: symbolSource,
+                            severity: .warning,
+                            range: range,
+                            identifier: "org.swift.docc.\(Metadata.directiveName).Invalid\(name)InDocumentationComment",
+                            summary: "Invalid use of \(name.singleQuoted) directive in documentation comment; configuration will be ignored",
+                            explanation: "Specify this configuration in a documentation extension file"
+                        )
+                    )
+                }
+
+                let solution = Solution(
+                    summary: "Remove invalid \(name.singleQuoted) directive",
+                    replacements: [
+                        Replacement(range: range, replacement: "")
+                    ]
+                )
+
+                return Problem(
                     diagnostic: Diagnostic(
                         source: symbolSource,
                         severity: .warning,
                         range: range,
                         identifier: "org.swift.docc.\(Metadata.directiveName).Invalid\(name)InDocumentationComment",
                         summary: "Invalid use of \(name.singleQuoted) directive in documentation comment; configuration will be ignored",
                         explanation: "Specify this configuration in a documentation extension file"
-
-                        // TODO: It would be nice to offer a solution here that removes the directive for you (#1111, rdar://140846407)
-                    )
+                    ),
+                    possibleSolutions: [solution]
                 )
             }
         )

Tests/SwiftDocCTests/Semantics/SymbolTests.swift

@@ -1311,6 +1311,19 @@ class SymbolTests: XCTestCase {
                 "org.swift.docc.Metadata.InvalidRedirectedInDocumentationComment",
             ]
         )
+
+        // Verify that each problem has exactly one solution to remove the directive
+        for problem in problems {
+            XCTAssertEqual(problem.possibleSolutions.count, 1, "Each invalid metadata directive should have exactly one solution")
+
+            let solution = try XCTUnwrap(problem.possibleSolutions.first)
+            XCTAssertTrue(solution.summary.hasPrefix("Remove invalid"), "Solution summary should start with 'Remove invalid'")
+            XCTAssertEqual(solution.replacements.count, 1, "Solution should have exactly one replacement")
+
+            let replacement = try XCTUnwrap(solution.replacements.first)
+            XCTAssertEqual(replacement.replacement, "", "Replacement should be empty string to remove the directive")
+            XCTAssertNotNil(replacement.range, "Replacement should have a valid range")
+        }
     }
 
     func testParsesDeprecationSummaryDirectiveFromDocComment() async throws {
@@ -1352,6 +1365,36 @@ class SymbolTests: XCTestCase {
         XCTAssert(problems.isEmpty)
     }
 
+    func testSolutionForInvalidMetadataDirectiveRemovesDirective() async throws {
+        let (_, problems) = try await makeDocumentationNodeForSymbol(
+            docComment: """
+                The symbol's abstract.
+
+                @Metadata {
+                  @DisplayName("Invalid Display Name")
+                }
+                """,
+            articleContent: nil
+        )
+
+        XCTAssertEqual(problems.count, 1)
+        let problem = try XCTUnwrap(problems.first)
+
+        XCTAssertEqual(problem.diagnostic.identifier, "org.swift.docc.Metadata.InvalidDisplayNameInDocumentationComment")
+        XCTAssertEqual(problem.possibleSolutions.count, 1)
+
+        let solution = try XCTUnwrap(problem.possibleSolutions.first)
+        XCTAssertEqual(solution.summary, "Remove invalid 'DisplayName' directive")
+        XCTAssertEqual(solution.replacements.count, 1)
+
+        let replacement = try XCTUnwrap(solution.replacements.first)
+        XCTAssertEqual(replacement.replacement, "")
+        XCTAssertNotNil(replacement.range)
+
+        // The replacement should remove the entire @DisplayName directive
+        // This would effectively remove the line "@DisplayName("Invalid Display Name")"
+    }
+
     // MARK: - Leading Whitespace in Doc Comments
 
     func testWithoutLeadingWhitespace() {