Add solutions to remove invalid metadata directives in documentation comments (#1277)

* Add solutions to remove invalid metadata directives in documentation comments

- Implement solutions for org.swift.docc.Metadata.Invalid<directive>InDocumentationComment diagnostics
- Each invalid directive now has a solution that removes the directive
- Follows the same pattern as other directive removal solutions in the codebase
- Added comprehensive tests to verify solutions are provided correctly
- Fixes issue #1111

* Fix code duplication in validateForUseInDocumentationComment method

- Create diagnostic once instead of duplicating it
- Use conditional solutions array based on range availability
- Single Problem creation path for better maintainability

* Add range verification test for invalid metadata directive solutions

- Verify replacement range matches problem's diagnostic range
- Ensures solution targets the correct content
- Improves test coverage for range accuracy

* Move test comments into assertion messages for better clarity

- Move explanatory comments into assertion message parameters
- Provides better context when tests fail
- Makes tests more self-documenting

* Fix code duplication in validateForUseInDocumentationComment method

- Create diagnostic once instead of duplicating it
- Use conditional solutions array based on range availability
- Single Problem creation path for better maintainability

Author: agisilaos

Sources/SwiftDocC/Semantics/Metadata/Metadata.swift

@@ -224,18 +224,25 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
 
         problems.append(
             contentsOf: namesAndRanges.map { (name, range) in
-                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)
-                    )
+                let 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 solutions: [Solution] = range.map { range in
+                    [Solution(
+                        summary: "Remove invalid \(name.singleQuoted) directive",
+                        replacements: [
+                            Replacement(range: range, replacement: "")
+                        ]
+                    )]
+                } ?? []
+                
+                return Problem(diagnostic: diagnostic, possibleSolutions: solutions)
             }
         )
 

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, "", "Replacement should be empty string to remove the directive")
+        XCTAssertNotNil(replacement.range, "Replacement should have a valid range")
+        
+        // Verify that the replacement range covers the expected content
+        XCTAssertEqual(replacement.range, problem.diagnostic.range, "Replacement range should match the problem's diagnostic range to ensure it removes the entire @DisplayName directive")
+    }
+
     // MARK: - Leading Whitespace in Doc Comments
 
     func testWithoutLeadingWhitespace() {