Prevent accessing unicode scalar element with incorrect index.

This change prevents a potential DocC crash by making sure that it does not access
an array element using an index that is outside of the bonds of the array.

`.index(after:` can crash in some cases if the passed index
belongs to the last element of the collection. with this change we ensure
that the passed index is not the last index.

rdar://150760264

Author: sofiaromorales

Sources/SwiftDocC/Utility/ValidatedURL.swift

@@ -179,23 +179,29 @@ private extension StringProtocol {
     func addingPercentEncodingIfNeeded(withAllowedCharacters allowedCharacters: CharacterSet) -> String? {
         var needsPercentEncoding: Bool {
             for (index, character) in unicodeScalars.indexed() where !allowedCharacters.contains(character) {
+                // Check if the character "%" represents a percent encoded URL.
+                // Any other disallowed character is an indication that this substring needs percent encoding.
                 if character == "%" {
                     // % isn't allowed in a URL fragment but it is also the escape character for percent encoding.
-                    let firstFollowingIndex  = unicodeScalars.index(after: index)
-                    let secondFollowingIndex = unicodeScalars.index(after: firstFollowingIndex)
-                    
-                    guard secondFollowingIndex < unicodeScalars.endIndex else {
+                    guard self.distance(from: index, to: self.endIndex) >= 2 else {
                         // There's not two characters after the "%". This "%" can't represent a percent encoded character.
                         return true
                     }
-                    // If either of the two following characters aren't hex digits, the "%" doesn't represent a
-                    return !Character(unicodeScalars[firstFollowingIndex]).isHexDigit
-                        || !Character(unicodeScalars[secondFollowingIndex]).isHexDigit
+                    let firstFollowingIndex  = self.index(after: index)
+                    let secondFollowingIndex = self.index(after: firstFollowingIndex)
 
-                } else {
-                    // Any other disallowed character is an indication that this substring needs percent encoding.
-                    return true
+                    // Check if the next two characthers represent a percent encoded
+                    // URL.
+                    // If either of the two following characters aren't hex digits,
+                    // the "%" doesn't represent a percent encoded character.
+                    if Character(unicodeScalars[firstFollowingIndex]).isHexDigit,
+                       Character(unicodeScalars[secondFollowingIndex]).isHexDigit
+                    {
+                        // Later characters in the string might require percentage encoding.
+                        continue
+                    }
                 }
+                return true
             }
             return false
         }

Tests/SwiftDocCTests/Utility/ValidatedURLTests.swift

@@ -81,6 +81,14 @@ class ValidatedURLTests: XCTestCase {
     }
 
     func testQueryIsPartOfPathForAuthoredLinks() throws {
+        
+        func validate(linkText: String, expectedPath: String, expectedFragment: String? = nil,file: StaticString = #filePath, line: UInt = #line) throws {
+            let validated = try XCTUnwrap(ValidatedURL(parsingAuthoredLink: linkText), "Failed to parse \(linkText.singleQuoted) as authored link")
+            XCTAssertNil(validated.components.queryItems, "Authored documentation links don't include query items", file: file, line: line)
+            XCTAssertEqual(validated.components.path, expectedPath, file: file, line: line)
+            XCTAssertEqual(validated.components.fragment, expectedFragment, file: file, line: line)
+        }
+        
         // Test return type disambiguation
         for linkText in [
             "SymbolName/memberName()->Int?",
@@ -91,14 +99,8 @@ class ValidatedURLTests: XCTestCase {
                 ? "/SymbolName/memberName()->Int?"
                 :  "SymbolName/memberName()->Int?"
 
-            let validated = try XCTUnwrap(ValidatedURL(parsingAuthoredLink: linkText), "Failed to parse \(linkText.singleQuoted) as authored link")
-            XCTAssertNil(validated.components.queryItems, "Authored documentation links don't include query items")
-            XCTAssertEqual(validated.components.path, expectedPath)
-            
-            let validatedWithHeading = try XCTUnwrap(ValidatedURL(parsingAuthoredLink: linkText + "#Heading-Name"), "Failed to parse '\(linkText)#Heading-Name' as authored link")
-            XCTAssertNil(validatedWithHeading.components.queryItems, "Authored documentation links don't include query items")
-            XCTAssertEqual(validatedWithHeading.components.path, expectedPath)
-            XCTAssertEqual(validatedWithHeading.components.fragment, "Heading-Name")
+            try validate(linkText: linkText, expectedPath: expectedPath)
+            try validate(linkText: linkText + "#Heading-Name", expectedPath: expectedPath, expectedFragment: "Heading-Name")
         }
 
         // Test parameter type disambiguation
@@ -111,15 +113,29 @@ class ValidatedURLTests: XCTestCase {
                 ? "/SymbolName/memberName(with:and:)-(Int?,_)"
                 :  "SymbolName/memberName(with:and:)-(Int?,_)"
 
-            let validated = try XCTUnwrap(ValidatedURL(parsingAuthoredLink: linkText), "Failed to parse \(linkText.singleQuoted) as authored link")
-            XCTAssertNil(validated.components.queryItems, "Authored documentation links don't include query items")
-            XCTAssertEqual(validated.components.path, expectedPath)
-            
-            let validatedWithHeading = try XCTUnwrap(ValidatedURL(parsingAuthoredLink: linkText + "#Heading-Name"), "Failed to parse '\(linkText)#Heading-Name' as authored link")
-            XCTAssertNil(validatedWithHeading.components.queryItems, "Authored documentation links don't include query items")
-            XCTAssertEqual(validatedWithHeading.components.path, expectedPath)
-            XCTAssertEqual(validatedWithHeading.components.fragment, "Heading-Name")
+            try validate(linkText: linkText, expectedPath: expectedPath)
+            try validate(linkText: linkText + "#Heading-Name", expectedPath: expectedPath, expectedFragment: "Heading-Name")
         }
+        
+        // Test parameter with percent encoding
+        var linkText = "doc://com.example.test/docc=Whats%20New&version=DocC&Title=[Update]"
+        var expectedPath = "/docc=Whats%20New&version=DocC&Title=[Update]"
+        try validate(linkText: linkText, expectedPath: expectedPath)
+        
+        // Test parameter with percent encoding at the end of the URL
+        linkText = "doc://com.example.test/docc=Whats%20New&version=DocC&Title=[Update]%20"
+        expectedPath = "/docc=Whats%20New&version=DocC&Title=[Update]%20"
+        try validate(linkText: linkText, expectedPath: expectedPath)
+        
+        // Test parameter without percent encoding
+        linkText = "doc://com.example.test/docc=WhatsNew&version=DocC&Title=[Update]"
+        expectedPath = "/docc=WhatsNew&version=DocC&Title=[Update]"
+        try validate(linkText: linkText, expectedPath: expectedPath)
+        
+        // Test parameter with special characters
+        linkText = "doc://com.example.test/テスト"
+        expectedPath = "/テスト"
+        try validate(linkText: linkText, expectedPath: expectedPath)
     }
 
     func testEscapedFragment() throws {