Rename snippet-build to snippet-extract (#33)

In general, the "build" terminology isn't really correct for snippets,
as no compilation is going on as far as the plugin is concerned. This tool
is actually parsing and extracting text for creation of symbol graphs for a
package's snippets. So we should call this process "extraction" rather than
"building".

rdar://101436368

Author: bitjammer

Package.swift

@@ -30,7 +30,7 @@ let package = Package(
                 intent: .documentationGeneration()
             ),
             dependencies: [
-                "snippet-build",
+                "snippet-extract",
             ],
             path: "Plugins/Swift-DocC Convert",
             exclude: ["Symbolic Links/README.md"]
@@ -45,7 +45,7 @@ let package = Package(
                 )
             ),
             dependencies: [
-                "snippet-build",
+                "snippet-extract",
             ],
             exclude: ["Symbolic Links/README.md"]
         ),
@@ -72,7 +72,7 @@ let package = Package(
         ),
         .target(name: "Snippets"),
         .executableTarget(
-            name: "snippet-build",
+            name: "snippet-extract",
             dependencies: [
                 "Snippets",
                 .product(name: "SymbolKit", package: "swift-docc-symbolkit"),

Plugins/SharedPackagePluginExtensions/PackageManager+getSymbolGraphsForDocC.swift

@@ -38,7 +38,7 @@ extension PackageManager {
         for target: SwiftSourceModuleTarget,
         context: PluginContext,
         verbose: Bool,
-        snippetBuilder: SnippetBuilder?
+        snippetExtractor: SnippetExtractor?
     ) throws -> DocCSymbolGraphResult {
         // First generate the primary symbol graphs containing information about the
         // symbols defined in the target itself.
@@ -59,18 +59,18 @@ extension PackageManager {
             print("target symbol graph directory path: '\(targetSymbolGraphsDirectory.path)'")
         }
 
-        // Then, check to see if we were provided a snippet builder. If so,
+        // Then, check to see if we were provided a snippet extractor. If so,
         // we should attempt to generate symbol graphs for any snippets included in the
         // target's containing package.
-        guard let snippetBuilder = snippetBuilder else {
+        guard let snippetExtractor = snippetExtractor else {
             return DocCSymbolGraphResult(targetSymbolGraphsDirectory: targetSymbolGraphsDirectory)
         }
 
         if verbose {
-            print("snippet builder provided, attempting to generate snippet symbol graph")
+            print("snippet extractor provided, attempting to generate snippet symbol graph")
         }
 
-        guard let snippetSymbolGraphsDirectory = try snippetBuilder.generateSnippets(
+        guard let snippetSymbolGraphsDirectory = try snippetExtractor.generateSnippets(
             for: target,
             context: context
         ) else {

Plugins/SharedPackagePluginExtensions/SnippetBuilder+generateSnippetsForTarget.swift renamed to Plugins/SharedPackagePluginExtensions/SnippetExtractor+generateSnippetsForTarget.swift

@@ -9,7 +9,7 @@
 import Foundation
 import PackagePlugin
 
-extension SnippetBuilder {
+extension SnippetExtractor {
     func generateSnippets(
         for target: SwiftSourceModuleTarget,
         context: PluginContext

Plugins/Swift-DocC Convert/SwiftDocCConvert.swift

@@ -47,13 +47,13 @@ import PackagePlugin
         }
 
 #if swift(>=5.7)
-        let snippetBuildTool = try context.tool(named: "snippet-build")
-        let snippetBuilder = SnippetBuilder(
-            snippetTool: URL(fileURLWithPath: snippetBuildTool.path.string, isDirectory: false),
+        let snippetExtractTool = try context.tool(named: "snippet-extract")
+        let snippetExtractor = SnippetExtractor(
+            snippetTool: URL(fileURLWithPath: snippetExtractTool.path.string, isDirectory: false),
             workingDirectory: URL(fileURLWithPath: context.pluginWorkDirectory.string, isDirectory: true)
         )
 #else
-        let snippetBuilder: SnippetBuilder? = nil
+        let snippetExtractor: SnippetBuilder? = nil
 #endif
 
 
@@ -70,7 +70,7 @@ import PackagePlugin
                 for: target,
                 context: context,
                 verbose: verbose,
-                snippetBuilder: snippetBuilder
+                snippetExtractor: snippetExtractor
             )
 
             if try FileManager.default.contentsOfDirectory(atPath: symbolGraphs.targetSymbolGraphsDirectory.path).isEmpty {

Plugins/Swift-DocC Preview/SwiftDocCPreview.swift

@@ -70,20 +70,20 @@ import PackagePlugin
         }
 
 #if swift(>=5.7)
-        let snippetBuildTool = try context.tool(named: "snippet-build")
-        let snippetBuilder = SnippetBuilder(
-            snippetTool: URL(fileURLWithPath: snippetBuildTool.path.string, isDirectory: false),
+        let snippetExtractTool = try context.tool(named: "snippet-extract")
+        let snippetExtractor = SnippetExtractor(
+            snippetTool: URL(fileURLWithPath: snippetExtractTool.path.string, isDirectory: false),
             workingDirectory: URL(fileURLWithPath: context.pluginWorkDirectory.string, isDirectory: true)
         )
 #else
-        let snippetBuilder: SnippetBuilder? = nil
+        let snippetExtractor: SnippetExtractor? = nil
 #endif
 
         let symbolGraphs = try packageManager.doccSymbolGraphs(
             for: target,
             context: context,
             verbose: verbose,
-            snippetBuilder: snippetBuilder
+            snippetExtractor: snippetExtractor
         )
 
         if try FileManager.default.contentsOfDirectory(atPath: symbolGraphs.targetSymbolGraphsDirectory.path).isEmpty {

Sources/SwiftDocCPluginUtilities/Snippets/SnippetBuilder.swift renamed to Sources/SwiftDocCPluginUtilities/Snippets/SnippetExtractor.swift

@@ -8,22 +8,22 @@
 
 import Foundation
 
-/// Manages snippet symbol graph building.
-public class SnippetBuilder {
+/// Manages snippet symbol graph extraction.
+public class SnippetExtractor {
     /// Uniquely identifies a Swift Package Manager package.
     public typealias PackageIdentifier = String
 
-    enum SymbolGraphBuildResult {
+    enum SymbolGraphExtractionResult {
         case packageDoesNotProduceSnippets
         case packageContainsSnippets(symbolGraphDirectory: URL)
     }
 
     private let snippetTool: URL
     private let workingDirectory: URL
 
-    private var snippetSymbolGraphBuildResults = [PackageIdentifier : SymbolGraphBuildResult]()
+    private var snippetSymbolGraphExtractionResults = [PackageIdentifier : SymbolGraphExtractionResult]()
 
-    /// Create a new snippet builder with the given snippet building tool
+    /// Create a new snippet extractor with the given tool
     /// and working directory.
     public init(snippetTool: URL, workingDirectory: URL) {
         self.snippetTool = snippetTool
@@ -68,15 +68,15 @@ public class SnippetBuilder {
 
     /// Generate snippets for the given package.
     ///
-    /// The snippet builder has an internal cache so it's safe to call this
+    /// The snippet extractor has an internal cache so it's safe to call this
     /// function multiple times with the same package identifier.
     ///
     /// - Parameters:
     ///   - packageIdentifier: A unique identifier for the packge.
     ///   - packageDisplayName: A display name for the package.
     ///   - packageDirectory: The root directory for this package.
     ///
-    ///     The snippet builder will look for a `Snippets` subdirectory
+    ///     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
@@ -86,7 +86,7 @@ public class SnippetBuilder {
         packageDisplayName: String,
         packageDirectory: URL
     ) throws -> URL? {
-        switch snippetSymbolGraphBuildResults[packageIdentifier] {
+        switch snippetSymbolGraphExtractionResults[packageIdentifier] {
         case .packageContainsSnippets(symbolGraphDirectory: let symbolGraphDirectory):
             return symbolGraphDirectory
         case .packageDoesNotProduceSnippets:
@@ -97,7 +97,7 @@ public class SnippetBuilder {
         }
 
         guard let snippetsDirectory = snippetsDirectory(in: packageDirectory) else {
-            snippetSymbolGraphBuildResults[packageIdentifier] = .packageDoesNotProduceSnippets
+            snippetSymbolGraphExtractionResults[packageIdentifier] = .packageDoesNotProduceSnippets
             return nil
         }
 
@@ -118,10 +118,10 @@ public class SnippetBuilder {
         try _runProcess(process)
 
         if _fileExists(outputDirectory.path) {
-            snippetSymbolGraphBuildResults[packageIdentifier] = .packageContainsSnippets(symbolGraphDirectory: outputDirectory)
+            snippetSymbolGraphExtractionResults[packageIdentifier] = .packageContainsSnippets(symbolGraphDirectory: outputDirectory)
             return outputDirectory
         } else {
-            snippetSymbolGraphBuildResults[packageIdentifier] = .packageDoesNotProduceSnippets
+            snippetSymbolGraphExtractionResults[packageIdentifier] = .packageDoesNotProduceSnippets
             return nil
         }
     }

Sources/snippet-build/SnippetBuildCommand.swift renamed to Sources/snippet-extract/SnippetBuildCommand.swift

@@ -11,14 +11,14 @@ import Snippets
 import SymbolKit
 
 @main
-struct SnippetBuildCommand {
+struct SnippetExtractCommand {
     var snippetsDir: String
     var outputDir: String
     var moduleName: String
 
     static func printUsage() {
         let usage = """
-            USAGE: snippet-build <snippet directory> <output directory> <module name>
+            USAGE: snippet-extract <snippet directory> <output directory> <module name>
 
             ARGUMENTS:
                 <snippet directory> - The directory containing Swift snippets
@@ -38,7 +38,7 @@ struct SnippetBuildCommand {
 
     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 metadata = SymbolGraph.Metadata(formatVersion: .init(major: 0, minor: 1, patch: 0), generator: "swift-docc-plugin/snippet-build")
+        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: [])
         try FileManager.default.createDirectory(atPath: emitFilename.deletingLastPathComponent().path, withIntermediateDirectories: true, attributes: nil)
@@ -91,9 +91,9 @@ struct SnippetBuildCommand {
             printUsage()
             exit(0)
         }
-        let snippetBuild = SnippetBuildCommand(snippetsDir: CommandLine.arguments[1],
-                                               outputDir: CommandLine.arguments[2],
-                                               moduleName: CommandLine.arguments[3])
-        try snippetBuild.run()
+        let snippetExtract = SnippetExtractCommand(snippetsDir: CommandLine.arguments[1],
+                                                   outputDir: CommandLine.arguments[2],
+                                                   moduleName: CommandLine.arguments[3])
+        try snippetExtract.run()
     }
 }