versionian 0.1.0

data/docs/index.adoc

@@ -0,0 +1,287 @@
+---
+layout: default
+title: Overview
+nav_order: 1
+---
+
+= Versionian: Declarative versioning schemes
+
+image:https://img.shields.io/gem/v/versionian.svg[RubyGems Version]
+image:https://img.shields.io/github/license/lutaml/versionian.svg[License]
+image:https://github.com/lutaml/versionian/actions/workflows/rake.yml/badge.svg["Build", link="https://github.com/lutaml/versionian/actions/workflows/rake.yml"]
+
+== Purpose
+
+Versionian is a Ruby library for declaring, parsing, comparing, and rendering version schemes.
+It provides model-driven primitives for defining how versions work, supporting semantic versioning, calendar versioning, and unlimited custom schemes through declarative YAML configuration.
+
+=== Why Versionian?
+
+Ruby's built-in `Gem::Version` handles semantic versioning well, but real-world projects use diverse versioning schemes that `Gem::Version` cannot parse or compare correctly:
+
+* **Calendar versioning** (`2024.01.17`, `2024.03`) - `Gem::Version` parses these but cannot enforce date validation
+* **Single-number versioning** (`5`, `5+hotfix`, `5-beta`) - `Gem::Version` treats postfixes incorrectly
+* **Human-readable versions** (`Alpha.1.5`, `Beta.2.0`) - `Gem::Version` cannot compare these
+* **Hash-based versions** (`2024.01.abc123`) - `Gem::Version` has no concept of commit hashes
+* **Custom schemes** - Every project has unique versioning needs
+
+=== How Versionian is different
+
+[width="100%",cols="3*m,4*m,3*m"]
+|===
+|Feature |Gem::Version |Versionian
+
+|Supported schemes
+|Semantic versioning only
+|4 built-in schemes, unlimited custom
+
+|Extensibility
+|Not extensible
+|Define custom schemes via declarative YAML or Ruby
+
+|Component types
+|Integers and dot-separated strings
+|Integer, Float, Enum, DatePart, Hash, Postfix, Prerelease, String, Wildcard
+
+|Comparison strategy
+|Fixed SemVer rules
+|Per-scheme comparison (lexicographic arrays)
+
+|Validation
+|Basic format validation
+|Type-aware validation (date ranges, enum values, hash formats)
+
+|Programmatic building
+|Not supported
+|Build versions from component values
+|===
+
+Versionian fills the gap between `Gem::Version`'s semantic versioning focus and the diverse versioning needs of real-world projects.
+
+== Features
+
+* link:core-topics/schemes.html[Built-in schemes] - SemVer, CalVer, SoloVer, WendtVer
+* link:core-topics/declarative-schemes.html[Declarative schemes] - Custom via YAML
+* link:core-topics/component-types.html[Component types] - Extensible type system
+* link:core-topics/range-matching.html[Range matching] - Version range comparisons
+* link:guides/custom-schemes.html[Custom Ruby schemes] - Ruby API for custom schemes
+* link:references/api.html[API reference] - Complete API documentation
+
+== Quick start
+
+Get started with Versionian in three steps:
+
+.Require the library
+[source,ruby]
+----
+require 'versionian'
+----
+
+.Parse and compare versions
+[source,ruby]
+----
+# Use built-in semantic versioning
+scheme = Versionian.get_scheme(:semantic)
+
+version = scheme.parse("1.12.0")
+puts version.to_s  # => "1.12.0"
+
+# Compare versions
+result = scheme.compare("1.12.0", "2.0.0")
+puts result  # => -1 (less than)
+----
+
+.Declare a custom scheme via YAML
+[source,yaml]
+----
+# schemes/my_scheme.yaml
+name: my_scheme
+type: declarative
+description: Custom version scheme
+components:
+  - name: major
+    type: integer
+    separator: "."
+  - name: minor
+    type: integer
+    separator: "."
+  - name: patch
+    type: integer
+    optional: true
+----
+
+[source,ruby]
+----
+# Load and use custom scheme
+scheme = Versionian::SchemeLoader.from_yaml_file('schemes/my_scheme.yaml')
+Versionian.register_scheme(:my_scheme, scheme)
+
+version = scheme.parse("1.2.3")
+puts version.major  # => 1
+----
+
+== Discovering available schemes
+
+Versionian provides several ways to discover available schemes:
+
+.List registered schemes
+[source,ruby]
+----
+# List all registered scheme names
+scheme_names = Versionian.scheme_registry.registered
+puts scheme_names.inspect  # => [:semantic, :calver, :solover, :wendtver]
+
+# Check if a scheme exists
+Versionian.scheme_registry.registered.include?(:semantic)  # => true
+----
+
+.Detect scheme from version string
+[source,ruby]
+----
+# Auto-detect which scheme matches a version string
+detected = Versionian.detect_scheme("1.2.3")
+puts detected.name  # => :semantic
+
+detected = Versionian.detect_scheme("2024.01.17")
+puts detected.name  # => :calver
+
+detected = Versionian.detect_scheme("5+hotfix")
+puts detected.name  # => :solover
+
+# Returns nil for unrecognised version strings
+detected = Versionian.detect_scheme("not-a-version")
+puts detected  # => nil
+----
+
+.Get and use a scheme
+[source,ruby]
+----
+# Get a scheme by name
+scheme = Versionian.get_scheme(:semantic)
+
+# Check scheme capabilities
+puts scheme.supports?("1.2.3")    # => true
+puts scheme.supports?("invalid")  # => false
+
+# Parse and compare
+version = scheme.parse("1.12.0")
+puts version.to_s  # => "1.12.0"
+
+# Raises error for unknown schemes
+begin
+  Versionian.get_scheme(:unknown)
+rescue Versionian::Errors::InvalidSchemeError => e
+  puts e.message  # => "Unknown scheme: unknown"
+end
+----
+
+== Architecture
+
+Versionian follows a model-driven architecture where version schemes define their own parsing, comparison, and rendering behavior.
+
+=== Lexicographic array comparison
+
+Versionian uses lexicographic array comparison instead of weighted integer sums. Each version stores a `comparable_array` where each element represents a component in comparison order:
+
+[source,ruby]
+----
+# Version stores array for comparison
+version.comparable_array  # => [2024, 1, 17, :rc, 1]
+
+# Comparison is element-by-element
+[2024, 1, 17] <=> [2024, 1, 18]  # => -1
+[2024, 1, 17] <=> [2024, 2, 1]   # => -1
+[2024, 1, 17] <=> [2024, 1, 17]  # => 0
+----
+
+This approach avoids integer overflow, provides better performance, and allows each component type to define its own comparison semantics.
+
+=== Parse versus build
+
+Versionian provides two ways to create version identifiers:
+
+* **Parse**: Extract components from a version string
+* **Build**: Create a version from component values
+
+[source,ruby]
+----
+# Parse: from string
+version = scheme.parse("1.12.0")
+
+# Build: from component values
+version = scheme.build(major: 1, minor: 12, patch: 0)
+----
+
+Both methods return the same `VersionIdentifier` object with a `comparable_array` for comparison.
+
+=== Object model
+
+.Versionian object model
+[source]
+----
+Versionian::VersionScheme (abstract)
+├── parse(version_string) -> VersionIdentifier
+├── build(component_values) -> VersionIdentifier
+├── compare_arrays(a, b) -> Integer
+├── render(version) -> String
+└── matches_range?(version_string, range) -> Boolean
+
+Implemented Schemes:
+├── Semantic (SemVer)
+├── CalVer (Calendar versioning)
+├── SoloVer (Single number with postfix)
+├── WendtVer (Auto-incrementing)
+└── Declarative (Custom segment-based)
+
+VersionIdentifier objects:
+├── raw_string (original input)
+├── scheme (reference to scheme)
+├── components (array of VersionComponent)
+└── comparable_array (for lexicographic comparison)
+
+Component type registry:
+├── Integer (numeric sequences)
+├── Float (IEEE754 floats)
+├── String (arbitrary text)
+├── Enum (ordered stages)
+├── DatePart (calendar components)
+├── Prerelease (SemVer prereleases)
+├── Postfix (SoloVer suffixes)
+├── Hash (git commit hashes)
+└── Custom types (user-defined)
+----
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem 'versionian'
+----
+
+And then execute:
+
+[source,shell]
+----
+bundle install
+----
+
+Or install it yourself as:
+
+[source,shell]
+----
+gem install versionian
+----
+
+== Contributing
+
+. Fork the repository
+. Create your feature branch (`git checkout -b my-new-feature`)
+. Commit your changes (`git commit -am 'Add some feature'`)
+. Push to the branch (`git push origin my-new-feature`)
+. Create a new Pull Request
+
+== License
+
+MIT License - see LICENSE file for details.

data/lib/versionian/component_definition.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Versionian
+  class ComponentDefinition
+    attr_reader :name, :type, :subtype, :values, :order, :weight, :optional, :ignore_in_comparison, :default,
+                :compare_as, :separator, :prefix, :suffix, :min_count, :max_count, :validate, :include_prefix_in_value
+
+    def initialize(**attrs)
+      @name = attrs[:name]
+      @type = attrs[:type]
+      @subtype = attrs[:subtype]
+      @values = attrs[:values] || []
+      @order = attrs[:order] || []
+      @weight = attrs[:weight] || 1
+      @optional = attrs[:optional] || false
+      @ignore_in_comparison = attrs[:ignore_in_comparison] || false
+      @default = attrs[:default]
+      @compare_as = attrs[:compare_as]
+      @separator = attrs[:separator]
+      @prefix = attrs[:prefix]
+      @suffix = attrs[:suffix]
+      @min_count = attrs[:min_count] || 1
+      @max_count = attrs[:max_count] || 1
+      @validate = attrs[:validate] || {}
+      @include_prefix_in_value = attrs[:include_prefix_in_value] || false
+      freeze
+    end
+
+    def self.from_hash(hash)
+      new(
+        name: hash["name"]&.to_sym || hash[:name],
+        type: hash["type"]&.to_sym || hash[:type],
+        subtype: hash["subtype"] || hash[:subtype],
+        values: (hash["values"] || hash[:values] || []).map(&:to_sym),
+        order: (hash["order"] || hash[:order] || []).map(&:to_sym),
+        weight: hash["weight"] || hash[:weight],
+        optional: hash["optional"] || hash[:optional],
+        ignore_in_comparison: hash["ignore_in_comparison"] || hash[:ignore_in_comparison],
+        default: hash["default"] || hash[:default],
+        compare_as: hash["compare_as"] || hash[:compare_as],
+        separator: hash["separator"] || hash[:separator],
+        prefix: hash["prefix"] || hash[:prefix],
+        suffix: hash["suffix"] || hash[:suffix],
+        min_count: hash["min_count"] || hash[:min_count] || 1,
+        max_count: hash["max_count"] || hash[:max_count] || 1,
+        validate: hash["validate"] || hash[:validate] || {},
+        include_prefix_in_value: hash["include_prefix_in_value"] || hash[:include_prefix_in_value]
+      )
+    end
+
+    def validate!
+      raise Errors::InvalidSchemeError, "name is required" unless @name
+      raise Errors::InvalidSchemeError, "type is required" unless @type
+    end
+
+    # Check if this component definition defines a separator
+    def has_separator?
+      !@separator.nil? && !@separator.empty?
+    end
+
+    # Check if this component definition defines a prefix
+    def has_prefix?
+      !@prefix.nil? && !@prefix.empty?
+    end
+
+    # Check if this component definition defines a suffix
+    def has_suffix?
+      !@suffix.nil? && !@suffix.empty?
+    end
+  end
+end

data/lib/versionian/component_types/base.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Versionian
+  module ComponentTypes
+    class Base
+      def self.parse(value, definition)
+        raise NotImplementedError, "#{self} must implement .parse"
+      end
+
+      def self.to_comparable(value, definition)
+        raise NotImplementedError, "#{self} must implement .to_comparable"
+      end
+
+      def self.format(value)
+        raise NotImplementedError, "#{self} must implement .format"
+      end
+    end
+  end
+end

data/lib/versionian/component_types/date_part.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Versionian
+  module ComponentTypes
+    class DatePart < Base
+      RANGES = {
+        year: [1, 9999],
+        month: [1, 12],
+        day: [1, 31],
+        week: [1, 53],
+        hour: [0, 23],
+        minute: [0, 59],
+        second: [0, 59]
+      }.freeze
+
+      def self.parse(value, definition)
+        return definition.default.to_i if value.nil? || value.empty?
+
+        int_val = Kernel.Integer(value)
+
+        subtype = definition.subtype
+        if subtype && RANGES.key?(subtype.to_sym)
+          min, max = RANGES[subtype.to_sym]
+          unless int_val.between?(min, max)
+            raise Errors::ParseError, "Invalid #{subtype} '#{int_val}'. Must be between #{min} and #{max}"
+          end
+        end
+
+        int_val
+      end
+
+      def self.to_comparable(value, _definition)
+        value
+      end
+
+      def self.format(value)
+        value.to_s.rjust(2, "0")
+      end
+    end
+  end
+end

data/lib/versionian/component_types/enum.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Versionian
+  module ComponentTypes
+    class Enum < Base
+      def self.parse(value, definition)
+        return nil if value.nil? || value.empty?
+
+        sym = value.to_sym
+
+        if definition.values && !definition.values.empty? && !definition.values.include?(sym)
+          raise Errors::ParseError,
+                "Invalid enum value '#{value}' for #{definition.name}. Allowed: #{definition.values.join(", ")}"
+        end
+
+        sym
+      end
+
+      def self.to_comparable(value, definition)
+        return ::Float::INFINITY if value.nil?
+
+        # Use the definition's order array
+        order = definition.order || []
+        order.index(value) || (order.length + 1)
+      end
+
+      def self.format(value)
+        value.nil? ? "" : value.to_s
+      end
+    end
+  end
+end

data/lib/versionian/component_types/float.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Versionian
+  module ComponentTypes
+    class Float < Base
+      def self.parse(value, definition)
+        return definition.default.to_f if value.nil? || value.empty?
+
+        ::Kernel.Float(value)
+      rescue ArgumentError, TypeError => e
+        raise Errors::ParseError, "Invalid float '#{value}': #{e.message}"
+      end
+
+      def self.to_comparable(value, _definition)
+        value
+      end
+
+      def self.format(value)
+        value.to_s
+      end
+    end
+  end
+end

data/lib/versionian/component_types/hash.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Versionian
+  module ComponentTypes
+    class Hash < Base
+      def self.parse(value, definition)
+        return definition.default if value.nil? || value.empty?
+
+        value.downcase # Normalize to lowercase
+      end
+
+      def self.to_comparable(value, _definition)
+        [value.length, value] # Compare by length first, then lexicographically
+      end
+
+      def self.format(value)
+        value
+      end
+    end
+  end
+end

data/lib/versionian/component_types/integer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Versionian
+  module ComponentTypes
+    class Integer < Base
+      def self.parse(value, definition)
+        return definition.default.to_i if value.nil? || value.empty?
+
+        Kernel.Integer(value)
+      rescue ArgumentError, TypeError => e
+        raise Errors::ParseError, "Invalid integer '#{value}': #{e.message}"
+      end
+
+      def self.to_comparable(value, _definition)
+        value
+      end
+
+      def self.format(value)
+        value.to_s
+      end
+    end
+  end
+end

data/lib/versionian/component_types/postfix.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Versionian
+  module ComponentTypes
+    class Postfix < Base
+      # Postfix format: [+|-]identifier
+      # + means "after" (hotfix)
+      # - means "before" (prerelease)
+      # No postfix is in the middle
+
+      def self.parse(value, _definition)
+        return nil if value.nil? || value.empty?
+
+        prefix = value[0]
+        identifier = value[1..]
+
+        { prefix: prefix, identifier: identifier }
+      end
+
+      def self.to_comparable(value, _definition)
+        return 0 if value.nil?
+
+        # Ordering: none (0) < + (1) < - (2)
+        case value[:prefix]
+        when "+" then 1
+        when "-" then 2
+        else 0
+        end
+      end
+
+      def self.format(value)
+        return "" if value.nil?
+
+        "#{value[:prefix]}#{value[:identifier]}"
+      end
+
+      def self.compare_postfixes(a, b)
+        return 0 if a.nil? && b.nil?
+        return -1 if a.nil? # No postfix < +postfix
+        return 1 if b.nil?
+
+        # Compare by prefix first
+        prefix_cmp = to_comparable(a) <=> to_comparable(b)
+        return prefix_cmp if prefix_cmp != 0
+
+        # Same prefix, compare identifier lexicographically
+        a[:identifier] <=> b[:identifier]
+      end
+    end
+  end
+end

data/lib/versionian/component_types/prerelease.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Versionian
+  module ComponentTypes
+    class Prerelease < Base
+      def self.parse(value, _definition)
+        return nil if value.nil? || value.empty?
+
+        # Split by dots: "alpha.1" => ["alpha", "1"]
+        value.split(".").map do |part|
+          if part =~ /^\d+$/
+            part.to_i
+          else
+            part.to_sym
+          end
+        end
+      end
+
+      def self.to_comparable(value, _definition)
+        # Compare according to SemVer rules
+        # nil > any prerelease
+        return [1] if value.nil?
+
+        value
+      end
+
+      def self.format(value)
+        return "" if value.nil?
+
+        value.map(&:to_s).join(".")
+      end
+
+      # Custom comparison for SemVer prerelease rules
+      def self.compare_prerelease_arrays(a, b)
+        return 0 if a.nil? && b.nil?
+        return 1 if a.nil? # nil > any prerelease
+        return -1 if b.nil?
+
+        max_len = [a.length, b.length].max
+        max_len.times do |i|
+          a_val = a[i]
+          b_val = b[i]
+
+          # Missing identifier = lower priority
+          return -1 if a_val.nil?
+          return 1 if b_val.nil?
+
+          # Numeric < alphanumeric
+          a_is_num = a_val.is_a?(Integer)
+          b_is_num = b_val.is_a?(Integer)
+
+          if a_is_num && !b_is_num
+            return -1
+          elsif !a_is_num && b_is_num
+            return 1
+          elsif a_is_num && b_is_num
+            cmp = a_val <=> b_val
+            return cmp if cmp != 0
+          else
+            cmp = a_val.to_s <=> b_val.to_s
+            return cmp if cmp != 0
+          end
+        end
+
+        # All equal up to here, shorter is lower priority
+        a.length <=> b.length
+      end
+    end
+  end
+end

data/lib/versionian/component_types/registry.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Versionian
+  module ComponentTypes
+    # Autoload component type classes
+    autoload :Base, "versionian/component_types/base"
+    autoload :Integer, "versionian/component_types/integer"
+    autoload :Float, "versionian/component_types/float"
+    autoload :Enum, "versionian/component_types/enum"
+    autoload :String, "versionian/component_types/string"
+    autoload :DatePart, "versionian/component_types/date_part"
+    autoload :Prerelease, "versionian/component_types/prerelease"
+    autoload :Postfix, "versionian/component_types/postfix"
+    autoload :Hash, "versionian/component_types/hash"
+
+    @types = {}
+    @mutex = Mutex.new
+
+    class << self
+      def register(name, type_class)
+        @mutex.synchronize do
+          @types[name] = type_class
+        end
+      end
+
+      def resolve(type)
+        @types[type] || raise(Errors::InvalidSchemeError, "Unknown component type: #{type}")
+      end
+
+      def registered
+        @types.keys
+      end
+    end
+  end
+end

data/lib/versionian/component_types/string.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Versionian
+  module ComponentTypes
+    class String < Base
+      def self.parse(value, definition)
+        return definition.default || "" if value.nil? || value.empty?
+
+        value.to_s
+      end
+
+      def self.to_comparable(value, _definition)
+        value
+      end
+
+      def self.format(value)
+        value
+      end
+    end
+  end
+end