Make snippet-extract take individual input/output files instead of a directory (#39)

bitjammer · web-flow · commit e013865138b5 · 2022-12-16T13:39:22.000-08:00
This does not change the experience for package authors but allows for better
integration with other tools that require sandboxing of file access.

rdar://103034070
diff --git a/Package.swift b/Package.swift
@@ -56,6 +56,7 @@ let package = Package(
             dependencies: [
                 "Snippets",
                 "SwiftDocCPluginUtilities",
+                "snippet-extract",
             ],
             resources: [
                 .copy("Test Fixtures"),
diff --git a/Sources/SwiftDocCPluginUtilities/Snippets/SnippetExtractor.swift b/Sources/SwiftDocCPluginUtilities/Snippets/SnippetExtractor.swift
@@ -15,7 +15,7 @@ public class SnippetExtractor {
     
     enum SymbolGraphExtractionResult {
         case packageDoesNotProduceSnippets
-        case packageContainsSnippets(symbolGraphDirectory: URL)
+        case packageContainsSnippets(symbolGraphFile: URL)
     }
     
     private let snippetTool: URL
@@ -65,6 +65,27 @@ public class SnippetExtractor {
     var _fileExists: (_ path: String) -> Bool = { path in
         return FileManager.default.fileExists(atPath: path)
     }
+
+    /// Returns all of the `.swift` files under a directory recursively.
+    ///
+    /// Provided for testing.
+    var _findSnippetFilesInDirectory: (_ directory: URL) -> [String] = { directory -> [String] in
+        guard let snippetEnumerator = FileManager.default.enumerator(at: directory,
+                                                                     includingPropertiesForKeys: nil,
+                                                                     options: [.skipsHiddenFiles]) else {
+            return []
+
+        }
+        var snippetInputFiles = [String]()
+        for case let potentialSnippetURL as URL in snippetEnumerator {
+            guard potentialSnippetURL.pathExtension.lowercased() == "swift" else {
+                continue
+            }
+            snippetInputFiles.append(potentialSnippetURL.path)
+        }
+
+        return snippetInputFiles
+    }
     
     /// Generate snippets for the given package.
     ///
@@ -79,16 +100,15 @@ public class SnippetExtractor {
     ///     The snippet extractor will look for a `Snippets` subdirectory
     ///     within this directory.
     ///
-    /// - Returns: A URL for the directory containing the generated snippets or nil if
-    ///   no snippets were produced.
+    /// - Returns: A URL for the output file of the generated snippets symbol graph JSON file.
     public func generateSnippets(
         for packageIdentifier: PackageIdentifier,
         packageDisplayName: String,
         packageDirectory: URL
     ) throws -> URL? {
         switch snippetSymbolGraphExtractionResults[packageIdentifier] {
-        case .packageContainsSnippets(symbolGraphDirectory: let symbolGraphDirectory):
-            return symbolGraphDirectory
+        case .packageContainsSnippets(symbolGraphFile: let symbolGraphFile):
+            return symbolGraphFile
         case .packageDoesNotProduceSnippets:
             return nil
         case .none:
@@ -100,26 +120,34 @@ public class SnippetExtractor {
             snippetSymbolGraphExtractionResults[packageIdentifier] = .packageDoesNotProduceSnippets
             return nil
         }
+
+        let snippetInputFiles = _findSnippetFilesInDirectory(snippetsDirectory)
+
+        guard !snippetInputFiles.isEmpty else {
+            snippetSymbolGraphExtractionResults[packageIdentifier] = .packageDoesNotProduceSnippets
+            return nil
+        }
         
         let outputDirectory = snippetsOutputDirectory(
             in: workingDirectory,
             packageIdentifier: packageIdentifier,
             packageDisplayName: packageDisplayName
         )
+
+        let outputFile = outputDirectory.appendingPathComponent("\(packageDisplayName)-snippets.symbols.json")
         
         let process = Process()
         process.executableURL = snippetTool
         process.arguments = [
-            snippetsDirectory.path,
-            outputDirectory.path,
-            packageDisplayName,
-        ]
-        
+            "--output", outputFile.path,
+            "--module-name", packageDisplayName,
+        ] + snippetInputFiles
+
         try _runProcess(process)
         
-        if _fileExists(outputDirectory.path) {
-            snippetSymbolGraphExtractionResults[packageIdentifier] = .packageContainsSnippets(symbolGraphDirectory: outputDirectory)
-            return outputDirectory
+        if _fileExists(outputFile.path) {
+            snippetSymbolGraphExtractionResults[packageIdentifier] = .packageContainsSnippets(symbolGraphFile: outputFile)
+            return outputFile
         } else {
             snippetSymbolGraphExtractionResults[packageIdentifier] = .packageDoesNotProduceSnippets
             return nil
diff --git a/Sources/snippet-extract/SnippetBuildCommand.swift b/Sources/snippet-extract/SnippetBuildCommand.swift
@@ -12,32 +12,92 @@ import SymbolKit
 
 @main
 struct SnippetExtractCommand {
-    var snippetsDir: String
-    var outputDir: String
+    enum OptionName: String {
+        case moduleName = "--module-name"
+        case outputFile = "--output"
+    }
+
+    enum Argument {
+        case moduleName(String)
+        case outputFile(String)
+        case inputFile(String)
+    }
+
+    enum ArgumentError: Error, CustomStringConvertible {
+        case missingOption(OptionName)
+        case missingOptionValue(OptionName)
+        case snippetNotContainedInSnippetsDirectory(URL)
+
+        var description: String {
+            switch self {
+            case .missingOption(let optionName):
+                return "Missing required option \(optionName.rawValue)"
+            case .missingOptionValue(let optionName):
+                return "Missing required option value for \(optionName.rawValue)"
+            case .snippetNotContainedInSnippetsDirectory(let snippetFileURL):
+                return "Snippet file '\(snippetFileURL.path)' is not contained in a directory called 'Snippets' at any level, so this tool is not able to compute the path components that would be used for linking to the snippet. It may exist in a subdirectory, but one of its parent directories must be named 'Snippets'."
+            }
+        }
+    }
+
+    var snippetFiles = [String]()
+    var outputFile: String
     var moduleName: String
 
     static func printUsage() {
         let usage = """
-            USAGE: snippet-extract <snippet directory> <output directory> <module name>
+            USAGE: snippet-extract --output <output file> --module-name <module name> <input files>
 
             ARGUMENTS:
-                <snippet directory> - The directory containing Swift snippets
-                <output directory> - The diretory in which to place Symbol Graph JSON file(s) representing the snippets
-                <module name> - The module name to use for the Symbol Graph (typically should be the package name)
+                <output file> (Required)
+                    The path of the output Symbol Graph JSON file representing the snippets for the a module or package
+                <module name> (Required)
+                    The module name to use for the Symbol Graph (typically should be the package name)
+                <input files>
+                    One or more absolute paths to snippet files to interpret as snippets
             """
         print(usage)
     }
 
+    init(arguments: [String]) throws {
+        var arguments = arguments
+
+        var parsedOutputFile: String? = nil
+        var parsedModuleName: String? = nil
+
+        while let argument = try arguments.parseSnippetArgument() {
+            switch argument {
+            case .inputFile(let inputFile):
+                snippetFiles.append(inputFile)
+            case .moduleName(let moduleName):
+                parsedModuleName = moduleName
+            case .outputFile(let outputFile):
+                parsedOutputFile = outputFile
+            }
+        }
+
+        guard let parsedOutputFile else {
+            throw ArgumentError.missingOption(.outputFile)
+        }
+        self.outputFile = parsedOutputFile
+
+        guard let parsedModuleName else {
+            throw ArgumentError.missingOption(.moduleName)
+        }
+        self.moduleName = parsedModuleName
+    }
+
     func run() throws {
-        let snippets = try loadSnippets(from: URL(fileURLWithPath: snippetsDir))
+        let snippets = try snippetFiles.map {
+            try Snippet(parsing: URL(fileURLWithPath: $0))
+        }
         guard snippets.count > 0 else { return }
-        let symbolGraphFilename = URL(fileURLWithPath: outputDir)
-            .appendingPathComponent("\(moduleName)-snippets.symbols.json")
+        let symbolGraphFilename = URL(fileURLWithPath: outputFile)
         try emitSymbolGraph(for: snippets, to: symbolGraphFilename, moduleName: moduleName)
     }
 
     func emitSymbolGraph(for snippets: [Snippet], to emitFilename: URL, moduleName: String) throws {
-        let snippetSymbols = snippets.map { SymbolGraph.Symbol($0, moduleName: moduleName, inDirectory: URL(fileURLWithPath: snippetsDir).absoluteURL) }
+        let snippetSymbols = try snippets.map { try SymbolGraph.Symbol($0, moduleName: moduleName) }
         let metadata = SymbolGraph.Metadata(formatVersion: .init(major: 0, minor: 1, patch: 0), generator: "snippet-extract")
         let module = SymbolGraph.Module(name: moduleName, platform: .init(architecture: nil, vendor: nil, operatingSystem: nil, environment: nil), isVirtual: true)
         let symbolGraph = SymbolGraph(metadata: metadata, module: module, symbols: snippetSymbols, relationships: [])
@@ -72,28 +132,42 @@ struct SnippetExtractCommand {
             .filter { $0.isDirectory }
     }
 
-    func loadSnippets(from snippetsDirectory: URL) throws -> [Snippet] {
-        guard snippetsDirectory.isDirectory else {
-            return []
-        }
-
-        let snippetFiles = try files(in: snippetsDirectory, withExtension: "swift") +
-            subdirectories(in: snippetsDirectory)
-                .flatMap { subdirectory -> [URL] in
-                    try files(in: subdirectory, withExtension: "swift")
-                }
-
-        return try snippetFiles.map { try Snippet(parsing: $0) }
-    }
-
     static func main() throws {
-        if CommandLine.arguments.count < 4 {
+        if CommandLine.arguments.count == 1 || CommandLine.arguments.contains("-h") || CommandLine.arguments.contains("--help") {
             printUsage()
             exit(0)
         }
-        let snippetExtract = SnippetExtractCommand(snippetsDir: CommandLine.arguments[1],
-                                                   outputDir: CommandLine.arguments[2],
-                                                   moduleName: CommandLine.arguments[3])
-        try snippetExtract.run()
+        do {
+            let snippetExtract = try SnippetExtractCommand(arguments: Array(CommandLine.arguments.dropFirst(1)))
+            try snippetExtract.run()
+        } catch let error as ArgumentError {
+            printUsage()
+            throw error
+        }
+    }
+}
+
+extension Array where Element == String {
+    mutating func parseSnippetArgument() throws -> SnippetExtractCommand.Argument? {
+        guard let thisArgument = first else {
+            return nil
+        }
+        removeFirst()
+        switch thisArgument {
+        case "--module-name":
+            guard let nextArgument = first else {
+                throw SnippetExtractCommand.ArgumentError.missingOptionValue(.moduleName)
+            }
+            removeFirst()
+            return .moduleName(nextArgument)
+        case "--output":
+            guard let nextArgument = first else {
+                throw SnippetExtractCommand.ArgumentError.missingOptionValue(.outputFile)
+            }
+            removeFirst()
+            return .outputFile(nextArgument)
+        default:
+            return .inputFile(thisArgument)
+        }
     }
 }
diff --git a/Sources/snippet-extract/Utility/SymbolGraph+Snippet.swift b/Sources/snippet-extract/Utility/SymbolGraph+Snippet.swift
@@ -14,18 +14,19 @@ extension SymbolGraph.Symbol {
     /// Create a ``SymbolGraph.Symbol`` from a ``Snippet``.
     ///
     /// - parameter moduleName: The name to use for the package name in the snippet symbol's precise identifier.
-    public init(_ snippet: Snippets.Snippet, moduleName: String, inDirectory snippetsDirectory: URL) {
+    public init(_ snippet: Snippets.Snippet, moduleName: String) throws {
         let basename = snippet.sourceFile.deletingPathExtension().lastPathComponent
         let identifier = SymbolGraph.Symbol.Identifier(precise: "$snippet__\(moduleName).\(basename)", interfaceLanguage: "swift")
         let names = SymbolGraph.Symbol.Names.init(title: basename, navigator: nil, subHeading: nil, prose: nil)
         
         var pathComponents = snippet.sourceFile.absoluteURL.deletingPathExtension().pathComponents[...]
-        for component in snippetsDirectory.absoluteURL.pathComponents {
-            guard pathComponents.first == component else {
-                break
-            }
-            pathComponents = pathComponents.dropFirst(1)
+
+        guard let snippetsPathComponentIndex = pathComponents.firstIndex(where: {
+            $0 == "Snippets"
+        }) else {
+            throw SnippetExtractCommand.ArgumentError.snippetNotContainedInSnippetsDirectory(snippet.sourceFile)
         }
+        pathComponents = pathComponents[snippetsPathComponentIndex...]
         
         let docComment = SymbolGraph.LineList(snippet.explanation
                                     .split(separator: "\n", maxSplits: Int.max, omittingEmptySubsequences: false)
diff --git a/Tests/SwiftDocCPluginUtilitiesTests/Snippets/SnippetExtractTests.swift b/Tests/SwiftDocCPluginUtilitiesTests/Snippets/SnippetExtractTests.swift
diff --git a/Tests/SwiftDocCPluginUtilitiesTests/Snippets/SnippetSymbolTests.swift b/Tests/SwiftDocCPluginUtilitiesTests/Snippets/SnippetSymbolTests.swift
