feat: Renames some modules, updates plugins to stop using deprecated components.

Sources/CliClient/CliClient.swift

@@ -0,0 +1,339 @@
+import Dependencies
+import DependenciesMacros
+import FileClient
+import Foundation
+import GitClient
+import ShellClient
+
+public extension DependencyValues {
+
+  var cliClient: CliClient {
+    get { self[CliClient.self] }
+    set { self[CliClient.self] = newValue }
+  }
+}
+
+/// Handles the command-line commands.
+@DependencyClient
+public struct CliClient: Sendable {
+
+  /// Build and update the version based on the git tag, or branch + sha.
+  public var build: @Sendable (SharedOptions) async throws -> String
+
+  /// Bump the existing version.
+  public var bump: @Sendable (BumpOption, SharedOptions) async throws -> String
+
+  /// Generate a version file with an optional version that can be set manually.
+  public var generate: @Sendable (SharedOptions) async throws -> String
+
+  /// Update a version file manually.
+  public var update: @Sendable (SharedOptions) async throws -> String
+
+  public enum BumpOption: Sendable, CaseIterable {
+    case major, minor, patch
+  }
+
+  public struct SharedOptions: Equatable, Sendable {
+
+    let allowPreReleaseTag: Bool
+    let dryRun: Bool
+    let gitDirectory: String?
+    let logLevel: Logger.Level
+    let target: String
+
+    public init(
+      allowPreReleaseTag: Bool = false,
+      gitDirectory: String? = nil,
+      dryRun: Bool = false,
+      target: String,
+      logLevel: Logger.Level = .debug
+    ) {
+      self.allowPreReleaseTag = allowPreReleaseTag
+      self.gitDirectory = gitDirectory
+      self.dryRun = dryRun
+      self.target = target
+      self.logLevel = logLevel
+    }
+  }
+
+}
+
+extension CliClient: DependencyKey {
+  public static let testValue: CliClient = Self()
+
+  public static func live(environment: [String: String]) -> Self {
+    .init(
+      build: { try await $0.build(environment) },
+      bump: { try await $1.bump($0) },
+      generate: { try await $0.generate() },
+      update: { try await $0.update() }
+    )
+  }
+
+  public static var liveValue: CliClient {
+    .live(environment: ProcessInfo.processInfo.environment)
+  }
+}
+
+// MARK: Private
+
+@_spi(Internal)
+public extension CliClient.SharedOptions {
+
+  func fileUrl() async throws -> URL {
+    @Dependency(\.fileClient) var fileClient
+
+    let target = self.target.hasPrefix(".") ? String(self.target.dropFirst()) : self.target
+    let targetHasSources = target.hasPrefix("Sources") || target.hasPrefix("/Sources")
+
+    var url = url(for: gitDirectory ?? (targetHasSources ? target : "Sources"))
+
+    if gitDirectory != nil {
+      if !targetHasSources {
+        url.appendPathComponent("Sources")
+      }
+      url.appendPathComponent(target)
+    }
+
+    let isDirectory = try await fileClient.isDirectory(url.cleanFilePath)
+
+    if isDirectory {
+      url.appendPathComponent(Constants.defaultFileName)
+    }
+
+    return url
+  }
+
+  @discardableResult
+  func run<T>(
+    _ operation: () async throws -> T
+  ) async rethrows -> T {
+    try await withDependencies {
+      $0.logger.logLevel = logLevel
+    } operation: {
+      try await operation()
+    }
+  }
+
+  func write(_ string: String, to url: URL) async throws {
+    @Dependency(\.fileClient) var fileClient
+    @Dependency(\.logger) var logger
+    if !dryRun {
+      try await fileClient.write(string: string, to: url)
+    } else {
+      logger.debug("Skipping, due to dry-run being passed.")
+      logger.debug("\(string)")
+    }
+  }
+}
+
+private extension CliClient.SharedOptions {
+
+  func gitVersion() async throws -> GitClient.Version {
+    @Dependency(\.gitClient) var gitClient
+
+    if let exactMatch = try? await gitClient.version(.init(
+      gitDirectory: gitDirectory,
+      style: .tag(exactMatch: true)
+    )) {
+      return exactMatch
+    } else if let partialMatch = try? await gitClient.version(.init(
+      gitDirectory: gitDirectory,
+      style: .tag(exactMatch: false)
+    )) {
+      return partialMatch
+    } else {
+      return try await gitClient.version(.init(
+        gitDirectory: gitDirectory,
+        style: .branch(commitSha: true)
+      ))
+    }
+  }
+
+  func gitSemVar() async throws -> SemVar {
+    @Dependency(\.gitClient) var gitClient
+
+    let version = try await gitVersion()
+
+    guard let semVar = version.semVar else {
+      return .init(preRelease: version.description)
+    }
+
+    if allowPreReleaseTag, semVar.preRelease == nil {
+      let branchVersion = try await gitClient.version(.init(
+        gitDirectory: gitDirectory,
+        style: .branch(commitSha: true)
+      ))
+      return .init(
+        major: semVar.major,
+        minor: semVar.minor,
+        patch: semVar.patch,
+        preRelease: branchVersion.description
+      )
+    }
+    return semVar
+  }
+
+  func build(_ environment: [String: String]) async throws -> String {
+    try await run {
+      @Dependency(\.gitClient) var gitVersion
+      @Dependency(\.fileClient) var fileClient
+      @Dependency(\.logger) var logger
+
+      let fileUrl = try await self.fileUrl()
+      logger.debug("File url: \(fileUrl.cleanFilePath)")
+
+      let currentVersion = try await gitVersion.currentVersion(in: gitDirectory)
+      logger.debug("Git version: \(currentVersion)")
+
+      let fileContents = Template.build(currentVersion)
+
+      try await write(fileContents, to: fileUrl)
+
+      return fileUrl.cleanFilePath
+    }
+  }
+
+  private func getVersionString() async throws -> (version: String, usesOptionalType: Bool) {
+    @Dependency(\.fileClient) var fileClient
+    @Dependency(\.gitClient) var gitVersionClient
+    @Dependency(\.logger) var logger
+
+    let targetUrl = try await fileUrl()
+
+    guard fileClient.fileExists(targetUrl) else {
+      // Get the latest tag, not requiring an exact tag set on the commit.
+      // This will return a tag, that may have some more data on the patch
+      // portion of the tag, such as: 0.1.1-4-g59bc977
+      let version = try await gitVersionClient.currentVersion(in: gitDirectory, exactMatch: false)
+      // TODO: Not sure what to do for the uses optional value here??
+      return (version, false)
+    }
+
+    let contents = try await fileClient.read(targetUrl)
+    let versionLine = contents.split(separator: "\n")
+      .first { $0.hasPrefix("let VERSION:") }
+
+    guard let versionLine else {
+      throw CliClientError.failedToParseVersionFile
+    }
+    logger.debug("Version line: \(versionLine)")
+
+    let isOptional = versionLine.contains("String?")
+    logger.debug("Uses optional: \(isOptional)")
+
+    let versionString = versionLine.split(separator: "let VERSION: \(isOptional ? "String?" : "String") = ").last
+    guard let versionString else {
+      throw CliClientError.failedToParseVersionFile
+    }
+    return (String(versionString), isOptional)
+  }
+
+  private func getSemVar(_ version: String, _ bump: CliClient.BumpOption) throws -> SemVar {
+    let semVar = SemVar(string: version) ?? .init()
+    return semVar.bump(bump)
+  }
+
+  func bump(_ type: CliClient.BumpOption) async throws -> String {
+    try await run {
+      @Dependency(\.fileClient) var fileClient
+      @Dependency(\.logger) var logger
+
+      let targetUrl = try await fileUrl()
+
+      logger.debug("Bump target url: \(targetUrl.cleanFilePath)")
+
+      let (versionString, usesOptional) = try await getVersionString()
+      let semVar = try getSemVar(versionString, type)
+      let version = semVar.versionString(withPreReleaseTag: allowPreReleaseTag)
+      logger.debug("Bumped version: \(version)")
+
+      let template = usesOptional ? Template.optional(version) : Template.build(version)
+      try await write(template, to: targetUrl)
+      return targetUrl.cleanFilePath
+    }
+  }
+
+  func generate(_ version: String? = nil) async throws -> String {
+    try await run {
+      @Dependency(\.fileClient) var fileClient
+      @Dependency(\.logger) var logger
+
+      let targetUrl = try await fileUrl()
+
+      logger.debug("Generate target url: \(targetUrl.cleanFilePath)")
+
+      guard !fileClient.fileExists(targetUrl) else {
+        throw CliClientError.fileExists(path: targetUrl.cleanFilePath)
+      }
+
+      let template = Template.optional(version)
+      try await write(template, to: targetUrl)
+      return targetUrl.cleanFilePath
+    }
+  }
+
+  func update() async throws -> String {
+    @Dependency(\.gitClient) var gitVersionClient
+    return try await generate(gitVersionClient.currentVersion(in: gitDirectory))
+  }
+}
+
+@_spi(Internal)
+public extension CliClient.BumpOption {
+
+  func bump(
+    major: inout Int,
+    minor: inout Int,
+    patch: inout Int
+  ) {
+    switch self {
+    case .major:
+      major += 1
+      minor = 0
+      patch = 0
+    case .minor:
+      minor += 1
+      patch = 0
+    case .patch:
+      patch += 1
+    }
+  }
+}
+
+@_spi(Internal)
+public struct Template: Sendable {
+  let type: TemplateType
+  let version: String?
+
+  enum TemplateType: String, Sendable {
+    case optionalString = "String?"
+    case string = "String"
+  }
+
+  var value: String {
+    let versionString = version != nil ? "\"\(version!)\"" : "nil"
+    return """
+    // Do not set this variable, it is set during the build process.
+    let VERSION: \(type.rawValue) = \(versionString)
+    """
+  }
+
+  public static func build(_ version: String? = nil) -> String {
+    nonOptional(version)
+  }
+
+  public static func nonOptional(_ version: String? = nil) -> String {
+    Self(type: .string, version: version).value
+  }
+
+  public static func optional(_ version: String? = nil) -> String {
+    Self(type: .optionalString, version: version).value
+  }
+}
+
+enum CliClientError: Error {
+  case gitDirectoryNotFound
+  case fileExists(path: String)
+  case failedToParseVersionFile
+}

Sources/CliClient/Constants.swift

@@ -0,0 +1,3 @@
+enum Constants {
+  static let defaultFileName = "Version.swift"
+}

Sources/CliClient/Documentation.docc/Articles/GettingStarted.md

@@ -0,0 +1,69 @@
+# Getting Started
+
+Learn how to integrate the plugins into your project
+
+## Overview
+
+Use the plugins by including as a package to your project and declaring in the `plugins` section of
+your target.
+
+> Note: You must use swift-tools version 5.6 or greater for package plugins and
+> target `macOS(.v10_15)` or greater.
+
+```swift
+// swift-tools-version: 5.7
+
+import PackageDescription
+
+let package = Package(
+  platforms:[.macOS(.v10_15)],
+  dependencies: [
+    ...,
+    .package(url: "https://github.com/m-housh/swift-cli-version.git", from: "0.1.0")
+  ],
+  targets: [
+    .executableTarget(
+      name: "<target name>",
+      dependencies: [...],
+      plugins: [ 
+        .plugin(name: "BuildWithVersionPlugin", package: "swift-cli-version")
+      ]
+    )
+  ]
+)
+```
+
+The above example uses the build tool plugin.  The `BuildWithVersionPlugin` will give you access
+to a `VERSION` variable in your project that you can use to supply the version of the tool.
+
+### Example
+
+```swift
+import ArgumentParser
+
+@main
+struct MyCliTool: ParsableCommand { 
+  static let configuration = CommandConfiguration(
+    abstract: "My awesome cli tool",
+    version: VERSION
+  )
+
+  func run() throws { 
+    print("Version: \(VERSION)")
+  }
+}
+```
+
+After you enable the plugin, you will have access to the `VERSION` string variable even though it is 
+not declared in your source files.
+
+![Trust & Enable](trust)
+
+> Note: If your `DerivedData` folder lives in a directory that is a mounted volume / or somewhere
+> that is not under your home folder then you may get build failures using the build tool
+> plugin, it will work if you build from the command line and pass the `--disable-sandbox` flag to the
+> build command or use one of the manual methods.
+
+## See Also
+
+<doc:ManualPlugins>

Sources/CliClient/Documentation.docc/Articles/ManualPlugins.md

@@ -0,0 +1,68 @@
+# Manual Plugins
+
+There are two plugins that are included that can be ran manually, if the build tool plugin does not fit
+your use case.
+
+## Generate Version
+
+The `generate-version` plugin will create a `Version.swift` file in the given target.  You can
+run it by running the following command.
+
+```bash
+swift package --disable-sandbox \
+  --allow-writing-to-package-directory \
+  generate-version \
+  <target>
+```
+
+> Note: If using the manual version then the `VERSION` variable is an optional string that will be
+> `nil`, allowing you to run the `update-version` command in your build pipeline.
+
+## Update Version
+
+The `update-version` plugin can be ran in your build pipeline process to set the version prior to
+building for distribution.
+
+```bash
+swift package --disable-sandbox \
+  --allow-writing-to-package-directory \
+  update-version \
+  <target>
+```
+
+## Options
+
+Both manual versions also allow the following options to customize the operation, the
+options need to come after the plugin name.
+
+| Option | Description |
+| ------ | ----------- |
+| --dry-run | Do not write to any files, but describe where values would be written |
+| --filename | Override the file name to be written in the target directory |
+| --verbose | Increase the logging output |
+
+### Example with options
+```bash
+swift package \
+  --allow-writing-to-package-directory \
+  generate-version \
+  --dry-run \
+  --verbose \
+  <target>
+```
+
+## View the Executable Options
+
+You can also run the following command to view the options in your terminal
+
+```bash
+swift run cli-version --help
+```
+
+Or
+
+```bash
+swift run cli-version <verb> --help
+```
+
+Where `verb` is one of, `build`, `generate`, or `update`.

Sources/CliClient/Documentation.docc/CliVersion.md

@@ -0,0 +1,23 @@
+# ``CliVersion``
+
+Derive a version for a command line tool from git tags or a git sha.
+
+## Additional Resources
+
+[Github Repo](https://github.com/m-housh/swift-cli-version)
+
+## Overview
+
+This tool exposes several plugins that can be used to derive a version for a command line program at
+build time or by manually running the plugin.  The version is derived from git tags and falling back to 
+the branch and git sha if a tag is not set for the current worktree state.
+
+## Articles
+
+- <doc:GettingStarted>
+- <doc:ManualPlugins>
+
+## Api
+
+- ``FileClient``
+- ``GitVersionClient``

Sources/CliClient/Helpers.swift

@@ -0,0 +1,15 @@
+import Logging
+
+// TODO: Move.
+@_spi(Internal)
+public extension Logger.Level {
+
+  init(verbose: Int) {
+    switch verbose {
+    case 1: self = .warning
+    case 2: self = .debug
+    case 3...: self = .trace
+    default: self = .info
+    }
+  }
+}

Sources/CliClient/SemVar.swift

@@ -0,0 +1,109 @@
+import Foundation
+import GitClient
+
+// Container for sem-var version.
+@_spi(Internal)
+public struct SemVar: CustomStringConvertible, Equatable, Sendable {
+  /// The major version.
+  public let major: Int
+  /// The minor version.
+  public let minor: Int
+  /// The patch version.
+  public let patch: Int
+  /// Extra pre-release tag.
+  public let preRelease: String?
+
+  public init(
+    major: Int,
+    minor: Int,
+    patch: Int,
+    preRelease: String? = nil
+  ) {
+    self.major = major
+    self.minor = minor
+    self.patch = patch
+    self.preRelease = preRelease
+  }
+
+  public init(preRelease: String? = nil) {
+    self.init(
+      major: 0,
+      minor: 0,
+      patch: 0,
+      preRelease: preRelease
+    )
+  }
+
+  public init?(string: String) {
+    let parts = string.split(separator: ".")
+    guard parts.count >= 3 else {
+      return nil
+    }
+    let major = Int(String(parts[0].replacingOccurrences(of: "\"", with: "")))
+    let minor = Int(String(parts[1]))
+
+    let patchParts = parts[2].split(separator: "-")
+    let patch = Int(patchParts.first ?? "0")
+    let preRelease = String(patchParts.dropFirst().joined(separator: "-"))
+
+    self.init(
+      major: major ?? 0,
+      minor: minor ?? 0,
+      patch: patch ?? 0,
+      preRelease: preRelease
+    )
+  }
+
+  public var description: String { versionString() }
+
+  // Create a version string, optionally appending a suffix.
+  public func versionString(withPreReleaseTag: Bool = true) -> String {
+    let string = "\(major).\(minor).\(patch)"
+
+    guard withPreReleaseTag else { return string }
+
+    guard let suffix = preRelease, suffix.count > 0 else {
+      return string
+    }
+
+    if !suffix.hasPrefix("-") {
+      return "\(string)-\(suffix)"
+    }
+
+    return "\(string)\(suffix)"
+  }
+
+  // Bumps the sem-var by the given option (major, minor, patch)
+  public func bump(_ option: CliClient.BumpOption) -> Self {
+    switch option {
+    case .major:
+      return .init(
+        major: major + 1,
+        minor: 0,
+        patch: 0,
+        preRelease: preRelease
+      )
+    case .minor:
+      return .init(
+        major: major,
+        minor: minor + 1,
+        patch: 0,
+        preRelease: preRelease
+      )
+    case .patch:
+      return .init(
+        major: major,
+        minor: minor,
+        patch: patch + 1,
+        preRelease: preRelease
+      )
+    }
+  }
+}
+
+@_spi(Internal)
+public extension GitClient.Version {
+  var semVar: SemVar? {
+    .init(string: description)
+  }
+}