Emit RenderIndex JSON by default (#100)

Removes the feature flag gating emitting RenderIndex JSON so that the
JSON representation of the navigator index is emitted during every conversion
of documentation by default.

Also bumps the RenderNode minor version to `0.3.0` so that clients of Swift-DocC
archives can detect based on the RenderNode version if a given DocC archive
will contain an `index.json` file.

Resolves rdar://89003698.

Author: ethan-kusters

Sources/SwiftDocC/Model/Rendering/RenderNode.swift

@@ -109,7 +109,7 @@ public struct RenderNode: VariantContainer {
     /// > Note: The patch value is currently unused and always set to `0`.
     public var schemaVersion = SemanticVersion(
         major: 0,
-        minor: 2,
+        minor: 3,
         patch: 0
     )
 

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

@@ -2,7 +2,7 @@
     "openapi": "3.0.0",
     "info": {
         "description": "Render Node API",
-        "version": "0.2.0",
+        "version": "0.3.0",
         "title": "Render Node API"
     },
     "paths": { },

Sources/SwiftDocC/Utility/FeatureFlags.swift

@@ -22,28 +22,21 @@ public struct FeatureFlags: Codable {
 
     /// Whether or not experimental support for emitting a JSON representation of the converted
     /// documentation's navigator index is enabled.
-    ///
-    /// This can be enabled on the command-line by passing `--enable-experimental-json-index`.
-    /// to docc.
-    public var isExperimentalJSONIndexEnabled = false
+    @available(*, deprecated, message: "Render Index JSON is now emitted by default.")
+    public var isExperimentalJSONIndexEnabled = true
 
     /// Creates a set of feature flags with the given values.
     ///
     /// - Parameters:
     ///   - enableObjectiveCSupport: Whether or not experimental language support for Objective-C should be enabled.
     ///
-    ///   - enableExperimentalJSONIndex: Whether or not experimental support for emitting a JSON
-    ///     representation of the navigator index should be enabled.
-    ///
     ///   - additionalFlags: Any additional flags to set.
     ///
     ///     This field allows clients to set feature flags without adding new API.
     public init(
         enableExperimentalObjectiveCSupport: Bool = false,
-        enableExperimentalJSONIndex: Bool = false,
         additionalFlags: [String : Bool] = [:]
     ) {
         self.isExperimentalObjectiveCSupportEnabled = enableExperimentalObjectiveCSupport
-        self.isExperimentalJSONIndexEnabled = enableExperimentalJSONIndex
     }
 }

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

@@ -34,7 +34,7 @@ public struct ConvertAction: Action, RecreatingContext {
     let emitDigest: Bool
     let inheritDocs: Bool
     let experimentalEnableCustomTemplates: Bool
-    let buildIndex: Bool
+    let buildLMDBIndex: Bool
     let documentationCoverageOptions: DocumentationCoverageOptions
     let diagnosticLevel: DiagnosticSeverity
     let diagnosticEngine: DiagnosticEngine
@@ -72,6 +72,10 @@ public struct ConvertAction: Action, RecreatingContext {
     private var durationMetric: Benchmark.Duration?
 
     /// Initializes the action with the given validated options, creates or uses the given action workspace & context.
+    /// - Parameter buildIndex: Whether or not the convert action should emit an LMDB representation
+    ///   of the navigator index.
+    ///
+    ///   A JSON representation is built and emitted regardless of this value.
     /// - Parameter workspace: A provided documentation workspace. Creates a new empty workspace if value is `nil`
     /// - Parameter context: A provided documentation context. Creates a new empty context in the workspace if value is `nil`
     /// - Parameter dataProvider: A data provider to use when registering bundles
@@ -105,7 +109,7 @@ public struct ConvertAction: Action, RecreatingContext {
         self.targetDirectory = targetDirectory
         self.htmlTemplateDirectory = htmlTemplateDirectory
         self.emitDigest = emitDigest
-        self.buildIndex = buildIndex
+        self.buildLMDBIndex = buildIndex
         self.workspace = workspace
         self.injectedDataProvider = dataProvider
         self.fileManager = fileManager
@@ -330,8 +334,7 @@ public struct ConvertAction: Action, RecreatingContext {
         // An optional indexer, if indexing while converting is enabled.
         var indexer: Indexer? = nil
 
-        let shouldBuildIndex = buildIndex || FeatureFlags.current.isExperimentalJSONIndexEnabled
-        if shouldBuildIndex, let bundleIdentifier = converter.firstAvailableBundle()?.identifier {
+        if let bundleIdentifier = converter.firstAvailableBundle()?.identifier {
             // Create an index builder and prepare it to receive nodes.
             indexer = try Indexer(outputURL: temporaryFolder, bundleIdentifier: bundleIdentifier)
         }
@@ -367,10 +370,9 @@ public struct ConvertAction: Action, RecreatingContext {
 
         // If we're building a navigation index, finalize the process and collect encountered problems.
         if let indexer = indexer {
-            let indexerProblems = indexer.finalize(
-                emitJSON: FeatureFlags.current.isExperimentalJSONIndexEnabled,
-                emitLMDB: buildIndex
-            )
+            // Always emit a JSON representation of the index but only emit the LMDB
+            // index if the user has explicitly opted in with the `--emit-lmdb-index` flag.
+            let indexerProblems = indexer.finalize(emitJSON: true, emitLMDB: buildLMDBIndex)
             allProblems.append(contentsOf: indexerProblems)
         }
 

Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift

@@ -21,7 +21,6 @@ extension ConvertAction {
         let outOfProcessResolver: OutOfProcessReferenceResolver?
 
         FeatureFlags.current.isExperimentalObjectiveCSupportEnabled = convert.enableExperimentalObjectiveCSupport
-        FeatureFlags.current.isExperimentalJSONIndexEnabled = convert.enableExperimentalJSONIndex
 
         // If the user-provided a URL for an external link resolver, attempt to
         // initialize an `OutOfProcessReferenceResolver` with the provided URL.
@@ -72,7 +71,7 @@ extension ConvertAction {
             htmlTemplateDirectory: convert.templateOption.templateURL ?? fallbackTemplateURL,
             emitDigest: convert.emitDigest,
             currentPlatforms: parsedPlatforms,
-            buildIndex: convert.index,
+            buildIndex: convert.emitLMDBIndex || convert.index,
             temporaryDirectory: FileManager.default.temporaryDirectory,
             documentationCoverageOptions: DocumentationCoverageOptions(
                 from: convert.experimentalDocumentationCoverageOptions

Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift

@@ -82,10 +82,21 @@ extension Docc {
         @Flag(help: "Writes additional metadata files to the output directory.")
         public var emitDigest = false
 
-        /// A user-provided value that is true if the navigator index should be produced.
+        /// A user-provided value that is true if the LMDB representation of the
+        /// navigator index should be produced.
         ///
         /// Defaults to false.
-        @Flag(help: "Writes the navigator index to the output directory.")
+        @Flag(
+            help: ArgumentHelp(
+                "Writes an LMDB representation of the navigator index to the output directory.",
+                discussion: "A JSON representation of the navigator index is emitted by default."
+            )
+        )
+        public var emitLMDBIndex = false
+        
+        /// This value is provided for backwards compatibility with existing clients but
+        /// will be removed soon. Renamed to '--emit-lmdb-index'.
+        @Flag(help: .hidden)
         public var index = false
 
         /// A user-provided value that is true if fix-its should be written to output.
@@ -115,8 +126,10 @@ extension Docc {
         /// A user-provided value that is true if the user enables experimental support for emitting
         /// a JSON index.
         ///
-        /// Defaults to false.
+        /// This property exists for backwards compatibility with existing clients but is
+        /// deprecated and will be removed soon.
         @Flag(help: .hidden)
+        @available(*, deprecated, message: "Render Index JSON is now emitted by default.")
         public var enableExperimentalJSONIndex = false
 
         /// A user-provided value that is true if experimental documentation inheritance is to be enabled.

Tests/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.swift

@@ -294,7 +294,20 @@ class ConvertSubcommandTests: XCTestCase {
 
         let action = try ConvertAction(fromConvertCommand: convertOptions)
 
-        XCTAssertEqual(action.buildIndex, true)
+        XCTAssertEqual(action.buildLMDBIndex, true)
+    }
+    
+    func testEmitLMDBIndex() throws {
+        let convertOptions = try Docc.Convert.parse([
+            testBundleURL.path,
+            "--emit-lmdb-index",
+        ])
+        
+        XCTAssertTrue(convertOptions.emitLMDBIndex)
+        
+        let action = try ConvertAction(fromConvertCommand: convertOptions)
+        
+        XCTAssertTrue(action.buildLMDBIndex)
     }
 
     func testWithoutBundle() throws {

Tests/SwiftDocCUtilitiesTests/ConvertActionStaticHostableTests.swift

@@ -48,7 +48,7 @@ class ConvertActionStaticHostableTests: StaticHostingBaseTests {
         _ = try action.perform(logHandle: .standardOutput)
 
         // Test the content of the output folder.
-        var expectedContent = ["data", "documentation", "tutorials", "downloads", "images", "metadata.json" ,"videos", "index.html"]
+        var expectedContent = ["data", "documentation", "tutorials", "downloads", "images", "metadata.json" ,"videos", "index.html", "index"]
         expectedContent += templateFolder.content.filter { $0 is Folder }.map{ $0.name }
 
         let output = try fileManager.contentsOfDirectory(atPath: targetBundleURL.path)

Tests/SwiftDocCUtilitiesTests/ConvertActionTests.swift

@@ -2298,8 +2298,6 @@ class ConvertActionTests: XCTestCase {
         let indexDirectory = targetDirectory.appendingPathComponent("index", isDirectory: true)
         let renderIndexJSON = indexDirectory.appendingPathComponent("index.json", isDirectory: false)
 
-        enableFeatureFlag(\.isExperimentalJSONIndexEnabled)
-        
         try action.performAndHandleResult()
         XCTAssertTrue(FileManager.default.directoryExists(atPath: indexDirectory.path))
         XCTAssertTrue(FileManager.default.fileExists(atPath: renderIndexJSON.path))