versionian 0.1.0

data/lib/versionian/errors/invalid_scheme_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Versionian
+  module Errors
+    class InvalidSchemeError < StandardError; end
+  end
+end

data/lib/versionian/errors/invalid_version_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Versionian
+  module Errors
+    class InvalidVersionError < StandardError; end
+  end
+end

data/lib/versionian/errors/parse_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Versionian
+  module Errors
+    class ParseError < StandardError; end
+  end
+end

data/lib/versionian/parsers/declarative.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module Versionian
+  module Parsers
+    # Parses version strings based on declarative segment definitions.
+    # Uses a state machine approach instead of regex for implementation independence.
+    class Declarative
+      attr_reader :segment_definitions
+
+      # @param segment_definitions [Array<ComponentDefinition>] Ordered segment definitions
+      def initialize(segment_definitions)
+        @segment_definitions = segment_definitions
+        validate_definitions!
+      end
+
+      # Parse a version string into component values.
+      #
+      # @param version_string [String] The version string to parse
+      # @return [Hash] Component values keyed by component name
+      # @raise [Errors::ParseError] If the version string doesn't match the schema
+      def parse(version_string)
+        raise Errors::ParseError, "Version string cannot be empty" if version_string.nil? || version_string.empty?
+
+        position = 0
+        results = {}
+
+        @segment_definitions.each_with_index do |segment, index|
+          # For optional segments with prefix, check if the prefix is present
+          # If the prefix was used as a boundary marker by the previous segment,
+          # we need to handle this case specially
+          if segment.optional && segment.prefix
+            if position >= version_string.length
+              results[segment.name] = nil
+              next
+            end
+
+            # Check if the defined prefix is present at the current position
+            prefix_at_position = version_string[position, segment.prefix.length] == segment.prefix
+
+            # Check if the prefix was just before our current position
+            # (meaning it was used as a boundary marker)
+            prefix_before_position = position >= segment.prefix.length &&
+              version_string[position - segment.prefix.length, segment.prefix.length] == segment.prefix
+
+            # For include_prefix_in_value, check if we're at a prefix-like character
+            prefix_like_char = segment.include_prefix_in_value &&
+              ["+", "-"].include?(version_string[position, 1])
+
+            prefix_present = prefix_at_position || prefix_before_position || prefix_like_char
+
+            unless prefix_present
+              results[segment.name] = nil
+              next
+            end
+
+            # If prefix was before our position, we're already past it, so don't consume again
+            # If prefix is at our position, consume it (unless include_prefix_in_value)
+            if prefix_at_position
+              unless segment.include_prefix_in_value
+                position += segment.prefix.length
+              end
+            end
+          end
+
+          # Find where this segment ends (look ahead to next segment's markers)
+          end_pos = find_segment_end_position(version_string, position, index)
+
+          # Extract raw value
+          raw_value = version_string[position...end_pos]
+
+          if raw_value.nil? || raw_value.empty?
+            if segment.optional
+              results[segment.name] = nil
+              next
+            else
+              raise Errors::ParseError,
+                    "Required segment '#{segment.name}' is missing or empty"
+            end
+          end
+
+          # Parse the value
+          component_type = ComponentTypes.resolve(segment.type)
+          parsed_value = component_type.parse(raw_value, segment)
+          results[segment.name] = parsed_value
+
+          # Advance position to end of this segment's value
+          position = end_pos
+
+          # After processing this segment, consume the separator for the next segment
+          # The separator is defined on the CURRENT segment and comes BEFORE the next segment
+          if segment.separator && !segment.separator.empty?
+            if position < version_string.length
+              if version_string[position, segment.separator.length] == segment.separator
+                position += segment.separator.length
+              end
+              # If separator not found at position, the next segment will handle it
+            end
+          end
+        end
+
+        # Check that we consumed the entire string
+        if position < version_string.length
+          remaining = version_string[position..-1]
+          raise Errors::ParseError,
+                "Unexpected trailing content after parsing: '#{remaining}'"
+        end
+
+        results
+      end
+
+      # Check if a version string matches this schema.
+      #
+      # @param version_string [String]
+      # @return [Boolean]
+      def match?(version_string)
+        parse(version_string)
+        true
+      rescue Errors::ParseError, Errors::InvalidVersionError
+        false
+      end
+
+      private
+
+      # Find the end position of this segment in the version string.
+      #
+      # The end position is determined by finding the earliest occurrence of:
+      # - This segment's own separator (if any) - the separator comes AFTER the value
+      # - The next segment's prefix (if any) - prefix comes BEFORE the next value
+      # - The next segment's separator (if this segment has no separator)
+      # - End of string (fallback)
+      #
+      # @param string [String] The version string
+      # @param position [Integer] Current position in the string
+      # @param segment_index [Integer] Index of current segment
+      # @return [Integer] End position of this segment
+      def find_segment_end_position(string, position, segment_index)
+        candidates = [string.length]
+        current_segment = @segment_definitions[segment_index]
+
+        # Check for current segment's own separator (comes after this segment's value)
+        if current_segment.separator && !current_segment.separator.empty?
+          sep_pos = string.index(current_segment.separator, position)
+          candidates << sep_pos if sep_pos && sep_pos >= position
+        end
+
+        # Look for next segment's markers (separators and prefixes)
+        ((segment_index + 1)...@segment_definitions.length).each do |next_idx|
+          next_segment = @segment_definitions[next_idx]
+
+          # Check for next segment's separator (always valid as a boundary)
+          if next_segment.separator && !next_segment.separator.empty?
+            sep_pos = string.index(next_segment.separator, position)
+            candidates << sep_pos if sep_pos && sep_pos >= position
+          end
+
+          # Check for next segment's prefix (always valid as a boundary)
+          if next_segment.prefix && !next_segment.prefix.empty?
+            # Check if the prefix exists in the remaining string (from position onwards)
+            remaining = string[position..]
+            found_prefix = false
+
+            if remaining
+              prefix_index_in_remaining = remaining.index(next_segment.prefix)
+              if prefix_index_in_remaining
+                # Calculate the actual position in the full string
+                actual_prefix_pos = position + prefix_index_in_remaining
+                candidates << actual_prefix_pos
+                found_prefix = true
+              end
+            end
+
+            # For include_prefix_in_value segments, also check for alternative prefixes
+            if next_segment.include_prefix_in_value
+              ["+", "-"].each do |alt_prefix|
+                if alt_prefix != next_segment.prefix
+                  alt_index_in_remaining = remaining&.index(alt_prefix)
+                  if alt_index_in_remaining
+                    candidates << (position + alt_index_in_remaining)
+                    found_prefix = true
+                  end
+                end
+              end
+            end
+
+            # Only stop looking if we found a prefix in the remaining string
+            break if found_prefix
+          end
+        end
+
+        candidates.compact.min
+      end
+
+      def validate_definitions!
+        @segment_definitions.each do |segment|
+          raise Errors::InvalidSchemeError, "segment name required" unless segment.name
+          raise Errors::InvalidSchemeError, "segment type required" unless segment.type
+        end
+
+        # Validate that optional segments (after the first) have a prefix
+        @segment_definitions.each_with_index do |segment, index|
+          next unless segment.optional
+          next if index.zero? # First segment doesn't need separator before it
+
+          # Optional segment must have prefix (to identify its presence)
+          # Separator alone is not enough because optional segments are optional
+          if segment.prefix.nil?
+            raise Errors::InvalidSchemeError,
+                  "Optional segment '#{segment.name}' must have prefix or separator"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/versionian/scheme_loader.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "psych"
+
+module Versionian
+  module Schemes
+    autoload :Pattern, "versionian/schemes/pattern"
+    autoload :CalVer, "versionian/schemes/calver"
+    autoload :Composite, "versionian/schemes/composite"
+  end
+
+  class SchemeLoader
+    ALLOWED_CLASSES = [Symbol, Integer, String, Array, Hash, TrueClass, FalseClass, NilClass].freeze
+
+    class << self
+      def from_yaml_file(path)
+        yaml = File.read(path)
+        from_yaml_string(yaml)
+      end
+
+      def from_yaml_string(yaml_string)
+        data = Psych.safe_load(yaml_string, permitted_classes: ALLOWED_CLASSES, aliases: true)
+        from_hash(data)
+      rescue Psych::SyntaxError => e
+        raise Errors::InvalidSchemeError, "Invalid YAML: #{e.message}"
+      end
+
+      def from_hash(data)
+        case data["type"]&.to_sym
+        when :declarative, "declarative"
+          Schemes::Declarative.new(
+            name: data["name"]&.to_sym,
+            component_definitions: parse_component_definitions(data["components"]),
+            description: data["description"]
+          )
+        when :pattern, "pattern"
+          Schemes::Pattern.new(
+            name: data["name"]&.to_sym,
+            pattern: data["pattern"],
+            component_definitions: parse_component_definitions(data["components"]),
+            format_template: data["format_template"],
+            description: data["description"]
+          )
+        when :calver, "calver"
+          Schemes::CalVer.new(
+            format: data["format"] || "YYYY.MM.DD",
+            name: data["name"]&.to_sym || :calver,
+            description: data["description"]
+          )
+        when :composite, "composite"
+          parse_composite_scheme(data)
+        else
+          raise Errors::InvalidSchemeError, "Unknown scheme type: #{data["type"]}"
+        end
+      end
+
+      private
+
+      def parse_composite_scheme(data)
+        sub_schemes = (data["schemes"] || []).map do |scheme_data|
+          from_hash(scheme_data)
+        end
+
+        fallback = from_hash(data["fallback_scheme"]) if data["fallback_scheme"]
+
+        Schemes::Composite.new(
+          name: data["name"]&.to_sym,
+          schemes: sub_schemes,
+          fallback_scheme: fallback,
+          description: data["description"]
+        )
+      end
+
+      def parse_component_definitions(components_data)
+        return [] unless components_data
+
+        components_data.map do |comp|
+          {
+            name: comp["name"]&.to_sym,
+            type: comp["type"]&.to_sym,
+            subtype: comp["subtype"],
+            values: (comp["values"] || []).map(&:to_sym),
+            order: (comp["order"] || []).map(&:to_sym),
+            weight: comp["weight"],
+            optional: comp["optional"],
+            ignore_in_comparison: comp["ignore_in_comparison"],
+            default: comp["default"],
+            compare_as: comp["compare_as"],
+            separator: comp["separator"],
+            prefix: comp["prefix"],
+            suffix: comp["suffix"],
+            min_count: comp["min_count"] || 1,
+            max_count: comp["max_count"] || 1,
+            validate: comp["validate"] || {},
+            include_prefix_in_value: comp["include_prefix_in_value"]
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/versionian/scheme_registry.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module Versionian
+  class SchemeRegistry
+    include Singleton
+
+    def initialize
+      @schemes = {}
+      @mutex = Mutex.new
+    end
+
+    def register(name, scheme)
+      @mutex.synchronize do
+        @schemes[name] = scheme
+      end
+    end
+
+    def get(name)
+      @schemes[name] || raise(Errors::InvalidSchemeError, "Unknown scheme: #{name}")
+    end
+
+    def registered
+      @schemes.keys
+    end
+
+    def detect_from(version_string)
+      @schemes.values.find do |scheme|
+        scheme.valid?(version_string)
+      end
+    end
+  end
+end

data/lib/versionian/schemes/calver.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Versionian
+  module Schemes
+    class CalVer < VersionScheme
+      # Format patterns with explicit format templates for rendering
+      FORMAT_PATTERNS = {
+        # Date-based formats with standard separators
+        "YYYY.MM.DD" => {
+          pattern: '^(\d{4})\.(\d{2})\.(\d{2})$',
+          format: "{year}.{month}.{day}"
+        },
+        "YYYY.MM" => {
+          pattern: '^(\d{4})\.(\d{2})$',
+          format: "{year}.{month}"
+        },
+        "YYYY.WW" => {
+          pattern: '^(\d{4})\.(\d{2})$',
+          format: "{year}.{week}"
+        },
+        "YY.MM.DD" => {
+          pattern: '^(\d{2})\.(\d{2})\.(\d{2})$',
+          format: "{year}.{month}.{day}"
+        },
+        "YY.MM" => {
+          pattern: '^(\d{2})\.(\d{2})$',
+          format: "{year}.{month}"
+        },
+        "YY.WW" => {
+          pattern: '^(\d{2})\.(\d{2})$',
+          format: "{year}.{week}"
+        }
+      }.freeze
+
+      attr_reader :format, :pattern_scheme
+
+      def initialize(format: "YYYY.MM.DD", name: :calver, description: nil)
+        # Normalize format - 0M and 0W are just formatting, use MM and WW
+        normalized_format = format.gsub("0M", "MM").gsub("0W", "WW")
+
+        config = FORMAT_PATTERNS[normalized_format] || FORMAT_PATTERNS["YYYY.MM.DD"]
+        desc = description || "Calendar versioning (#{normalized_format})"
+
+        component_definitions = build_component_definitions(normalized_format)
+
+        super(name: name, description: desc)
+        @format = normalized_format
+        @pattern_scheme = Pattern.new(
+          name: name,
+          pattern: config[:pattern],
+          component_definitions: component_definitions,
+          format_template: config[:format],
+          description: desc
+        )
+      end
+
+      def parse(version_string)
+        @pattern_scheme.parse(version_string)
+      end
+
+      def compare_arrays(a, b)
+        @pattern_scheme.compare_arrays(a, b)
+      end
+
+      def matches_range?(version_string, range)
+        @pattern_scheme.matches_range?(version_string, range)
+      end
+
+      def render(version)
+        @pattern_scheme.render(version)
+      end
+
+      private
+
+      def build_component_definitions(format)
+        definitions = []
+
+        # Year component (2 or 4 digits)
+        definitions << { name: :year, type: :date_part, subtype: :year }
+
+        # Month component
+        definitions << { name: :month, type: :date_part, subtype: :month } if format.include?("MM")
+
+        # Day component
+        definitions << { name: :day, type: :date_part, subtype: :day } if format.include?("DD")
+
+        # Week component
+        definitions << { name: :week, type: :date_part, subtype: :week } if format.include?("WW")
+
+        definitions
+      end
+    end
+  end
+end

data/lib/versionian/schemes/composite.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Versionian
+  module Schemes
+    class Composite < VersionScheme
+      attr_reader :schemes, :fallback_scheme
+
+      def initialize(schemes:, fallback_scheme:, name:, description: nil)
+        super(name: name, description: description)
+        @schemes = schemes
+        @fallback_scheme = fallback_scheme # Default if no pattern matches
+      end
+
+      def parse(version_string)
+        # Try each scheme in order
+        @schemes.each do |scheme|
+          next unless scheme.valid?(version_string)
+
+          version = scheme.parse(version_string)
+          # Wrap with composite metadata for cross-format comparison
+          return wrap_with_comparable_array(version)
+        end
+
+        # Fallback to default scheme
+        @fallback_scheme.parse(version_string)
+      end
+
+      def compare_arrays(a, b)
+        # Direct array comparison (already normalized by wrap_with_comparable_array)
+        a <=> b
+      end
+
+      def matches_range?(version_string, range)
+        version = parse(version_string)
+        comparable = version.comparable_array
+
+        case range.type
+        when :equals
+          comparable == parse(range.boundary).comparable_array
+        when :before
+          comparable < parse(range.boundary).comparable_array
+        when :after
+          comparable >= parse(range.boundary).comparable_array
+        when :between
+          comparable >= parse(range.from).comparable_array &&
+            comparable <= parse(range.to).comparable_array
+        end
+      end
+
+      def render(version)
+        version.raw_string
+      end
+
+      private
+
+      def wrap_with_comparable_array(version)
+        # Extract comparable array and normalize length
+        base_array = version.comparable_array
+
+        # Check if any component has compare_as directive
+        compare_as_component = version.components.find { |c| c.definition&.compare_as }
+
+        if compare_as_component && compare_as_component.definition.compare_as == "lowest"
+          # Mark as lower priority than base versions
+          # Prefix with a sentinel value that sorts lower than any normal component
+          # For x.y.z-git{hash}: [-1, 1, 2, 3, hash_value]
+          # This sorts lower than [0, 1, 2, 3, 0] (standard x.y.z)
+          [-1] + base_array
+        elsif compare_as_component && compare_as_component.definition.compare_as == "highest"
+          # Mark as higher priority than base versions
+          [1] + base_array
+        else
+          # Standard comparison
+          # Pad with zeros to normalize length
+          max_length = 5
+          padded = [0] + base_array + [0] * (max_length - base_array.length)
+          padded.first(max_length + 1)
+        end
+      end
+    end
+  end
+end

data/lib/versionian/schemes/declarative.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative '../parsers/declarative'
+require_relative '../version_scheme'
+
+module Versionian
+  module Schemes
+    # Declarative version scheme that uses segment definitions instead of regex patterns.
+    # This provides implementation independence and better performance than regex-based schemes.
+    class Declarative < VersionScheme
+      attr_reader :component_definitions, :parser
+
+      # Initialize a new declarative scheme.
+      #
+      # @param name [Symbol] The name of the scheme
+      # @param component_definitions [Array<ComponentDefinition, Hash>] Ordered segment definitions
+      # @param description [String] Optional description of the scheme
+      def initialize(name:, component_definitions:, description: nil)
+        super(name: name, description: description)
+        # Convert hash definitions to ComponentDefinition objects
+        @component_definitions = component_definitions.map do |defn|
+          defn.is_a?(Hash) ? ComponentDefinition.from_hash(defn) : defn
+        end
+        @parser = Parsers::Declarative.new(@component_definitions)
+      end
+
+      # Parse a version string into component values.
+      #
+      # @param version_string [String] The version string to parse
+      # @return [Hash] Component values keyed by component name
+      # @raise [Errors::ParseError] If the version string doesn't match the schema
+      def parse(version_string)
+        component_values = @parser.parse(version_string)
+        build_version_object(version_string, component_values)
+      end
+
+      # Check if a version string matches this scheme.
+      #
+      # @param version_string [String]
+      # @return [Boolean]
+      def valid?(version_string)
+        @parser.match?(version_string)
+      end
+
+      # Check if this scheme supports a given version string.
+      #
+      # @param version_string [String]
+      # @return [Boolean]
+      def supports?(version_string)
+        valid?(version_string)
+      end
+
+      # Compare two version strings.
+      #
+      # @param a [String] First version string
+      # @param b [String] Second version string
+      # @return [Integer] -1, 0, or 1
+      def compare(a, b)
+        version_a = parse(a)
+        version_b = parse(b)
+        version_a <=> version_b
+      end
+
+      # Check if a version string matches a range.
+      #
+      # @param version_string [String] The version string to check
+      # @param range [VersionRange] The range to check against
+      # @return [Boolean]
+      def matches_range?(version_string, range)
+        version = parse(version_string)
+        range.includes?(version)
+      end
+
+      # Render a version object back to a string.
+      #
+      # @param version [Version] The version object to render
+      # @return [String] The rendered version string
+      def render(version)
+        version.raw_string
+      end
+
+      private
+
+      # Build a Version object from component values.
+      #
+      # @param raw_string [String] The original version string
+      # @param component_values [Hash] Parsed component values
+      # @return [VersionIdentifier] The version object
+      def build_version_object(raw_string, component_values)
+        # Build comparable array from component values
+        comparable_array = build_comparable_array(component_values)
+
+        # Build component objects
+        components = component_values.map do |name, value|
+          definition = @component_definitions.find { |d| d.name == name }
+          build_component_object(name, value, definition)
+        end
+
+        VersionIdentifier.new(
+          raw_string: raw_string,
+          scheme: self,
+          components: components,
+          comparable_array: comparable_array
+        )
+      end
+
+      # Build a comparable array from component values.
+      #
+      # @param component_values [Hash] Parsed component values
+      # @return [Array] Comparable array
+      def build_comparable_array(component_values)
+        # Build array based on component definitions order
+        @component_definitions.map do |definition|
+          value = component_values[definition.name]
+          next if value.nil? # Skip optional components that weren't parsed
+
+          component_type = ComponentTypes.resolve(definition.type)
+          component_type.to_comparable(value, definition)
+        end.compact
+      end
+
+      # Build a component object from a parsed value.
+      #
+      # @param name [Symbol] Component name
+      # @param value [Object] Parsed value
+      # @param definition [ComponentDefinition] Component definition
+      # @return [VersionComponent] The component object
+      def build_component_object(name, value, definition)
+        VersionComponent.new(
+          name: name,
+          type: definition.type,
+          value: value,
+          weight: definition.weight || 1
+        )
+      end
+    end
+  end
+end