Merge branch 'main' into remove-redundant-bundle-params

Author: d-ronnqvist

Sources/SwiftDocC/Checker/Checkers/AbstractContainsFormattedTextOnly.swift

@@ -14,7 +14,7 @@ public import Markdown
 /**
  A document's abstract may only contain formatted text. Images and links are not allowed.
  */
-@available(*, deprecated, message: "This check is no longer applicable. This deprecated API will be removed after 6.3 is released")
+@available(*, deprecated, message: "This check is no longer applicable. This deprecated API will be removed after 6.4 is released")
 public struct AbstractContainsFormattedTextOnly: Checker {
     public var problems: [Problem] = [Problem]()
     private var sourceFile: URL?

Sources/SwiftDocC/Checker/Checkers/InvalidCodeBlockOption.swift

@@ -0,0 +1,97 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+internal import Foundation
+internal import Markdown
+
+/**
+ Code blocks can have a `nocopy` option after the \`\`\`, in the language line.
+`nocopy` can be immediately after the \`\`\` or after a specified language and a comma (`,`).
+ */
+internal struct InvalidCodeBlockOption: Checker {
+    var problems = [Problem]()
+
+    /// Parsing options for code blocks
+    private let knownOptions = RenderBlockContent.CodeBlockOptions.knownOptions
+
+    private var sourceFile: URL?
+
+    /// Creates a new checker that detects documents with multiple titles.
+    ///
+    /// - Parameter sourceFile: The URL to the documentation file that the checker checks.
+    init(sourceFile: URL?) {
+        self.sourceFile = sourceFile
+    }
+
+    mutating func visitCodeBlock(_ codeBlock: CodeBlock) {
+        let (lang, tokens) = RenderBlockContent.CodeBlockOptions.tokenizeLanguageString(codeBlock.language)
+
+        func matches(token: RenderBlockContent.CodeBlockOptions.OptionName, value: String?) {
+            guard token == .unknown, let value = value else { return }
+
+            let matches = NearMiss.bestMatches(for: knownOptions, against: value)
+
+            if !matches.isEmpty {
+                let diagnostic = Diagnostic(source: sourceFile, severity: .warning, range: codeBlock.range, identifier: "org.swift.docc.InvalidCodeBlockOption", summary: "Unknown option \(value.singleQuoted) in code block.")
+                let possibleSolutions = matches.map { candidate in
+                    Solution(
+                        summary: "Replace \(value.singleQuoted) with \(candidate.singleQuoted).",
+                        replacements: []
+                    )
+                }
+                problems.append(Problem(diagnostic: diagnostic, possibleSolutions: possibleSolutions))
+            } else if lang == nil {
+                let diagnostic = Diagnostic(source: sourceFile, severity: .warning, range: codeBlock.range, identifier: "org.swift.docc.InvalidCodeBlockOption", summary: "Unknown option \(value.singleQuoted) in code block.")
+                let possibleSolutions =
+                Solution(
+                    summary: "If \(value.singleQuoted) is the language for this code block, then write \(value.singleQuoted) as the first option.",
+                    replacements: []
+                )
+                problems.append(Problem(diagnostic: diagnostic, possibleSolutions: [possibleSolutions]))
+            }
+        }
+
+        func validateArrayIndices(token: RenderBlockContent.CodeBlockOptions.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
+
+            let indices = RenderBlockContent.CodeBlockOptions.parseCodeBlockOptionsArray(value)
+
+            if !value.isEmpty, indices.isEmpty {
+                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)
+    }
+}

Sources/SwiftDocC/Indexing/Navigator/AvailabilityIndex+Ext.swift

@@ -83,7 +83,7 @@ public struct InterfaceLanguage: Hashable, CustomStringConvertible, Codable, Equ
     /// > ``from(string:)`` function.
     public let id: String
 
-    /// A mask to use to identify the interface language..
+    /// A mask to use to identify the interface language.
     public let mask: ID
 
 

Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift

@@ -219,12 +219,12 @@ public class NavigatorIndex {
     }
 
     /**
-     Initialize an `NavigatorIndex` from a given path with an empty tree.
+     Initialize a `NavigatorIndex` from a given path with an empty tree.
 
      - Parameter url: The URL pointing to the path from which the index should be read.
      - Parameter bundleIdentifier: The name of the bundle the index is referring to.
 
-     - Note: Don't exposed this initializer as it's used **ONLY** for building an index.
+     - Note: Don't expose this initializer as it's used **ONLY** for building an index.
      */
     fileprivate init(withEmptyTree url: URL, bundleIdentifier: String) throws {
         self.url = url
@@ -364,14 +364,14 @@ public class NavigatorIndex {
     Read a tree on disk from a given path.
     The read is atomically performed, which means it reads all the content of the file from the disk and process the tree from loaded data.
     The queue is used to load the data for a given timeout period, after that, the queue is used to schedule another read after a given delay.
-    This approach ensures that the used  queue doesn't stall while loading the content from the disk keeping the used queue responsive.
+    This approach ensures that the used queue doesn't stall while loading the content from the disk keeping the used queue responsive.
 
     - Parameters:
-       - timeout: The amount of time we can load a batch of items from data, once the timeout time pass,
+       - timeout: The duration for which we can load a batch of items from data. Once the timeout duration passes,
                   the reading process will reschedule asynchronously using the given queue.
-       - delay: The delay to wait before schedule the next read. Default: 0.01 seconds.
+       - delay: The duration to wait for before scheduling the next read. Default: 0.01 seconds.
        - queue: The queue to use.
-       - broadcast: The callback to update get updates of the current process.
+       - broadcast: The callback to receive updates on the status of the current process.
 
     - Note: Do not access the navigator tree root node or the map from identifier to node from a different thread than the one the queue is using while the read is performed,
      this may cause data inconsistencies. For that please use the broadcast callback that notifies which items have been loaded.
@@ -455,6 +455,17 @@ extension NavigatorIndex {
             self.fragment = fragment
             self.languageIdentifier = languageIdentifier
         }
+
+        /// Compare an identifier with another one, ignoring the identifier language.
+        ///
+        /// Used when curating cross-language references in multi-language frameworks.
+        ///
+        /// - Parameter other: The other identifier to compare with.
+        func isEquivalentIgnoringLanguage(to other: Identifier) -> Bool {
+            return self.bundleIdentifier == other.bundleIdentifier &&
+                   self.path == other.path &&
+                   self.fragment == other.fragment
+        }
     }
 
     /**
@@ -884,7 +895,7 @@ extension NavigatorIndex {
         ///   - emitJSONRepresentation: Whether or not a JSON representation of the index should
         ///     be written to disk.
         ///
-        ///     Defaults to `false`.
+        ///     Defaults to `true`.
         ///
         ///   - emitLMDBRepresentation: Whether or not an LMDB representation of the index should
         ///     written to disk.
@@ -917,7 +928,7 @@ extension NavigatorIndex {
                     let (nodeID, parent) = nodesMultiCurated[index]
                     let placeholders = identifierToChildren[nodeID]!
                     for reference in placeholders {
-                        if let child = identifierToNode[reference] {
+                        if let child = identifierToNode[reference] ?? externalNonSymbolNode(for: reference) {
                             parent.add(child: child)
                             pendingUncuratedReferences.remove(reference)
                             if !multiCurated.keys.contains(reference) && reference.fragment == nil {
@@ -938,7 +949,7 @@ extension NavigatorIndex {
             for (nodeIdentifier, placeholders) in identifierToChildren {
                 for reference in placeholders {
                     let parent = identifierToNode[nodeIdentifier]!
-                    if let child = identifierToNode[reference] {
+                    if let child = identifierToNode[reference] ?? externalNonSymbolNode(for: reference) {
                         let needsCopy = multiCurated[reference] != nil
                         parent.add(child: (needsCopy) ? child.copy() : child)
                         pendingUncuratedReferences.remove(reference)
@@ -969,14 +980,11 @@ extension NavigatorIndex {
                 // page types as symbol nodes on the assumption that an unknown page type is a
                 // symbol kind added in a future version of Swift-DocC.
                 // Finally, don't add external references to the root; if they are not referenced within the navigation tree, they should be dropped altogether.
-                if let node = identifierToNode[nodeID], PageType(rawValue: node.item.pageType)?.isSymbolKind == false , !node.item.isExternal {
+                if let node = identifierToNode[nodeID], PageType(rawValue: node.item.pageType)?.isSymbolKind == false, !node.item.isExternal {
 
                     // If an uncurated page has been curated in another language, don't add it to the top-level.
                     if curatedReferences.contains(where: { curatedNodeID in
-                        // Compare all the identifier's properties for equality, except for its language.
-                        curatedNodeID.bundleIdentifier == nodeID.bundleIdentifier
-                            && curatedNodeID.path == nodeID.path
-                            && curatedNodeID.fragment == nodeID.fragment
+                        curatedNodeID.isEquivalentIgnoringLanguage(to: nodeID)
                     }) {
                         continue
                     }
@@ -1256,7 +1264,22 @@ extension NavigatorIndex {
             problem = Problem(diagnostic: diagnostic, possibleSolutions: [])
             problems.append(problem)
         }
-        
+
+        /// Find an external node for the reference that is not of a symbol kind. The source language
+        /// of the reference is ignored during this lookup since the reference assumes the target node
+        /// to be of the same language as the page that it is curated in. This may or may not be true
+        /// since non-symbol kinds (articles, tutorials, etc.) are not tied to a language.
+        // This is a workaround for https://github.com/swiftlang/swift-docc/issues/240.
+        // FIXME: This should ideally be solved by making the article language-agnostic rather
+        // than accomodating the "Swift" language and special-casing for non-symbol nodes.
+        func externalNonSymbolNode(for reference: NavigatorIndex.Identifier) -> NavigatorTree.Node? {
+            identifierToNode
+            .first { identifier, node in
+                identifier.isEquivalentIgnoringLanguage(to: reference)
+                && PageType.init(rawValue: node.item.pageType)?.isSymbolKind == false
+                && node.item.isExternal
+            }?.value
+        }
 
         /// Build the index using the render nodes files in the provided documentation archive.
         /// - Returns: A list containing all the errors encountered during indexing.

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -259,6 +259,7 @@ public class DocumentationContext {
             MissingAbstract(sourceFile: source).any(),
             NonOverviewHeadingChecker(sourceFile: source).any(),
             SeeAlsoInTopicsHeadingChecker(sourceFile: source).any(),
+            InvalidCodeBlockOption(sourceFile: source).any(),
         ])
         checker.visit(document)
         diagnosticEngine.emit(checker.problems)
@@ -2414,7 +2415,6 @@ public class DocumentationContext {
             }
         }
     }
-    
     /// A closure type getting the information about a reference in a context and returns any possible problems with it.
     public typealias ReferenceCheck = (DocumentationContext, ResolvedTopicReference) -> [Problem]
 
@@ -2697,6 +2697,11 @@ public class DocumentationContext {
         ).isSymbol
     }
 
+    /// Returns whether the given reference resolves to an external entity.
+    func isExternal(reference: ResolvedTopicReference) -> Bool {
+        externalCache[reference] != nil
+    }
+
     // MARK: - Relationship queries
 
     /// Fetch the child nodes of a documentation node with the given `reference`, optionally filtering to only children of the given `kind`.