calver 1.1.6

/// Re-exports for the CLI interface and command definitions.
///
/// This module provides the main CLI structure and available commands
/// for the calver tool, enabling calendar-based version management.
pub use cli::{Cli, Commands};

/// Command-line interface definitions for the calver tool.
///
/// This module contains the CLI parser configuration and command definitions
/// using the `clap` crate. It defines the main application structure and
/// available subcommands for calendar versioning operations.
///
/// # Environment Variables
///
/// The CLI supports the following environment variables for default values:
/// - `CALVER_FORMAT`: Default date format string
/// - `CALVER_SEPARATOR`: Default separator between date and patch
/// - `CALVER_PATCH`: Default patch number
/// - `CALVER_LAST`: Previous version for automatic patch increment
///
/// # Examples
///
/// Basic usage:
/// ```bash
/// calver bump                           # Generate version with defaults
/// calver bump --format "%Y%m%d"        # Custom date format
/// calver bump --separator "_"          # Custom separator
/// calver bump --patch 5                # Explicit patch number
/// calver bump --last "2024.03.15-3"    # Auto-increment from last version
/// ```
mod cli {
    use clap::{Parser, Subcommand};

    /// Main CLI application structure for the calver tool.
    ///
    /// This struct defines the root command-line interface for the calendar
    /// versioning tool. It uses clap's derive macros to automatically generate
    /// argument parsing, help text, and version information.
    ///
    /// The tool is designed to be lightweight and focused on calendar versioning,
    /// providing an easy way to generate date-based version identifiers with
    /// automatic patch increment capabilities.
    ///
    /// # Usage
    ///
    /// ```bash
    /// calver <COMMAND>
    /// ```
    ///
    /// # Available Commands
    ///
    /// - `bump`: Generate or increment a calendar version
    ///
    /// # Examples
    ///
    /// ```bash
    /// # Show help
    /// calver --help
    ///
    /// # Show version
    /// calver --version
    ///
    /// # Run bump command
    /// calver bump --format "%Y.%m.%d"
    /// ```
    #[derive(Debug, Parser)]
    #[command(name = "calver", version, about = "A lightweight command-line tool for effortless Calendar Versioning increments", long_about = None)]
    pub struct Cli {
        #[command(subcommand)]
        pub command: Commands,
    }

    /// Available subcommands for the calver tool.
    ///
    /// This enum defines all the operations that can be performed with the
    /// calver tool. Currently, it focuses on version bumping with various
    /// configuration options.
    ///
    /// Each command variant contains its own set of arguments and options,
    /// allowing for flexible version generation strategies.
    #[derive(Debug, Subcommand)]
    pub enum Commands {
        /// Bumps the version using today's date (UTC).
        ///
        /// This command generates a new calendar version based on the current UTC date.
        /// It supports various customization options for formatting and can either
        /// use an explicit patch number or automatically increment based on a
        /// previous version.
        ///
        /// # Behavior
        ///
        /// - Uses current UTC date/time for version generation
        /// - Supports custom date formats (default: "%Y.%m.%d")
        /// - Allows custom separators between date and patch (default: "-")
        /// - Can use explicit patch numbers or auto-increment from last version
        /// - Patch numbers are limited to u16 range (0-65535)
        ///
        /// # Environment Variables
        ///
        /// All options can be set via environment variables:
        /// - `CALVER_FORMAT`: Date format string
        /// - `CALVER_SEPARATOR`: Separator character(s)
        /// - `CALVER_PATCH`: Explicit patch number
        /// - `CALVER_LAST`: Previous version for auto-increment
        ///
        /// # Examples
        ///
        /// ```bash
        /// # Basic usage with defaults
        /// calver bump
        /// # Output: "2024.03.15-0"
        ///
        /// # Custom format and separator
        /// calver bump --format "%Y%m%d" --separator "_v"
        /// # Output: "20240315_v0"
        ///
        /// # Explicit patch number
        /// calver bump --patch 5
        /// # Output: "2024.03.15-5"
        ///
        /// # Auto-increment from last version
        /// calver bump --last "2024.03.15-3"
        /// # Output: "2024.03.15-4" (if same date)
        /// # Output: "2024.03.15-0" (if different date)
        ///
        /// # Using environment variables
        /// export CALVER_FORMAT="%Y.%m.%d"
        /// export CALVER_SEPARATOR="-"
        /// calver bump
        /// ```
        ///
        /// # Argument Conflicts
        ///
        /// The `--patch` and `--last` arguments are mutually exclusive:
        /// - Use `--patch` for explicit patch numbers
        /// - Use `--last` for automatic increment from previous version
        Bump {
            /// The format of the calendar version.
            ///
            /// Specifies how the date portion of the version should be formatted.
            /// Uses strftime format specifiers. Common formats include:
            /// - `%Y.%m.%d`: 2024.03.15 (default)
            /// - `%Y%m%d`: 20240315
            /// - `%y.%m.%d`: 24.03.15
            /// - `%Y-%m-%d`: 2024-03-15
            ///
            /// Can also be set via the `CALVER_FORMAT` environment variable.
            ///
            /// # Examples
            ///
            /// ```bash
            /// calver bump --format "%Y.%m.%d"    # 2024.03.15
            /// calver bump --format "%Y%m%d"      # 20240315
            /// calver bump --format "%y%m%d"      # 240315
            /// ```
            #[arg(short, long, env = "CALVER_FORMAT")]
            format: Option<String>,

            /// The separator for the calendar version.
            ///
            /// Defines the character(s) used to separate the date portion from
            /// the patch number. Common separators include:
            /// - `-`: 2024.03.15-0 (default)
            /// - `_`: 2024.03.15_0
            /// - `.`: 2024.03.15.0
            /// - `_v`: 2024.03.15_v0
            ///
            /// Can also be set via the `CALVER_SEPARATOR` environment variable.
            ///
            /// # Examples
            ///
            /// ```bash
            /// calver bump --separator "-"        # 2024.03.15-0
            /// calver bump --separator "_"        # 2024.03.15_0
            /// calver bump --separator "_v"       # 2024.03.15_v0
            /// ```
            #[arg(short, long, env = "CALVER_SEPARATOR")]
            separator: Option<String>,

            /// Path to a Git repository to automatically fetch the latest tag for today.
            ///
            /// When provided, calver will:
            /// 1. Open the Git repository at the specified path
            /// 2. Search for tags matching today's date with the specified format
            /// 3. Automatically increment from the highest patch number found
            /// 4. Start from patch 0 if no matching tag exists
            ///
            /// This option conflicts with both --patch and --last as it determines
            /// the version automatically from the repository's tags.
            ///
            /// # Examples
            ///
            /// ```bash
            /// # Use current directory
            /// calver bump --git-path .
            ///
            /// # Use specific repository path
            /// calver bump --git-path /path/to/my/project
            ///
            /// # Combine with custom format
            /// calver bump --git-path . --format "%Y%m%d" --separator "_"
            /// ```
            #[arg(short, long, env = "CALVER_GIT_PATH", conflicts_with_all = ["patch", "last"])]
            git_path: Option<String>,

            /// The explicit patch number to use.
            ///
            /// Sets a specific patch number for the version instead of
            /// auto-incrementing from a previous version. Must be between
            /// 0 and 65535 (u16 range).
            ///
            /// This argument conflicts with `--last` and `--git-path`. Use one or the other:
            /// - `--patch`: For explicit control over patch numbers
            /// - `--last`: For automatic increment based on previous version
            ///
            /// Can also be set via the `CALVER_PATCH` environment variable.
            ///
            /// # Examples
            ///
            /// ```bash
            /// calver bump --patch 0              # 2024.03.15-0
            /// calver bump --patch 10             # 2024.03.15-10
            /// calver bump --patch 999            # 2024.03.15-999
            /// ```
            #[arg(
                short,
                long,
                default_value_t = 0,
                env = "CALVER_PATCH",
                conflicts_with_all = ["last", "git_path"]
            )]
            patch: u16,

            /// The previous version for automatic patch increment.
            ///
            /// Provides the last generated version string to automatically
            /// determine the next patch number. The tool will:
            /// 1. Parse the date from the previous version
            /// 2. Compare it with today's date
            /// 3. If dates match: increment the patch number
            /// 4. If dates differ: start with patch 0
            ///
            /// This argument conflicts with `--patch` and `--git-path`. Use one or the other:
            /// - `--last`: For automatic increment
            /// - `--patch`: For explicit patch number control
            ///
            /// Can also be set via the `CALVER_LAST` environment variable.
            ///
            /// # Examples
            ///
            /// ```bash
            /// # Same date - increment patch
            /// calver bump --last "2024.03.15-3"
            /// # Output: "2024.03.15-4"
            ///
            /// # Different date - reset patch
            /// calver bump --last "2024.03.14-10"
            /// # Output: "2024.03.15-0"
            ///
            /// # Invalid format - start fresh
            /// calver bump --last "invalid-version"
            /// # Output: "2024.03.15-0"
            /// ```
            #[arg(short, long, env = "CALVER_LAST", conflicts_with_all = ["patch", "git_path"])]
            last: Option<String>,
        },
    }
}