makit 0.0.157 → 0.0.158

data/lib/makit/version.rb

@@ -1,503 +1,661 @@
-# frozen_string_literal: true
-
-module Makit
-  # Static version for now to avoid circular dependency issues
-  #VERSION = "0.0.157"
-
-  # Version management utilities for various file formats
-  #
-  # This class provides methods for detecting, extracting, and updating version
-  # numbers in various file formats including .csproj, .wxs, .yml, .gemspec,
-  # .nuspec, and .toml files.
-  #
-  # == Semantic Versioning
-  #
-  # This class follows Semantic Versioning (SemVer) specification (https://semver.org/).
-  # Version numbers use the format: MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
-  #
-  # === Version Number Components
-  #
-  # * MAJOR: Incremented for incompatible API changes that break backward compatibility.
-  #   Example: 1.0.0 -> 2.0.0 indicates breaking changes.
-  #
-  # * MINOR: Incremented for new functionality added in a backward-compatible manner.
-  #   Example: 1.0.0 -> 1.1.0 indicates new features that don't break existing code.
-  #
-  # * PATCH: Incremented for backward-compatible bug fixes.
-  #   Example: 1.0.0 -> 1.0.1 indicates bug fixes only.
-  #
-  # === Pre-release Versions
-  #
-  # Pre-release versions can be appended with a hyphen and identifier(s):
-  # * 1.0.0-alpha.1 (alpha release)
-  # * 1.0.0-beta.2 (beta release)
-  # * 1.0.0-rc.1 (release candidate)
-  # * 1.0.0-preview (preview release)
-  #
-  # Pre-release versions have lower precedence than normal versions:
-  # * 1.0.0-alpha.1 < 1.0.0
-  # * 1.0.0-beta.1 < 1.0.0-rc.1
-  #
-  # === Version Comparison
-  #
-  # Versions are compared using semantic versioning rules:
-  # * Compare MAJOR first, then MINOR, then PATCH
-  # * Pre-release versions are always less than normal versions
-  # * Numeric identifiers are compared numerically
-  # * Non-numeric identifiers are compared lexicographically
-  #
-  # Examples:
-  # * 1.0.0 < 2.0.0 (major version difference)
-  # * 1.0.0 < 1.1.0 (minor version difference)
-  # * 1.0.0 < 1.0.1 (patch version difference)
-  # * 1.0.0-alpha < 1.0.0 (pre-release is less than release)
-  #
-  # === Usage in This Class
-  #
-  # * {parse} - Parses a version string into MAJOR, MINOR, PATCH, and suffix components
-  # * {get_highest_version} - Compares versions using semantic versioning rules to find the highest
-  # * {version} - Reads the current version from the gemspec file
-  # * {get_version_from_file} - Extracts version from various file formats
-  # * {set_version_in_file} - Updates version in various file formats
-  #
-  class Version
-
-    # Attempt to detect the version from the SSOT (Single Source of Truth) version file
-    # Uses the same logic as Makit::Version.info to find version files in priority order:
-    # *.gemspec, Directory.Build.props, Cargo.toml, package.json, pyproject.toml, pom.xml
-    # Falls back to makit.gemspec only if we're in the makit gem directory
-    # @return [String] The version string, or "0.0.0" if no version file is found
-    # @raise [RuntimeError] If a version file is found but version cannot be detected
-    def self.version
-      # Try to find version file in project root using SSOT logic (same as Makit::Version.info)
-      project_root = begin
-        require_relative "directories" unless defined?(Makit::Directories)
-        Makit::Directories::PROJECT_ROOT
-      rescue NameError, LoadError
-        find_project_root(Dir.pwd)
-      end
-
-      # Use SSOT version file detection (supports multiple file types)
-      if project_root && Dir.exist?(project_root)
-        version_file = find_ssot_version_file(project_root)
-        if version_file && File.exist?(version_file)
-          version = extract_version_from_ssot_file(version_file)
-          return version if version
-        end
-      end
-
-      # Fallback to makit.gemspec (for the makit gem itself)
-      # Check if makit.gemspec exists relative to this file
-      makit_gemspec = File.join(File.dirname(__FILE__), "..", "..", "makit.gemspec")
-      makit_gemspec = File.expand_path(makit_gemspec)
-      
-      # Use makit.gemspec if:
-      # 1. It exists, AND
-      # 2. Either we're in the makit gem directory (project_root matches), OR
-      #    project_root is nil (running outside a project context, likely from installed gem)
-      if File.exist?(makit_gemspec)
-        makit_gem_dir = File.dirname(makit_gemspec)
-        use_makit_gemspec = if project_root
-          # If we have a project root, only use makit.gemspec if we're in the makit gem directory
-          File.expand_path(project_root) == File.expand_path(makit_gem_dir)
-        else
-          # If no project root, check if current directory is makit gem or if makit.gemspec is nearby
-          # This handles the case when running from installed gem or outside project context
-          Dir.pwd == makit_gem_dir || File.expand_path(Dir.pwd).start_with?(File.expand_path(makit_gem_dir))
-        end
-        
-        if use_makit_gemspec
-          gemspec_content = File.read(makit_gemspec)
-          match = gemspec_content.match(/spec\.version\s*=\s*["']([^"']+)["']/)
-          raise "Version not found in gemspec file" if match.nil?
-          return match[1]
-        end
-      end
-
-      # If no version file found, return default version (for non-gem projects)
-      "0.0.0"
-    end
-
-    # Parse a semantic version string into its components
-    #
-    # Parses a version string following Semantic Versioning (SemVer) format:
-    # MAJOR.MINOR.PATCH[-PRERELEASE]
-    #
-    # @param version_string [String] Version string in SemVer format (e.g., "1.2.3" or "1.2.3-alpha.1")
-    # @return [Hash] Hash with keys: :major, :minor, :patch, :suffix
-    #   - :major [Integer] Major version number
-    #   - :minor [Integer] Minor version number
-    #   - :patch [Integer] Patch version number
-    #   - :suffix [String] Pre-release suffix (e.g., "-alpha.1") or empty string
-    # @raise [RuntimeError] If version string doesn't match MAJOR.MINOR.PATCH format
-    #
-    # @example Basic version
-    #   Makit::Version.parse("1.2.3")
-    #   # => { major: 1, minor: 2, patch: 3, suffix: "" }
-    #
-    # @example Version with pre-release suffix
-    #   Makit::Version.parse("1.2.3-alpha")
-    #   # => { major: 1, minor: 2, patch: 3, suffix: "-alpha" }
-    #
-    # @example Invalid format
-    #   Makit::Version.parse("1.2")
-    #   # => RuntimeError: Invalid version format: 1.2. Expected format: Major.Minor.Patch
-    #
-    def self.parse(version_string)
-    parts = version_string.split(".")
-    if parts.length < 3
-      raise "Invalid version format: #{version_string}. Expected format: Major.Minor.Patch"
-    end
-
-    major = parts[0].to_i
-    minor = parts[1].to_i
-    patch = parts[2].to_i
-
-    # Handle pre-release suffixes (e.g., "0.1.0-preview" -> patch = 0, suffix = "-preview")
-    # Note: If suffix contains dots (e.g., "1.2.3-preview.1"), the split by "." will separate
-    # the patch and suffix parts, so only the part before the first "-" in parts[2] is used as patch.
-    patch_part = parts[2]
-    if patch_part.include?("-")
-      patch, suffix = patch_part.split("-", 2)
-      patch = patch.to_i
-      suffix = "-#{suffix}"
-    else
-      suffix = ""
-    end
-
-    { major: major, minor: minor, patch: patch, suffix: suffix }
-  end
-
-    # Find the highest version from an array of version strings
-    #
-    # Compares versions using semantic versioning rules (see class documentation).
-    # Uses Ruby's Gem::Version for comparison, which follows SemVer specification.
-    #
-    # @param versions [Array<String>] Array of version strings to compare
-    # @return [String] The highest version string using semantic versioning comparison
-    #
-    # @example
-    #   Makit::Version.get_highest_version(["1.0.0", "2.0.0", "1.5.0", "1.0.1"])
-    #   # => "2.0.0"
-    #
-    # @example Pre-release versions
-    #   Makit::Version.get_highest_version(["1.0.0-alpha", "1.0.0", "1.0.0-beta"])
-    #   # => "1.0.0" (pre-release versions are lower than release versions)
-    #
-    def self.get_highest_version(versions)
-      versions.max { |a, b| Gem::Version.new(a) <=> Gem::Version.new(b) }
-    end
-
-    # Extract version number from a file based on its extension
-    #
-    # Supports multiple file formats:
-    # - .csproj files: `<Version>x.y.z</Version>`
-    # - .wxs files: `Version="x.y.z"`
-    # - .yml files: `VERSION: "x.y.z"`
-    #
-    # @param path [String] Path to the file containing version information
-    # @return [String] The extracted version string
-    # @raise [RuntimeError] If file doesn't exist or has unrecognized extension
-    def self.get_version_from_file(path)
-      raise "file #{path}does not exist" unless File.exist?(path)
-
-      extension = File.extname(path)
-      case extension
-      when ".csproj"
-        Makit::Version.detect_from_file(path, /<Version>([-\w\d.]+)</)
-      when ".wxs"
-        Makit::Version.detect_from_file(path, / Version="([\d.]+)"/)
-      when ".yml"
-        Makit::Version.detect_from_file(path, /VERSION:\s*["']?([\d.]+)["']?/)
-      when ".rb"
-        Makit::Version.detect_from_file(path, /VERSION = "([\d.]+)"/)
-      else
-        raise "unrecognized file type"
-      end
-    end
-
-    # Detect version using a regex pattern in a specific file
-    #
-    # @param filename [String] Path to the file to search
-    # @param regex [Regexp] Regular expression pattern to match version
-    # @return [String, nil] The extracted version or nil if no match found
-    # @raise [RuntimeError] If file doesn't exist
-    def self.detect_from_file(filename, regex)
-      raise "unable to find version in #{filename}" unless File.exist?(filename)
-
-      match = File.read(filename).match(regex)
-      match.captures[0] if !match.nil? && match.captures.length.positive?
-    end
-
-    # Update version number in a file based on its extension
-    #
-    # Supports updating versions in multiple file formats:
-    # - .yml files
-    # - .gemspec files
-    # - .csproj files
-    # - .nuspec files
-    # - .wxs files
-    # - .toml files
-    #
-    # @param filename [String] Path to the file to update
-    # @param version [String] New version string to set
-    # @return [nil]
-    def self.set_version_in_file(filename, version)
-      text = File.read(filename)
-      #   VERSION = "0.0.138rake" (.rb file)
-      new_text = text
-      new_text = new_text.gsub(/VERSION:\s?['|"]([.\d]+)['|"]/, "VERSION: \"#{version}\"") if filename.include?(".yml")
-      new_text = new_text.gsub(/spec\.version\s*=\s*['"]([^'"]+)['"]/, "spec.version = '#{version}'") if filename.include?(".gemspec")
-      # Handle Directory.Build.props and .csproj files (both use <Version> tag)
-      if filename.include?("Directory.Build.props") || filename.include?(".csproj")
-        new_text = new_text.gsub(/<Version>([-\w\d.]+)</, "<Version>#{version}<")
-      end
-      new_text = new_text.gsub(/<version>([-\w\d.]+)</, "<version>#{version}<") if filename.include?(".nuspec")
-      new_text = new_text.gsub(/ Version="([\d.]+)"/, " Version=\"#{version}\"") if filename.include?(".wxs")
-      new_text = new_text.gsub(/VERSION = "([\d.]+)"/, "VERSION = \"#{version}\"") if filename.include?(".rb")
-      # Handle Cargo.toml, pyproject.toml, and other .toml files
-      if filename.include?(".toml")
-        new_text = new_text.gsub(/version\s+=\s+['"]([\w.]+)['"]/, "version=\"#{version}\"")
-      end
-      # Handle package.json
-      if filename.include?("package.json")
-        require "json"
-        json = JSON.parse(new_text)
-        json["version"] = version
-        new_text = JSON.pretty_generate(json)
-      end
-      # Handle pom.xml
-      if filename.include?("pom.xml")
-        new_text = new_text.gsub(%r{<version>([^<]+)</version>}, "<version>#{version}</version>")
-      end
-      File.write(filename, new_text) if new_text != text
-    end
-
-    # Update version number in multiple files matching a glob pattern
-    #
-    # @param glob_pattern [String] Glob pattern to match files (e.g., '**/*.csproj')
-    # @param version [String] New version string to set in all matching files
-    # @return [nil]
-    def self.set_version_in_files(glob_pattern, version)
-      Dir.glob(glob_pattern).each do |filename|
-        set_version_in_file(filename, version)
-      end
-    end
-
-    # Display version information for the current project
-    #
-    # Finds the Single Source of Truth (SSOT) version file in the project root
-    # and displays the file path and current version value.
-    #
-    # Searches for common version files in priority order:
-    # * *.gemspec (Ruby gems)
-    # * Directory.Build.props (.NET projects)
-    # * Cargo.toml (Rust projects)
-    # * package.json (Node.js projects)
-    # * pyproject.toml (Python projects)
-    # * pom.xml (Maven/Java projects)
-    #
-    # If no version file is found, issues a warning and suggests defining a VERSION_FILE
-    # constant to manually specify the version file path.
-    #
-    # @return [nil] Outputs version information to stdout, or returns early with warning if no file found
-    # @raise [RuntimeError] If project root cannot be determined or version cannot be extracted from file
-    #
-    # @example Output format
-    #   Version File: makit.gemspec
-    #   Version: 0.0.147
-    #
-    # @example With VERSION_FILE constant defined
-    #   VERSION_FILE = "custom/version.txt"
-    #   Makit::Version.info
-    #   # Uses the file specified by VERSION_FILE constant
-    #
-    def self.info
-      # Access Directories lazily to avoid circular dependency
-      project_root = begin
-        require_relative "directories" unless defined?(Makit::Directories)
-        Makit::Directories::PROJECT_ROOT
-      rescue NameError, LoadError
-        # Fallback: try to find project root from current directory
-        find_project_root(Dir.pwd)
-      end
-
-      raise "Project root not found" if project_root.nil? || !Dir.exist?(project_root)
-
-      version_file = find_ssot_version_file(project_root)
-      
-      if version_file.nil?
-        warn "  Warning: No version file found in project root: #{project_root}"
-        warn "  You may define a constant VERSION_FILE to manually set the version file path"
-        return
-      end
-
-      # Extract version based on file type
-      version = extract_version_from_ssot_file(version_file)
-
-      raise "Version not found in #{version_file}" if version.nil?
-
-      # Display information with relative path (Windows-safe path handling)
-      # Normalize both paths to forward slashes for comparison, then convert back if needed
-      normalized_version_file = version_file.gsub(/\\/, "/")
-      normalized_project_root = project_root.gsub(/\\/, "/")
-      relative_path = normalized_version_file.sub(normalized_project_root + "/", "")
-      puts "  Version File: #{relative_path}"
-      puts "  Version: #{version}"
-    end
-
-    # Bump the patch version in the SSOT version file
-    #
-    # Finds the Single Source of Truth (SSOT) version file in the project root,
-    # reads the current version, increments the patch version, and updates the file.
-    #
-    # @return [String] The new version string after bumping
-    # @raise [RuntimeError] If project root cannot be determined, no version file is found,
-    #   or version cannot be parsed/updated
-    #
-    # @example
-    #   # Current version: 1.2.3
-    #   Makit::Version.bump
-    #   # => "1.2.4"
-    #
-    # @example With pre-release suffix
-    #   # Current version: 1.2.3-alpha
-    #   Makit::Version.bump
-    #   # => "1.2.4" (removes pre-release suffix when bumping)
-    #
-    def self.bump
-      # Find the SSOT version file
-      project_root = begin
-        require_relative "directories" unless defined?(Makit::Directories)
-        Makit::Directories::PROJECT_ROOT
-      rescue NameError, LoadError
-        find_project_root(Dir.pwd)
-      end
-
-      raise "Project root not found" if project_root.nil? || !Dir.exist?(project_root)
-
-      version_file = find_ssot_version_file(project_root)
-      if version_file.nil?
-        warn "  Warning: No version file found in project root: #{project_root}"
-        warn "  You may define a constant VERSION_FILE to manually set the version file path"
-        raise "Cannot bump version: no version file found"
-      end
-
-      # Read current version
-      current_version = extract_version_from_ssot_file(version_file)
-      raise "Version not found in #{version_file}" if current_version.nil?
-
-      # Parse and bump patch version
-      parsed = parse(current_version)
-      new_version = "#{parsed[:major]}.#{parsed[:minor]}.#{parsed[:patch] + 1}"
-
-      # Update the version file
-      set_version_in_file(version_file, new_version)
-
-      # Verify the update
-      updated_version = extract_version_from_ssot_file(version_file)
-      if updated_version != new_version
-        raise "Version bump failed: expected #{new_version}, got #{updated_version}"
-      end
-
-      new_version
-    end
-
-    private
-
-    # Find the SSOT version file in the project root
-    #
-    # Checks for VERSION_FILE constant first (if defined), then searches for common version files.
-    #
-    # @param project_root [String] Path to the project root directory
-    # @return [String, nil] Path to the version file, or nil if not found
-    def self.find_ssot_version_file(project_root)
-      # Normalize project_root for file operations (Ruby's File methods work with forward slashes)
-      normalized_root = project_root.gsub(/\\/, "/")
-      
-      # Check for manually defined VERSION_FILE constant first
-      if defined?(VERSION_FILE) && !VERSION_FILE.nil?
-        version_file = File.expand_path(VERSION_FILE, normalized_root)
-        return version_file if File.exist?(version_file)
-        warn "  Warning: VERSION_FILE constant points to non-existent file: #{VERSION_FILE}"
-      end
-
-      # Priority order for version files (SSOT)
-      version_file_patterns = [
-        "*.gemspec",                    # Ruby gems
-        "Directory.Build.props",        # .NET projects
-        "Cargo.toml",                   # Rust projects
-        "package.json",                 # Node.js projects
-        "pyproject.toml",               # Python projects
-        "pom.xml"                       # Maven/Java projects
-      ]
-
-      version_file_patterns.each do |pattern|
-        matches = Dir.glob(File.join(normalized_root, pattern))
-        next if matches.empty?
-
-        # For gemspec, prefer the one matching the project name or take the first
-        version_file = matches.first
-        return version_file if version_file
-      end
-
-      nil
-    end
-
-    # Find project root by looking for common markers
-    def self.find_project_root(start_dir)
-      current = File.expand_path(start_dir)
-      root = File.expand_path("/")
-
-      while current != root
-        markers = ["Rakefile", "rakefile.rb", ".gitignore", ".git"]
-        return current if markers.any? { |marker| File.exist?(File.join(current, marker)) }
-        current = File.dirname(current)
-      end
-
-      nil
-    end
-
-    # Extract version from SSOT file based on file type
-    def self.extract_version_from_ssot_file(file_path)
-      case File.basename(file_path)
-      when /\.gemspec$/
-        # Extract from gemspec: spec.version = "x.y.z"
-        content = File.read(file_path)
-        match = content.match(/spec\.version\s*=\s*["']([^"']+)["']/)
-        match ? match[1] : nil
-      when "Directory.Build.props"
-        # Extract from Directory.Build.props: <Version>x.y.z</Version>
-        content = File.read(file_path)
-        match = content.match(%r{<Version>([^<]+)</Version>})
-        match ? match[1] : nil
-      when "Cargo.toml"
-        # Extract from Cargo.toml: version = "x.y.z"
-        content = File.read(file_path)
-        match = content.match(/version\s*=\s*["']([^"']+)["']/)
-        match ? match[1] : nil
-      when "package.json"
-        # Extract from package.json: "version": "x.y.z"
-        require "json"
-        json = JSON.parse(File.read(file_path))
-        json["version"]
-      when "pyproject.toml"
-        # Extract from pyproject.toml: version = "x.y.z" (in [project] or [tool.poetry] section)
-        content = File.read(file_path)
-        # Try [project] section first
-        match = content.match(/\[project\]\s*version\s*=\s*["']([^"']+)["']/)
-        return match[1] if match
-        # Try [tool.poetry] section
-        match = content.match(/\[tool\.poetry\]\s*version\s*=\s*["']([^"']+)["']/)
-        match ? match[1] : nil
-      when "pom.xml"
-        # Extract from pom.xml: <version>x.y.z</version>
-        content = File.read(file_path)
-        match = content.match(%r{<version>([^<]+)</version>})
-        match ? match[1] : nil
-      else
-        nil
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+module Makit
+  # Static version for now to avoid circular dependency issues
+  #VERSION = "0.0.158"
+
+  # Version management utilities for various file formats
+  #
+  # This class provides methods for detecting, extracting, and updating version
+  # numbers in various file formats including .csproj, .wxs, .yml, .gemspec,
+  # .nuspec, and .toml files.
+  #
+  # == Semantic Versioning
+  #
+  # This class follows Semantic Versioning (SemVer) specification (https://semver.org/).
+  # Version numbers use the format: MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
+  #
+  # === Version Number Components
+  #
+  # * MAJOR: Incremented for incompatible API changes that break backward compatibility.
+  #   Example: 1.0.0 -> 2.0.0 indicates breaking changes.
+  #
+  # * MINOR: Incremented for new functionality added in a backward-compatible manner.
+  #   Example: 1.0.0 -> 1.1.0 indicates new features that don't break existing code.
+  #
+  # * PATCH: Incremented for backward-compatible bug fixes.
+  #   Example: 1.0.0 -> 1.0.1 indicates bug fixes only.
+  #
+  # === Pre-release Versions
+  #
+  # Pre-release versions can be appended with a hyphen and identifier(s):
+  # * 1.0.0-alpha.1 (alpha release)
+  # * 1.0.0-beta.2 (beta release)
+  # * 1.0.0-rc.1 (release candidate)
+  # * 1.0.0-preview (preview release)
+  #
+  # Pre-release versions have lower precedence than normal versions:
+  # * 1.0.0-alpha.1 < 1.0.0
+  # * 1.0.0-beta.1 < 1.0.0-rc.1
+  #
+  # === Version Comparison
+  #
+  # Versions are compared using semantic versioning rules:
+  # * Compare MAJOR first, then MINOR, then PATCH
+  # * Pre-release versions are always less than normal versions
+  # * Numeric identifiers are compared numerically
+  # * Non-numeric identifiers are compared lexicographically
+  #
+  # Examples:
+  # * 1.0.0 < 2.0.0 (major version difference)
+  # * 1.0.0 < 1.1.0 (minor version difference)
+  # * 1.0.0 < 1.0.1 (patch version difference)
+  # * 1.0.0-alpha < 1.0.0 (pre-release is less than release)
+  #
+  # === Usage in This Class
+  #
+  # * {parse} - Parses a version string into MAJOR, MINOR, PATCH, and suffix components
+  # * {get_highest_version} - Compares versions using semantic versioning rules to find the highest
+  # * {version} - Reads the current version from the gemspec file
+  # * {get_version_from_file} - Extracts version from various file formats
+  # * {set_version_in_file} - Updates version in various file formats
+  #
+  class Version
+
+    # Attempt to detect the version from the SSOT (Single Source of Truth) version file
+    # Uses the same logic as Makit::Version.info to find version files in priority order:
+    # *.gemspec, Directory.Build.props, Cargo.toml, package.json, pyproject.toml, pom.xml
+    # Falls back to makit.gemspec only if we're in the makit gem directory
+    # @return [String] The version string, or "0.0.0" if no version file is found
+    # @raise [RuntimeError] If a version file is found but version cannot be detected
+    def self.version
+      # Try to find version file in project root using SSOT logic (same as Makit::Version.info)
+      project_root = begin
+        require_relative "directories" unless defined?(Makit::Directories)
+        Makit::Directories::PROJECT_ROOT
+      rescue NameError, LoadError
+        find_project_root(Dir.pwd)
+      end
+
+      # Use SSOT version file detection (supports multiple file types)
+      if project_root && Dir.exist?(project_root)
+        version_file = find_ssot_version_file(project_root)
+        if version_file && File.exist?(version_file)
+          version = extract_version_from_ssot_file(version_file)
+          return version if version
+        end
+      end
+
+      # Fallback to makit.gemspec (for the makit gem itself)
+      # Check if makit.gemspec exists relative to this file
+      makit_gemspec = File.join(File.dirname(__FILE__), "..", "..", "makit.gemspec")
+      makit_gemspec = File.expand_path(makit_gemspec)
+      
+      # Use makit.gemspec if:
+      # 1. It exists, AND
+      # 2. Either we're in the makit gem directory (project_root matches), OR
+      #    project_root is nil (running outside a project context, likely from installed gem)
+      if File.exist?(makit_gemspec)
+        makit_gem_dir = File.dirname(makit_gemspec)
+        use_makit_gemspec = if project_root
+          # If we have a project root, only use makit.gemspec if we're in the makit gem directory
+          File.expand_path(project_root) == File.expand_path(makit_gem_dir)
+        else
+          # If no project root, check if current directory is makit gem or if makit.gemspec is nearby
+          # This handles the case when running from installed gem or outside project context
+          Dir.pwd == makit_gem_dir || File.expand_path(Dir.pwd).start_with?(File.expand_path(makit_gem_dir))
+        end
+        
+        if use_makit_gemspec
+          gemspec_content = File.read(makit_gemspec)
+          match = gemspec_content.match(/spec\.version\s*=\s*["']([^"']+)["']/)
+          raise "Version not found in gemspec file" if match.nil?
+          return match[1]
+        end
+      end
+
+      # If no version file found, return default version (for non-gem projects)
+      "0.0.0"
+    end
+
+    # Parse a semantic version string into its components
+    #
+    # Parses a version string following Semantic Versioning (SemVer) format:
+    # MAJOR.MINOR.PATCH[-PRERELEASE]
+    #
+    # @param version_string [String] Version string in SemVer format (e.g., "1.2.3" or "1.2.3-alpha.1")
+    # @return [Hash] Hash with keys: :major, :minor, :patch, :suffix
+    #   - :major [Integer] Major version number
+    #   - :minor [Integer] Minor version number
+    #   - :patch [Integer] Patch version number
+    #   - :suffix [String] Pre-release suffix (e.g., "-alpha.1") or empty string
+    # @raise [RuntimeError] If version string doesn't match MAJOR.MINOR.PATCH format
+    #
+    # @example Basic version
+    #   Makit::Version.parse("1.2.3")
+    #   # => { major: 1, minor: 2, patch: 3, suffix: "" }
+    #
+    # @example Version with pre-release suffix
+    #   Makit::Version.parse("1.2.3-alpha")
+    #   # => { major: 1, minor: 2, patch: 3, suffix: "-alpha" }
+    #
+    # @example Invalid format
+    #   Makit::Version.parse("1.2")
+    #   # => RuntimeError: Invalid version format: 1.2. Expected format: Major.Minor.Patch
+    #
+    def self.parse(version_string)
+    parts = version_string.split(".")
+    if parts.length < 3
+      raise "Invalid version format: #{version_string}. Expected format: Major.Minor.Patch"
+    end
+
+    major = parts[0].to_i
+    minor = parts[1].to_i
+    patch = parts[2].to_i
+
+    # Handle pre-release suffixes (e.g., "0.1.0-preview" -> patch = 0, suffix = "-preview")
+    # Note: If suffix contains dots (e.g., "1.2.3-preview.1"), the split by "." will separate
+    # the patch and suffix parts, so only the part before the first "-" in parts[2] is used as patch.
+    patch_part = parts[2]
+    if patch_part.include?("-")
+      patch, suffix = patch_part.split("-", 2)
+      patch = patch.to_i
+      suffix = "-#{suffix}"
+    else
+      suffix = ""
+    end
+
+    { major: major, minor: minor, patch: patch, suffix: suffix }
+  end
+
+    # Find the highest version from an array of version strings
+    #
+    # Compares versions using semantic versioning rules (see class documentation).
+    # Uses Ruby's Gem::Version for comparison, which follows SemVer specification.
+    #
+    # @param versions [Array<String>] Array of version strings to compare
+    # @return [String] The highest version string using semantic versioning comparison
+    #
+    # @example
+    #   Makit::Version.get_highest_version(["1.0.0", "2.0.0", "1.5.0", "1.0.1"])
+    #   # => "2.0.0"
+    #
+    # @example Pre-release versions
+    #   Makit::Version.get_highest_version(["1.0.0-alpha", "1.0.0", "1.0.0-beta"])
+    #   # => "1.0.0" (pre-release versions are lower than release versions)
+    #
+    def self.get_highest_version(versions)
+      versions.max { |a, b| Gem::Version.new(a) <=> Gem::Version.new(b) }
+    end
+
+    # Extract version number from a file based on its extension
+    #
+    # Supports multiple file formats:
+    # - .csproj files: `<Version>x.y.z</Version>`
+    # - .wxs files: `Version="x.y.z"`
+    # - .yml files: `VERSION: "x.y.z"`
+    #
+    # @param path [String] Path to the file containing version information
+    # @return [String] The extracted version string
+    # @raise [RuntimeError] If file doesn't exist or has unrecognized extension
+    def self.get_version_from_file(path)
+      raise "file #{path}does not exist" unless File.exist?(path)
+
+      extension = File.extname(path)
+      case extension
+      when ".csproj"
+        Makit::Version.detect_from_file(path, /<Version>([-\w\d.]+)</)
+      when ".wxs"
+        Makit::Version.detect_from_file(path, / Version="([\d.]+)"/)
+      when ".yml"
+        Makit::Version.detect_from_file(path, /VERSION:\s*["']?([\d.]+)["']?/)
+      when ".rb"
+        Makit::Version.detect_from_file(path, /VERSION = "([\d.]+)"/)
+      else
+        raise "unrecognized file type"
+      end
+    end
+
+    # Detect version using a regex pattern in a specific file
+    #
+    # @param filename [String] Path to the file to search
+    # @param regex [Regexp] Regular expression pattern to match version
+    # @return [String, nil] The extracted version or nil if no match found
+    # @raise [RuntimeError] If file doesn't exist
+    def self.detect_from_file(filename, regex)
+      raise "unable to find version in #{filename}" unless File.exist?(filename)
+
+      match = File.read(filename).match(regex)
+      match.captures[0] if !match.nil? && match.captures.length.positive?
+    end
+
+    # Update version number in a file based on its extension
+    #
+    # Supports updating versions in multiple file formats:
+    # - .yml files
+    # - .gemspec files
+    # - .csproj files
+    # - .nuspec files
+    # - .wxs files
+    # - .toml files
+    # - Directory.Build.props files (.NET projects)
+    #
+    # @param filename [String] Path to the file to update
+    # @param version [String] New version string to set
+    # @return [nil]
+    def self.set_version_in_file(filename, version)
+      # Handle Directory.Build.props files with special logic
+      if filename.include?("Directory.Build.props")
+        set_version_in_directory_build_props(filename, version)
+        return
+      end
+      
+      text = File.read(filename)
+      #   VERSION = "0.0.138rake" (.rb file)
+      new_text = text
+      new_text = new_text.gsub(/VERSION:\s?['|"]([.\d]+)['|"]/, "VERSION: \"#{version}\"") if filename.include?(".yml")
+      new_text = new_text.gsub(/spec\.version\s*=\s*['"]([^'"]+)['"]/, "spec.version = '#{version}'") if filename.include?(".gemspec")
+      # Handle Directory.Build.props and .csproj files (both use <Version> tag)
+      if filename.include?("Directory.Build.props") || filename.include?(".csproj")
+        new_text = new_text.gsub(/<Version>([-\w\d.]+)</, "<Version>#{version}<")
+      end
+      new_text = new_text.gsub(/<version>([-\w\d.]+)</, "<version>#{version}<") if filename.include?(".nuspec")
+      new_text = new_text.gsub(/ Version="([\d.]+)"/, " Version=\"#{version}\"") if filename.include?(".wxs")
+      new_text = new_text.gsub(/VERSION = "([\d.]+)"/, "VERSION = \"#{version}\"") if filename.include?(".rb")
+      # Handle Cargo.toml, pyproject.toml, and other .toml files
+      if filename.include?(".toml")
+        new_text = new_text.gsub(/version\s+=\s+['"]([\w.]+)['"]/, "version=\"#{version}\"")
+      end
+      # Handle package.json
+      if filename.include?("package.json")
+        require "json"
+        json = JSON.parse(new_text)
+        json["version"] = version
+        new_text = JSON.pretty_generate(json)
+      end
+      # Handle pom.xml
+      if filename.include?("pom.xml")
+        new_text = new_text.gsub(%r{<version>([^<]+)</version>}, "<version>#{version}</version>")
+      end
+      File.write(filename, new_text) if new_text != text
+    end
+
+    # Update version number in multiple files matching a glob pattern
+    #
+    # @param glob_pattern [String] Glob pattern to match files (e.g., '**/*.csproj')
+    # @param version [String] New version string to set in all matching files
+    # @return [nil]
+    def self.set_version_in_files(glob_pattern, version)
+      Dir.glob(glob_pattern).each do |filename|
+        set_version_in_file(filename, version)
+      end
+    end
+
+    # Display version information for the current project
+    #
+    # Finds the Single Source of Truth (SSOT) version file in the project root
+    # and displays the file path and current version value.
+    #
+    # Searches for common version files in priority order:
+    # * *.gemspec (Ruby gems)
+    # * Directory.Build.props (.NET projects)
+    # * Cargo.toml (Rust projects)
+    # * package.json (Node.js projects)
+    # * pyproject.toml (Python projects)
+    # * pom.xml (Maven/Java projects)
+    #
+    # If no version file is found, issues a warning and suggests defining a VERSION_FILE
+    # constant to manually specify the version file path.
+    #
+    # @return [nil] Outputs version information to stdout, or returns early with warning if no file found
+    # @raise [RuntimeError] If project root cannot be determined or version cannot be extracted from file
+    #
+    # @example Output format
+    #   Version File: makit.gemspec
+    #   Version: 0.0.147
+    #
+    # @example With VERSION_FILE constant defined
+    #   VERSION_FILE = "custom/version.txt"
+    #   Makit::Version.info
+    #   # Uses the file specified by VERSION_FILE constant
+    #
+    def self.info
+      # Access Directories lazily to avoid circular dependency
+      project_root = begin
+        require_relative "directories" unless defined?(Makit::Directories)
+        Makit::Directories::PROJECT_ROOT
+      rescue NameError, LoadError
+        # Fallback: try to find project root from current directory
+        find_project_root(Dir.pwd)
+      end
+
+      raise "Project root not found" if project_root.nil? || !Dir.exist?(project_root)
+
+      version_file = find_ssot_version_file(project_root)
+      
+      if version_file.nil?
+        warn "  Warning: No version file found in project root: #{project_root}"
+        warn "  You may define a constant VERSION_FILE to manually set the version file path"
+        return
+      end
+
+      # Extract version based on file type
+      version = extract_version_from_ssot_file(version_file)
+
+      raise "Version not found in #{version_file}" if version.nil?
+
+      # Display information with relative path (Windows-safe path handling)
+      # Normalize both paths to forward slashes for comparison, then convert back if needed
+      normalized_version_file = version_file.gsub(/\\/, "/")
+      normalized_project_root = project_root.gsub(/\\/, "/")
+      relative_path = normalized_version_file.sub(normalized_project_root + "/", "")
+      puts "  Version File: #{relative_path}"
+      puts "  Version: #{version}"
+    end
+
+    # Bump the patch version in the SSOT version file
+    #
+    # Finds the Single Source of Truth (SSOT) version file in the project root,
+    # reads the current version, increments the patch version, and updates the file.
+    #
+    # @return [String] The new version string after bumping
+    # @raise [RuntimeError] If project root cannot be determined, no version file is found,
+    #   or version cannot be parsed/updated
+    #
+    # @example
+    #   # Current version: 1.2.3
+    #   Makit::Version.bump
+    #   # => "1.2.4"
+    #
+    # @example With pre-release suffix
+    #   # Current version: 1.2.3-alpha
+    #   Makit::Version.bump
+    #   # => "1.2.4" (removes pre-release suffix when bumping)
+    #
+    def self.bump
+      # Find the SSOT version file
+      project_root = begin
+        require_relative "directories" unless defined?(Makit::Directories)
+        Makit::Directories::PROJECT_ROOT
+      rescue NameError, LoadError
+        find_project_root(Dir.pwd)
+      end
+
+      raise "Project root not found" if project_root.nil? || !Dir.exist?(project_root)
+
+      version_file = find_ssot_version_file(project_root)
+      if version_file.nil?
+        warn "  Warning: No version file found in project root: #{project_root}"
+        warn "  You may define a constant VERSION_FILE to manually set the version file path"
+        raise "Cannot bump version: no version file found"
+      end
+
+      # Read current version
+      current_version = extract_version_from_ssot_file(version_file)
+      raise "Version not found in #{version_file}" if current_version.nil?
+
+      # Parse and bump patch version
+      parsed = parse(current_version)
+      new_version = "#{parsed[:major]}.#{parsed[:minor]}.#{parsed[:patch] + 1}"
+
+      # Update the version file
+      set_version_in_file(version_file, new_version)
+
+      # Verify the update
+      updated_version = extract_version_from_ssot_file(version_file)
+      if updated_version != new_version
+        raise "Version bump failed: expected #{new_version}, got #{updated_version}"
+      end
+
+      new_version
+    end
+
+    private
+
+    # Find the SSOT version file in the project root
+    #
+    # Checks for VERSION_FILE constant first (if defined), then searches for common version files.
+    #
+    # @param project_root [String] Path to the project root directory
+    # @return [String, nil] Path to the version file, or nil if not found
+    def self.find_ssot_version_file(project_root)
+      # Normalize project_root for file operations (Ruby's File methods work with forward slashes)
+      normalized_root = project_root.gsub(/\\/, "/")
+      
+      # Check for manually defined VERSION_FILE constant first
+      if defined?(VERSION_FILE) && !VERSION_FILE.nil?
+        version_file = File.expand_path(VERSION_FILE, normalized_root)
+        return version_file if File.exist?(version_file)
+        warn "  Warning: VERSION_FILE constant points to non-existent file: #{VERSION_FILE}"
+      end
+
+      # Priority order for version files (SSOT)
+      version_file_patterns = [
+        "*.gemspec",                    # Ruby gems
+        "Directory.Build.props",        # .NET projects
+        "Cargo.toml",                   # Rust projects
+        "package.json",                 # Node.js projects
+        "pyproject.toml",               # Python projects
+        "pom.xml"                       # Maven/Java projects
+      ]
+
+      version_file_patterns.each do |pattern|
+        matches = Dir.glob(File.join(normalized_root, pattern))
+        next if matches.empty?
+
+        # For gemspec, prefer the one matching the project name or take the first
+        version_file = matches.first
+        return version_file if version_file
+      end
+
+      nil
+    end
+
+    # Find project root by looking for common markers
+    def self.find_project_root(start_dir)
+      current = File.expand_path(start_dir)
+      root = File.expand_path("/")
+
+      while current != root
+        markers = ["Rakefile", "rakefile.rb", ".gitignore", ".git"]
+        return current if markers.any? { |marker| File.exist?(File.join(current, marker)) }
+        current = File.dirname(current)
+      end
+
+      nil
+    end
+
+    # Normalize version string for parsing (strip metadata, handle 3/4-part)
+    #
+    # Strips build metadata (+abc123), handles 3-part and 4-part versions,
+    # and trims whitespace.
+    #
+    # @param version_string [String] Version string to normalize
+    # @return [String] Normalized version string
+    #
+    # @example
+    #   normalize_version_for_parsing("0.1.1+abc123") # => "0.1.1"
+    #   normalize_version_for_parsing("0.1.1.0")      # => "0.1.1.0"
+    #   normalize_version_for_parsing(" 0.1.1 ")      # => "0.1.1"
+    def self.normalize_version_for_parsing(version_string)
+      return nil if version_string.nil?
+      
+      # Trim whitespace
+      normalized = version_string.strip
+      
+      # Strip build metadata (e.g., "+abc123")
+      normalized = normalized.split("+").first if normalized.include?("+")
+      
+      normalized
+    end
+
+    # Extract SemVer (3-part) from version string (handles 4-part)
+    #
+    # If version is 4-part (x.y.z.w), extracts first 3 parts (x.y.z).
+    # If 3-part, returns as-is. Strips pre-release and build metadata.
+    #
+    # @param version_string [String] Version string (3-part or 4-part)
+    # @return [String] 3-part SemVer version string
+    #
+    # @example
+    #   extract_semver_from_version("0.1.1.0")      # => "0.1.1"
+    #   extract_semver_from_version("0.1.1")        # => "0.1.1"
+    #   extract_semver_from_version("0.1.1-alpha") # => "0.1.1"
+    def self.extract_semver_from_version(version_string)
+      normalized = normalize_version_for_parsing(version_string)
+      return nil if normalized.nil?
+      
+      # Strip pre-release suffix (e.g., "-alpha", "-beta.1")
+      normalized = normalized.split("-").first if normalized.include?("-")
+      
+      # Split by dots to check if 4-part
+      parts = normalized.split(".")
+      
+      # If 4-part, extract first 3 parts
+      if parts.length >= 4
+        "#{parts[0]}.#{parts[1]}.#{parts[2]}"
+      elsif parts.length == 3
+        normalized
+      else
+        # Invalid format, return as-is (will be caught by parse method)
+        normalized
+      end
+    end
+
+    # Convert SemVer to 4-part format
+    #
+    # Converts "x.y.z" to "x.y.z.0". Handles pre-release suffixes by stripping them.
+    #
+    # @param version_string [String] SemVer version string (x.y.z)
+    # @return [String] 4-part version string (x.y.z.0)
+    #
+    # @example
+    #   semver_to_four_part("0.1.2")        # => "0.1.2.0"
+    #   semver_to_four_part("0.1.2-alpha")  # => "0.1.2.0"
+    def self.semver_to_four_part(version_string)
+      # Extract SemVer first (handles pre-release suffixes)
+      semver = extract_semver_from_version(version_string)
+      return nil if semver.nil?
+      
+      # Ensure it's 3-part, then append .0
+      parts = semver.split(".")
+      if parts.length == 3
+        "#{parts[0]}.#{parts[1]}.#{parts[2]}.0"
+      else
+        # If already 4-part or invalid, return as-is
+        semver
+      end
+    end
+
+    # Update Directory.Build.props file with new version
+    #
+    # Reads file, updates <Version>, <AssemblyVersion>, and <FileVersion> elements
+    # in all PropertyGroups, preserves XML structure, and performs atomic operation.
+    #
+    # @param filename [String] Path to Directory.Build.props file
+    # @param new_version [String] New SemVer version string (x.y.z)
+    # @return [nil]
+    # @raise [RuntimeError] If <Version> element is missing or update fails
+    def self.set_version_in_directory_build_props(filename, new_version)
+      # Read file content
+      content = File.read(filename)
+      
+      # Validate that <Version> element exists
+      unless content.match(%r{<Version>([^<]+)</Version>})
+        raise "Directory.Build.props file does not contain <Version> element: #{filename}"
+      end
+      
+      # Extract SemVer from new_version (in case it's 4-part or has metadata)
+      semver_version = extract_semver_from_version(new_version)
+      raise "Invalid version format: #{new_version}" if semver_version.nil?
+      
+      # Convert to 4-part format for AssemblyVersion and FileVersion
+      four_part_version = semver_to_four_part(semver_version)
+      raise "Failed to convert version to 4-part format: #{semver_version}" if four_part_version.nil?
+      
+      # Prepare updated content (start with original)
+      updated_content = content.dup
+      
+      # Update <Version> element (preserve XML structure)
+      # Pattern: captures opening tag, whitespace, content, whitespace, closing tag
+      version_pattern = %r{(<Version>)\s*([^<]+?)\s*(</Version>)}
+      if updated_content.match(version_pattern)
+        updated_content = updated_content.gsub(version_pattern) do |match|
+          "#{$1}#{semver_version}#{$3}"
+        end
+      else
+        raise "Failed to update <Version> element in #{filename}"
+      end
+      
+      # Update <AssemblyVersion> element if present (preserve XML structure)
+      assembly_version_pattern = %r{(<AssemblyVersion>)\s*([^<]+?)\s*(</AssemblyVersion>)}
+      if updated_content.match(assembly_version_pattern)
+        updated_content = updated_content.gsub(assembly_version_pattern) do |match|
+          "#{$1}#{four_part_version}#{$3}"
+        end
+      end
+      # Note: If AssemblyVersion doesn't exist, we don't add it (per FR-006)
+      
+      # Update <FileVersion> element if present (preserve XML structure)
+      file_version_pattern = %r{(<FileVersion>)\s*([^<]+?)\s*(</FileVersion>)}
+      if updated_content.match(file_version_pattern)
+        updated_content = updated_content.gsub(file_version_pattern) do |match|
+          "#{$1}#{four_part_version}#{$3}"
+        end
+      end
+      # Note: If FileVersion doesn't exist, we don't add it (per FR-006)
+      
+      # Atomic write: only write if content changed
+      if updated_content != content
+        File.write(filename, updated_content)
+      end
+    end
+
+    # Extract version from SSOT file based on file type
+    def self.extract_version_from_ssot_file(file_path)
+      case File.basename(file_path)
+      when /\.gemspec$/
+        # Extract from gemspec: spec.version = "x.y.z"
+        content = File.read(file_path)
+        match = content.match(/spec\.version\s*=\s*["']([^"']+)["']/)
+        match ? match[1] : nil
+      when "Directory.Build.props"
+        # Extract from Directory.Build.props: <Version>x.y.z</Version>
+        content = File.read(file_path)
+        match = content.match(%r{<Version>([^<]+)</Version>})
+        if match
+          # Trim whitespace and normalize (strip build metadata)
+          normalize_version_for_parsing(match[1])
+        else
+          nil
+        end
+      when "Cargo.toml"
+        # Extract from Cargo.toml: version = "x.y.z"
+        content = File.read(file_path)
+        match = content.match(/version\s*=\s*["']([^"']+)["']/)
+        match ? match[1] : nil
+      when "package.json"
+        # Extract from package.json: "version": "x.y.z"
+        require "json"
+        json = JSON.parse(File.read(file_path))
+        json["version"]
+      when "pyproject.toml"
+        # Extract from pyproject.toml: version = "x.y.z" (in [project] or [tool.poetry] section)
+        content = File.read(file_path)
+        # Try [project] section first
+        match = content.match(/\[project\]\s*version\s*=\s*["']([^"']+)["']/)
+        return match[1] if match
+        # Try [tool.poetry] section
+        match = content.match(/\[tool\.poetry\]\s*version\s*=\s*["']([^"']+)["']/)
+        match ? match[1] : nil
+      when "pom.xml"
+        # Extract from pom.xml: <version>x.y.z</version>
+        content = File.read(file_path)
+        match = content.match(%r{<version>([^<]+)</version>})
+        match ? match[1] : nil
+      else
+        nil
+      end
+    end
+  end
+end