Add support for custom scripts

Author: Lucca-mito

Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift

@@ -106,6 +106,10 @@ public struct DocumentationBundle {
 
     /// A custom JSON settings file used to theme renderer output.
     public let themeSettings: URL?
+    
+    /// A custom JSON settings file used to add custom scripts to the renderer output.
+    public let customScripts: URL?
+
     /// A URL prefix to be appended to the relative presentation URL.
     ///
     /// This is used when a built documentation is hosted in a known location.
@@ -122,6 +126,7 @@ public struct DocumentationBundle {
     ///   - customHeader: A custom HTML file to use as the header for rendered output.
     ///   - customFooter: A custom HTML file to use as the footer for rendered output.
     ///   - themeSettings: A custom JSON settings file used to theme renderer output.
+    ///   - customScripts: A custom JSON settings file used to add custom scripts to the renderer output.
     public init(
         info: Info,
         baseURL: URL = URL(string: "/")!,
@@ -130,7 +135,8 @@ public struct DocumentationBundle {
         miscResourceURLs: [URL],
         customHeader: URL? = nil,
         customFooter: URL? = nil,
-        themeSettings: URL? = nil
+        themeSettings: URL? = nil,
+        customScripts: URL? = nil
     ) {
         self.info = info
         self.baseURL = baseURL
@@ -140,6 +146,7 @@ public struct DocumentationBundle {
         self.customHeader = customHeader
         self.customFooter = customFooter
         self.themeSettings = themeSettings
+        self.customScripts = customScripts
         self.rootReference = ResolvedTopicReference(bundleID: info.id, path: "/", sourceLanguage: .swift)
         self.documentationRootReference = ResolvedTopicReference(bundleID: info.id, path: NodeURLGenerator.Path.documentationFolder, sourceLanguage: .swift)
         self.tutorialTableOfContentsContainer = ResolvedTopicReference(bundleID: info.id, path: NodeURLGenerator.Path.tutorialsFolder, sourceLanguage: .swift)

Sources/SwiftDocC/Infrastructure/DocumentationBundleFileTypes.swift

@@ -84,4 +84,12 @@ public enum DocumentationBundleFileTypes {
     public static func isThemeSettingsFile(_ url: URL) -> Bool {
         return url.lastPathComponent == themeSettingsFileName
     }
+    
+    private static let customScriptsFileName = "custom-scripts.json"
+    /// Checks if a file is `custom-scripts.json`.
+    /// - Parameter url: The file to check.
+    /// - Returns: Whether or not the file at `url` is `custom-scripts.json`.
+    public static func isCustomScriptsFile(_ url: URL) -> Bool {
+        return url.lastPathComponent == customScriptsFileName
+    }
 }

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -1783,6 +1783,7 @@ public class DocumentationContext {
 
     private static let supportedImageExtensions: Set<String> = ["png", "jpg", "jpeg", "svg", "gif"]
     private static let supportedVideoExtensions: Set<String> = ["mov", "mp4"]
+    private static let supportedScriptExtensions: Set<String> = ["js"]
 
     // TODO: Move this functionality to ``DocumentationBundleFileTypes`` (rdar://68156425).
 
@@ -1839,7 +1840,7 @@ public class DocumentationContext {
         }
     }
 
-    /// Returns a list of all the image assets that registered for a given `bundleIdentifier`.
+    /// Returns a list of all the image assets that registered for a given `bundleID`.
     ///
     /// - Parameter bundleID: The identifier of the bundle to return image assets for.
     /// - Returns: A list of all the image assets for the given bundle.
@@ -1852,7 +1853,7 @@ public class DocumentationContext {
         registeredImageAssets(for: DocumentationBundle.Identifier(rawValue: bundleIdentifier))
     }
 
-    /// Returns a list of all the video assets that registered for a given `bundleIdentifier`.
+    /// Returns a list of all the video assets that registered for a given `bundleID`.
     ///
     /// - Parameter bundleID: The identifier of the bundle to return video assets for.
     /// - Returns: A list of all the video assets for the given bundle.
@@ -1865,7 +1866,7 @@ public class DocumentationContext {
         registeredVideoAssets(for: DocumentationBundle.Identifier(rawValue: bundleIdentifier))
     }
 
-    /// Returns a list of all the download assets that registered for a given `bundleIdentifier`.
+    /// Returns a list of all the download assets that registered for a given `bundleID`.
     ///
     /// - Parameter bundleID: The identifier of the bundle to return download assets for.
     /// - Returns: A list of all the download assets for the given bundle.
@@ -1877,6 +1878,14 @@ public class DocumentationContext {
     public func registeredDownloadsAssets(forBundleID bundleIdentifier: BundleIdentifier) -> [DataAsset] {
         registeredDownloadsAssets(for: DocumentationBundle.Identifier(rawValue: bundleIdentifier))
     }
+    
+    /// Returns a list of all the custom scripts that registered for a given `bundleID`.
+    ///
+    /// - Parameter bundleID: The identifier of the bundle to return custom scripts for.
+    /// - Returns: A list of all the custom scripts for the given bundle.
+    public func registeredCustomScripts(for bundleID: DocumentationBundle.Identifier) -> [DataAsset] {
+        return registeredAssets(withExtensions: DocumentationContext.supportedScriptExtensions, forBundleID: bundleID)
+    }
 
     typealias Articles = [DocumentationContext.SemanticResult<Article>]
     private typealias ArticlesTuple = (articles: Articles, rootPageArticles: Articles)

Sources/SwiftDocC/Infrastructure/Input Discovery/DocumentationInputsProvider.swift

@@ -25,6 +25,7 @@ extension DocumentationContext {
     ///  ``DocumentationBundle/symbolGraphURLs``  | ``DocumentationBundleFileTypes/isSymbolGraphFile(_:)``
     ///  ``DocumentationBundle/info``             | ``DocumentationBundleFileTypes/isInfoPlistFile(_:)``
     ///  ``DocumentationBundle/themeSettings``    | ``DocumentationBundleFileTypes/isThemeSettingsFile(_:)``
+    ///  ``DocumentationBundle/customScripts``    | ``DocumentationBundleFileTypes/isCustomScriptsFile(_:)``
     ///  ``DocumentationBundle/customHeader``     | ``DocumentationBundleFileTypes/isCustomHeader(_:)``
     ///  ``DocumentationBundle/customFooter``     | ``DocumentationBundleFileTypes/isCustomFooter(_:)``
     ///  ``DocumentationBundle/miscResourceURLs`` | Any file not already matched above.
@@ -165,7 +166,8 @@ extension DocumentationContext.InputsProvider {
             miscResourceURLs: foundContents.resources,
             customHeader:  shallowContent.first(where: FileTypes.isCustomHeader),
             customFooter:  shallowContent.first(where: FileTypes.isCustomFooter),
-            themeSettings: shallowContent.first(where: FileTypes.isThemeSettingsFile)
+            themeSettings: shallowContent.first(where: FileTypes.isThemeSettingsFile),
+            customScripts: shallowContent.first(where: FileTypes.isCustomScriptsFile)
         )
     }
 

Sources/SwiftDocC/Infrastructure/Workspace/LocalFileSystemDataProvider+BundleDiscovery.swift

@@ -83,6 +83,7 @@ extension LocalFileSystemDataProvider: DocumentationWorkspaceDataProvider {
         let customHeader = findCustomHeader(bundleChildren)?.url
         let customFooter = findCustomFooter(bundleChildren)?.url
         let themeSettings = findThemeSettings(bundleChildren)?.url
+        let customScripts = findCustomScripts(bundleChildren)?.url
 
         return DocumentationBundle(
             info: info,
@@ -91,7 +92,8 @@ extension LocalFileSystemDataProvider: DocumentationWorkspaceDataProvider {
             miscResourceURLs: miscResources,
             customHeader: customHeader,
             customFooter: customFooter,
-            themeSettings: themeSettings
+            themeSettings: themeSettings,
+            customScripts: customScripts
         )
     }
 
@@ -140,6 +142,10 @@ extension LocalFileSystemDataProvider: DocumentationWorkspaceDataProvider {
     private func findThemeSettings(_ bundleChildren: [FSNode]) -> FSNode.File? {
         return bundleChildren.firstFile { DocumentationBundleFileTypes.isThemeSettingsFile($0.url) }
     }
+    
+    private func findCustomScripts(_ bundleChildren: [FSNode]) -> FSNode.File? {
+        return bundleChildren.firstFile { DocumentationBundleFileTypes.isCustomScriptsFile($0.url) }
+    }
 }
 
 @available(*, deprecated, message: "This deprecated API will be removed after 6.2 is released.")

Sources/SwiftDocC/SwiftDocC.docc/Resources/CustomScripts.spec.json

@@ -0,0 +1,98 @@
+{
+    "openapi": "3.0.0",
+    "info": {
+        "title": "Custom Scripts",
+        "description": "This spec describes the permissible contents of a custom-scripts.json file in a documentation catalog, which is used to add custom scripts to a DocC-generated website.",
+        "version": "0.0.1"
+    },
+    "paths": {},
+    "components": {
+        "schemas": {
+            "Scripts": {
+                "type": "array",
+                "description": "An array of custom scripts, which is the top-level container in a custom-scripts.json file.",
+                "items": {
+                    "oneOf": [
+                        { "$ref": "#/components/schemas/ExternalScript" },
+                        { "$ref": "#/components/schemas/LocalScript" },
+                        { "$ref": "#/components/schemas/InlineScript" }
+                    ]
+                }
+            },
+            "Script": {
+                "type": "object",
+                "description": "An abstract schema representing any script, from which all three script types inherit.",
+                "properties": {
+                    "type": {
+                        "type": "string",
+                        "description": "The `type` attribute of the HTML script element."
+                    },
+                    "run": {
+                        "type": "string",
+                        "enum": ["on-load", "on-navigate", "on-load-and-navigate"],
+                        "description": "Whether the custom script should be run only on the initial page load, each time the reader navigates after the initial page load, or both."
+                    }
+                }
+            },
+            "ScriptFromFile": {
+                "description": "An abstract schema representing a script from an external or local file; that is, not an inline script.",
+                "allOf": [
+                    { "$ref": "#/components/schemas/Script" },
+                    {
+                        "properties": {
+                            "async": { "type": "boolean" },
+                            "defer": { "type": "boolean" }
+                        }
+                    }
+                ]
+            },
+            "ExternalScript": {
+                "description": "A script at an external URL.",
+                "allOf": [
+                    { "$ref": "#/components/schemas/ScriptFromFile" },
+                    {
+                        "required": ["url"],
+                        "properties": {
+                            "url": { "type": "string" },
+                            "integrity": { "type": "string" }
+                        }
+                    }
+                ]
+            },
+            "LocalScript": {
+                "description": "A script from a local file.",
+                "allOf": [
+                    { "$ref": "#/components/schemas/ScriptFromFile" },
+                    {
+                        "required": ["name"],
+                        "properties": {
+                            "name": {
+                                "type": "string",
+                                "description": "The name of the local script file, optionally including the '.js' extension."
+                            },
+                        }
+                    }
+                ]
+            },
+            "InlineScript": {
+                "description": "A script whose source code is in the custom-scripts.json file itself.",
+                "allOf": [
+                    { "$ref": "#/components/schemas/Script" },
+                    {
+                        "required": ["code"],
+                        "properties": {
+                            "code": {
+                                "type": "string",
+                                "description": "The source code of the inline script."
+                            }
+                        }
+                    }
+                ]
+            }
+        },
+        "requestBodies": {},
+        "securitySchemes": {},
+        "links": {},
+        "callbacks": {}
+    }
+}

Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertFileWritingConsumer.swift

@@ -126,6 +126,18 @@ struct ConvertFileWritingConsumer: ConvertOutputConsumer, ExternalNodeConsumer {
         for downloadAsset in context.registeredDownloadsAssets(for: bundleID) {
             try copyAsset(downloadAsset, to: downloadsDirectory)
         }
+        
+        // Create custom scripts directory if needed. Do not append the bundle identifier.
+        let scriptsDirectory = targetFolder
+            .appendingPathComponent("custom-scripts", isDirectory: true)
+        if !fileManager.directoryExists(atPath: scriptsDirectory.path) {
+            try fileManager.createDirectory(at: scriptsDirectory, withIntermediateDirectories: true, attributes: nil)
+        }
+        
+        // Copy all registered custom scripts to the output directory.
+        for customScript in context.registeredCustomScripts(for: bundleID) {
+            try copyAsset(customScript, to: scriptsDirectory)
+        }
 
         // If the bundle contains a `header.html` file, inject a <template> into
         // the `index.html` file using its contents. This will only be done if
@@ -151,6 +163,16 @@ struct ConvertFileWritingConsumer: ConvertOutputConsumer, ExternalNodeConsumer {
             }
             try fileManager._copyItem(at: themeSettings, to: targetFile)
         }
+        
+        // Copy the `custom-scripts.json` file into the output directory if one
+        // is provided.
+        if let customScripts = bundle.customScripts {
+            let targetFile = targetFolder.appendingPathComponent(customScripts.lastPathComponent, isDirectory: false)
+            if fileManager.fileExists(atPath: targetFile.path) {
+                try fileManager.removeItem(at: targetFile)
+            }
+            try fileManager._copyItem(at: customScripts, to: targetFile)
+        }
     }
 
     func consume(linkableElementSummaries summaries: [LinkDestinationSummary]) throws {

Sources/SwiftDocCUtilities/PreviewServer/RequestHandler/FileRequestHandler.swift

@@ -107,6 +107,7 @@ struct FileRequestHandler: RequestHandlerFactory {
         TopLevelAssetFileMetadata(filePath: "/favicon.ico", mimetype: "image/x-icon"),
         TopLevelAssetFileMetadata(filePath: "/theme-settings.js", mimetype: "text/javascript"),
         TopLevelAssetFileMetadata(filePath: "/theme-settings.json", mimetype: "application/json"),
+        TopLevelAssetFileMetadata(filePath: "/custom-scripts.json", mimetype: "application/json"),
     ]
 
     /// Returns a Boolean value that indicates whether the given path is located inside an asset folder.

Tests/SwiftDocCTests/Infrastructure/DocumentationBundleFileTypesTests.swift

@@ -13,46 +13,51 @@ import XCTest
 
 class DocumentationBundleFileTypesTests: XCTestCase {
     func testIsCustomHeader() {
-        XCTAssertTrue(DocumentationBundleFileTypes.isCustomHeader(
-            URL(fileURLWithPath: "header.html")))
-        XCTAssertTrue(DocumentationBundleFileTypes.isCustomHeader(
-            URL(fileURLWithPath: "/header.html")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isCustomHeader(
-            URL(fileURLWithPath: "header")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isCustomHeader(
-            URL(fileURLWithPath: "/header.html/foo")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isCustomHeader(
-            URL(fileURLWithPath: "footer.html")))
-        XCTAssertTrue(DocumentationBundleFileTypes.isCustomHeader(
-            URL(fileURLWithPath: "DocC.docc/header.html")))
+        assertThat(DocumentationBundleFileTypes.isCustomHeader, matchesFilesNamed: "header", withExtension: "html")
     }
 
     func testIsCustomFooter() {
-        XCTAssertTrue(DocumentationBundleFileTypes.isCustomFooter(
-            URL(fileURLWithPath: "footer.html")))
-        XCTAssertTrue(DocumentationBundleFileTypes.isCustomFooter(
-            URL(fileURLWithPath: "/footer.html")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isCustomFooter(
-            URL(fileURLWithPath: "footer")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isCustomFooter(
-            URL(fileURLWithPath: "/footer.html/foo")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isCustomFooter(
-            URL(fileURLWithPath: "header.html")))
-        XCTAssertTrue(DocumentationBundleFileTypes.isCustomFooter(
-            URL(fileURLWithPath: "DocC.docc/footer.html")))
+        assertThat(DocumentationBundleFileTypes.isCustomFooter, matchesFilesNamed: "footer", withExtension: "html")
     }
 
     func testIsThemeSettingsFile() {
-        XCTAssertTrue(DocumentationBundleFileTypes.isThemeSettingsFile(
-            URL(fileURLWithPath: "theme-settings.json")))
-        XCTAssertTrue(DocumentationBundleFileTypes.isThemeSettingsFile(
-            URL(fileURLWithPath: "/a/b/theme-settings.json")))
-
-        XCTAssertFalse(DocumentationBundleFileTypes.isThemeSettingsFile(
-            URL(fileURLWithPath: "theme-settings.txt")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isThemeSettingsFile(
-            URL(fileURLWithPath: "not-theme-settings.json")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isThemeSettingsFile(
-            URL(fileURLWithPath: "/a/theme-settings.json/bar")))
+        assertThat(DocumentationBundleFileTypes.isThemeSettingsFile, matchesFilesNamed: "theme-settings", withExtension: "json")
+    }
+    
+    func testIsCustomScriptsFile() {
+        assertThat(DocumentationBundleFileTypes.isCustomScriptsFile, matchesFilesNamed: "custom-scripts", withExtension: "json")
+    }
+    
+    private func assertThat(
+        _ predicate: (URL) -> Bool,
+        matchesFilesNamed fileName: String,
+        withExtension extension: String,
+        file: StaticString = #filePath,
+        line: UInt = #line
+    ) {
+        let fileNameWithExtension = "\(fileName).\(`extension`)"
+        
+        let pathsThatShouldMatch = [
+            fileNameWithExtension,
+            "/\(fileNameWithExtension)",
+            "DocC/docc/\(fileNameWithExtension)",
+            "/a/b/\(fileNameWithExtension)"
+        ].map { URL(fileURLWithPath: $0) }
+        
+        let pathsThatShouldNotMatch = [
+            fileName,
+            "/\(fileNameWithExtension)/foo",
+            "/a/\(fileNameWithExtension)/bar",
+            "\(fileName).wrongextension",
+            "wrongname.\(`extension`)"
+        ].map { URL(fileURLWithPath: $0) }
+        
+        for url in pathsThatShouldMatch {
+            XCTAssertTrue(predicate(url), file: file, line: line)
+        }
+        
+        for url in pathsThatShouldNotMatch {
+            XCTAssertFalse(predicate(url), file: file, line: line)
+        }
     }
 }