validate array values in code block options for highlight and strikeout

Author: Jesse Haigh

Sources/SwiftDocC/Checker/Checkers/InvalidCodeBlockOption.swift

@@ -58,8 +58,36 @@ public struct InvalidCodeBlockOption: Checker {
             }
         }
 
+        func validateArrayIndices(token: RenderBlockContent.CodeListing.OptionName, value: String?) {
+            guard token == .highlight || token == .strikeout, let value = value else { return }
+            // code property ends in a newline. this gives us a bogus extra line.
+            let lineCount: Int = codeBlock.code.split(omittingEmptySubsequences: false, whereSeparator: { $0.isNewline }).count - 1
+
+            guard let indices = parseCodeBlockOptionArray(value) else {
+                let diagnostic = Diagnostic(source: sourceFile, severity: .warning, range: codeBlock.range, identifier: "org.swift.docc.InvalidCodeBlockOption", summary: "Could not parse \(token.rawValue.singleQuoted) indices from \(value.singleQuoted). Expected an integer (e.g. 3) or an array (e.g. [1, 3, 5])")
+                problems.append(Problem(diagnostic: diagnostic, possibleSolutions: []))
+                return
+            }
+
+            let invalid = indices.filter { $0 < 1 || $0 > lineCount }
+            guard !invalid.isEmpty else { return }
+
+            let diagnostic = Diagnostic(source: sourceFile, severity: .warning, range: codeBlock.range, identifier: "org.swift.docc.InvalidCodeBlockOption", summary: "Invalid \(token.rawValue.singleQuoted) index\(invalid.count == 1 ? "" : "es") in \(value.singleQuoted) for a code block with \(lineCount) line\(lineCount == 1 ? "" : "s"). Valid range is 1...\(lineCount).")
+            let solutions: [Solution] = {
+                if invalid.contains(where: {$0 == lineCount + 1}) {
+                    return [Solution(
+                        summary: "If you intended the last line, change '\(lineCount + 1)' to \(lineCount).",
+                        replacements: []
+                    )]
+                }
+                return []
+            }()
+            problems.append(Problem(diagnostic: diagnostic, possibleSolutions: solutions))
+        }
+
         for (token, value) in tokens {
             matches(token: token, value: value)
+            validateArrayIndices(token: token, value: value)
         }
         // check if first token (lang) might be a typo
         matches(token: .unknown, value: lang)

Tests/SwiftDocCTests/Checker/Checkers/InvalidCodeBlockOptionTests.swift

@@ -122,5 +122,41 @@ let b = 2
             XCTAssertEqual(problem.possibleSolutions.map(\.summary), ["If 'swift' is the language for this code block, then write 'swift' as the first option."])
         }
     }
+
+    func testInvalidHighlightIndex() throws {
+        let markupSource = """
+```swift, nocopy, highlight=[2]
+let b = 2
+```
+"""
+        let document = Document(parsing: markupSource, options: [])
+        var checker = InvalidCodeBlockOption(sourceFile: URL(fileURLWithPath: #file))
+        checker.visit(document)
+        XCTAssertEqual(1, checker.problems.count)
+        let problem = try XCTUnwrap(checker.problems.first)
+
+        XCTAssertEqual("org.swift.docc.InvalidCodeBlockOption", problem.diagnostic.identifier)
+        XCTAssertEqual(problem.diagnostic.summary, "Invalid 'highlight' index in '[2]' for a code block with 1 line. Valid range is 1...1.")
+        XCTAssertEqual(problem.possibleSolutions.map(\.summary), ["If you intended the last line, change '2' to 1."])
+    }
+
+    func testInvalidHighlightandStrikeoutIndex() throws {
+        let markupSource = """
+```swift, nocopy, highlight=[0], strikeout=[-1, 4]
+let a = 1
+let b = 2
+let c = 3
+```
+"""
+        let document = Document(parsing: markupSource, options: [])
+        var checker = InvalidCodeBlockOption(sourceFile: URL(fileURLWithPath: #file))
+        checker.visit(document)
+        XCTAssertEqual(2, checker.problems.count)
+
+        XCTAssertEqual("org.swift.docc.InvalidCodeBlockOption", checker.problems[0].diagnostic.identifier)
+        XCTAssertEqual(checker.problems[0].diagnostic.summary, "Invalid 'highlight' index in '[0]' for a code block with 3 lines. Valid range is 1...3.")
+        XCTAssertEqual(checker.problems[1].diagnostic.summary, "Invalid 'strikeout' indexes in '[-1, 4]' for a code block with 3 lines. Valid range is 1...3.")
+        XCTAssertEqual(checker.problems[1].possibleSolutions.map(\.summary), ["If you intended the last line, change '4' to 3."])
+    }
 }