Merge branch 'main' into same-shape

Author: d-ronnqvist

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:6.0
 /*
  This source file is part of the Swift.org open source project
 
@@ -15,6 +15,8 @@ import class Foundation.ProcessInfo
 let swiftSettings: [SwiftSetting] = [
     .unsafeFlags(["-Xfrontend", "-warn-long-expression-type-checking=1000"], .when(configuration: .debug)),
 
+    .swiftLanguageMode(.v5),
+    
     .enableUpcomingFeature("ConciseMagicFile"), // SE-0274: https://github.com/swiftlang/swift-evolution/blob/main/proposals/0274-magic-file.md
     .enableUpcomingFeature("ExistentialAny"), // SE-0335: https://github.com/swiftlang/swift-evolution/blob/main/proposals/0335-existential-any.md
     .enableUpcomingFeature("InternalImportsByDefault"), // SE-0409: https://github.com/swiftlang/swift-evolution/blob/main/proposals/0409-access-level-on-imports.md
@@ -23,8 +25,8 @@ let swiftSettings: [SwiftSetting] = [
 let package = Package(
     name: "SwiftDocC",
     platforms: [
-        .macOS(.v12),
-        .iOS(.v15)
+        .macOS(.v13),
+        .iOS(.v16)
     ],
     products: [
         .library(

Sources/SwiftDocC/Checker/Checkers/AbstractContainsFormattedTextOnly.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-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
@@ -14,6 +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.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/Converter/DocumentationContextConverter.swift

@@ -20,9 +20,6 @@ public class DocumentationContextConverter {
     /// The context the converter uses to resolve references it finds in the documentation node's content.
     let context: DocumentationContext
 
-    /// The bundle that contains the content from which the documentation node originated.
-    let bundle: DocumentationBundle
-    
     /// A context that contains common pre-rendered pieces of content.
     let renderContext: RenderContext
 
@@ -43,12 +40,11 @@ public class DocumentationContextConverter {
     /// The remote source control repository where the documented module's source is hosted.
     let sourceRepository: SourceRepository?
 
-    /// Creates a new node converter for the given bundle and context.
+    /// Creates a new node converter for the given context.
     ///
     /// The converter uses bundle and context to resolve references to other documentation and describe the documentation hierarchy.
     ///
     /// - Parameters:
-    ///   - bundle: The bundle that contains the content from which the documentation node originated.
     ///   - context: The context that the converter uses to to resolve references it finds in the documentation node's content.
     ///   - renderContext: A context that contains common pre-rendered pieces of content.
     ///   - emitSymbolSourceFileURIs: Whether the documentation converter should include
@@ -61,22 +57,39 @@ public class DocumentationContextConverter {
     ///   - sourceRepository: The source repository where the documentation's sources are hosted.
     ///   - symbolIdentifiersWithExpandedDocumentation: A list of symbol IDs that have version of their documentation page with more content that a renderer can link to.
     public init(
-        bundle: DocumentationBundle,
         context: DocumentationContext,
         renderContext: RenderContext,
         emitSymbolSourceFileURIs: Bool = false,
         emitSymbolAccessLevels: Bool = false,
         sourceRepository: SourceRepository? = nil,
         symbolIdentifiersWithExpandedDocumentation: [String]? = nil
     ) {
-        self.bundle = bundle
         self.context = context
         self.renderContext = renderContext
         self.shouldEmitSymbolSourceFileURIs = emitSymbolSourceFileURIs
         self.shouldEmitSymbolAccessLevels = emitSymbolAccessLevels
         self.sourceRepository = sourceRepository
         self.symbolIdentifiersWithExpandedDocumentation = symbolIdentifiersWithExpandedDocumentation
     }
+    @available(*, deprecated, renamed: "init(context:renderContext:emitSymbolSourceFileURIs:emitSymbolAccessLevels:sourceRepository:symbolIdentifiersWithExpandedDocumentation:)", message: "Use 'init(context:renderContext:emitSymbolSourceFileURIs:emitSymbolAccessLevels:sourceRepository:symbolIdentifiersWithExpandedDocumentation:)' instead. This deprecated API will be removed after 6.4 is released.")
+    public convenience init(
+        bundle _: DocumentationBundle,
+        context: DocumentationContext,
+        renderContext: RenderContext,
+        emitSymbolSourceFileURIs: Bool = false,
+        emitSymbolAccessLevels: Bool = false,
+        sourceRepository: SourceRepository? = nil,
+        symbolIdentifiersWithExpandedDocumentation: [String]? = nil
+    ) {
+        self.init(
+            context: context,
+            renderContext: renderContext,
+            emitSymbolSourceFileURIs: emitSymbolSourceFileURIs,
+            emitSymbolAccessLevels: emitSymbolAccessLevels,
+            sourceRepository: sourceRepository,
+            symbolIdentifiersWithExpandedDocumentation: symbolIdentifiersWithExpandedDocumentation
+        )
+    }
 
     /// Converts a documentation node to a render node.
     ///
@@ -91,7 +104,6 @@ public class DocumentationContextConverter {
 
         var translator = RenderNodeTranslator(
             context: context,
-            bundle: bundle,
             identifier: node.reference,
             renderContext: renderContext,
             emitSymbolSourceFileURIs: shouldEmitSymbolSourceFileURIs,

Sources/SwiftDocC/Converter/DocumentationNodeConverter.swift

@@ -15,20 +15,19 @@ public struct DocumentationNodeConverter {
     /// The context the converter uses to resolve references it finds in the documentation node's content.
     let context: DocumentationContext
 
-    /// The bundle that contains the content from which the documentation node originated.
-    let bundle: DocumentationBundle
-    
-    /// Creates a new node converter for the given bundle and context.
+    /// Creates a new node converter for the given context.
     ///
-    /// The converter uses bundle and context to resolve references to other documentation and describe the documentation hierarchy.
+    /// The converter uses context to resolve references to other documentation and describe the documentation hierarchy.
     ///
     /// - Parameters:
-    ///   - bundle: The bundle that contains the content from which the documentation node originated.
     ///   - context: The context that the converter uses to to resolve references it finds in the documentation node's content.
-    public init(bundle: DocumentationBundle, context: DocumentationContext) {
-        self.bundle = bundle
+    public init(context: DocumentationContext) {
         self.context = context
     }
+    @available(*, deprecated, renamed: "init(context:)", message: "Use 'init(context:)' instead. This deprecated API will be removed after 6.4 is released.")
+    public init(bundle _: DocumentationBundle, context: DocumentationContext) {
+        self.init(context: context)
+    }
 
     /// Converts a documentation node to a render node.
     ///
@@ -37,7 +36,7 @@ public struct DocumentationNodeConverter {
     ///   - node: The documentation node to convert.
     /// - Returns: The render node representation of the documentation node.
     public func convert(_ node: DocumentationNode) -> RenderNode {
-        var translator = RenderNodeTranslator(context: context, bundle: bundle, identifier: node.reference)
+        var translator = RenderNodeTranslator(context: context, identifier: node.reference)
         return translator.visit(node.semantic) as! RenderNode
     }
 }

Sources/SwiftDocC/DocumentationService/Convert/ConvertService.swift

@@ -158,7 +158,7 @@ public struct ConvertService: DocumentationService {
             let context = try await DocumentationContext(bundle: bundle, dataProvider: dataProvider, configuration: configuration)
 
             // Precompute the render context
-            let renderContext = RenderContext(documentationContext: context, bundle: bundle)
+            let renderContext = RenderContext(documentationContext: context)
 
             let symbolIdentifiersMeetingRequirementsForExpandedDocumentation: [String]? = request.symbolIdentifiersWithExpandedDocumentation?.compactMap { identifier, expandedDocsRequirement in
                 guard let documentationNode = context.documentationCache[identifier] else {
@@ -168,7 +168,6 @@ public struct ConvertService: DocumentationService {
                 return documentationNode.meetsExpandedDocumentationRequirements(expandedDocsRequirement) ? identifier : nil
             }
             let converter = DocumentationContextConverter(
-                bundle: bundle,
                 context: context,
                 renderContext: renderContext,
                 emitSymbolSourceFileURIs: request.emitSymbolSourceFileURIs,
@@ -243,12 +242,11 @@ public struct ConvertService: DocumentationService {
             .compactMap { (value, isDocumentationExtensionContent) -> (ResolvedTopicReference, RenderReferenceStore.TopicContent)? in
                 let (topicReference, article) = value
 
-                let bundle = context.bundle
-                guard bundle.id == topicReference.bundleID else { return nil }
-                let renderer = DocumentationContentRenderer(documentationContext: context, bundle: bundle)
+                guard context.inputs.id == topicReference.bundleID else { return nil }
+                let renderer = DocumentationContentRenderer(context: context)
 
                 let documentationNodeKind: DocumentationNode.Kind = isDocumentationExtensionContent ? .unknownSymbol : .article
-                let overridingDocumentationNode = DocumentationContext.documentationNodeAndTitle(for: article, kind: documentationNodeKind, in: bundle)?.node
+                let overridingDocumentationNode = DocumentationContext.documentationNodeAndTitle(for: article, kind: documentationNodeKind, in: context.inputs)?.node
                 var dependencies = RenderReferenceDependencies()
                 let renderReference = renderer.renderReference(for: topicReference, with: overridingDocumentationNode, dependencies: &dependencies)
 

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