versionian 0.1.0

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docs/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+gem 'jekyll'
+gem 'just-the-docs'
+gem 'jekyll-asciidoc'
+gem 'jekyll-seo-tag'
+gem 'jekyll-sitemap'
+gem 'rouge'

data/docs/_guides/custom-schemes.adoc

@@ -0,0 +1,110 @@
+---
+layout: default
+title: Custom Schemes
+nav_order: 1
+parent: Guides
+---
+
+= Creating Custom Schemes
+
+== General
+
+You can create custom versioning schemes by subclassing `Versionian::VersionScheme` or using declarative YAML configuration.
+
+== Declarative YAML approach
+
+For most custom schemes, the declarative YAML approach is recommended:
+
+[source,yaml]
+----
+. Example scheme defined at `my_scheme.yaml`
+----
+[source,yaml]
+----
+name: my_yaml_scheme
+type: declarative
+description: My custom version scheme
+components:
+  - name: major
+    type: integer
+    separator: "."
+  - name: minor
+    type: integer
+    separator: "."
+  - name: patch
+    type: integer
+----
+
+[source,ruby]
+----
+scheme = Versionian::SchemeLoader.from_yaml_file('my_scheme.yaml')
+Versionian.register_scheme(:my_scheme, scheme)
+
+version = scheme.parse("1.2.3")
+puts version.major  # => 1
+puts version.minor  # => 2
+----
+
+== Ruby class approach
+
+For complex versioning schemes, you can create custom scheme classes in Ruby.
+
+[source,ruby]
+----
+class FloatVerScheme < Versionian::VersionScheme
+  def initialize(name: :floatver, description: "Float-based versioning")
+    super
+  end
+
+  def parse(version_string)
+    float_value = Float(version_string)
+    Versionian::VersionIdentifier.new(
+      raw_string: version_string,
+      scheme: self,
+      components: [],
+      comparable_array: [float_value]
+    )
+  end
+
+  def compare_arrays(a, b)
+    a.first <=> b.first  # Direct float comparison
+  end
+
+  def render(version)
+    version.raw_string
+  end
+end
+
+# Register and use
+Versionian.register_scheme(:floatver, FloatVerScheme.new)
+----
+
+== Required methods
+
+A custom scheme must implement:
+
+[cols="2,3"]
+|===
+|Method |Description
+
+|#parse(string)
+|Parse version string and return VersionIdentifier
+
+|#compare_arrays(a, b)
+|Compare two comparable arrays
+
+|#valid?(string)
+|Check if string is valid for this scheme
+|===
+
+== Registering custom schemes
+
+[source,ruby]
+----
+# Register with Versionian
+Versionian.register_scheme(:my_scheme, MyScheme.new)
+
+# Use like built-in schemes
+scheme = Versionian.get_scheme(:my_scheme)
+version = scheme.parse("1.2.3")
+----

data/docs/_guides/index.adoc

@@ -0,0 +1,12 @@
+---
+layout: default
+title: Overview
+nav_order: 1
+has_children: true
+---
+
+= Guides
+
+How-to guides and advanced usage documentation.
+
+* link:custom-schemes.html[Custom Schemes] - Creating your own version schemes

data/docs/_pages/component-types.adoc

@@ -0,0 +1,151 @@
+---
+layout: default
+title: Component Types
+nav_order: 3
+parent: Core Topics
+---
+
+= Component Types
+
+== Overview
+
+Versionian provides an extensible component type system that allows different versioning
+schemes to parse and compare version components according to their specific rules.
+
+== Built-in Component Types
+
+=== Integer
+
+Numeric sequence components (major, minor, patch, etc.)
+
+[source,ruby]
+----
+component = Versionian::ComponentTypes::Integer.parse("42", definition)
+component.value  # => 42
+
+# Comparison is numeric
+component.to_comparable(42, definition)  # => 42
+----
+
+=== Float
+
+IEEE754 floating point numbers.
+
+[source,ruby]
+----
+component = Versionian::ComponentTypes::Float.parse("3.14", definition)
+component.value  # => 3.14
+----
+
+=== String
+
+Arbitrary text components.
+
+[source,ruby]
+----
+component = Versionian::ComponentTypes::String.parse("beta", definition)
+component.value  # => "beta"
+----
+
+=== Enum
+
+Ordered stages (alpha, beta, rc, stable, etc.)
+
+[source,ruby]
+----
+definition = Versionian::ComponentDefinition.new(
+  name: :stage,
+  type: :enum,
+  values: [:alpha, :beta, :rc, :stable],
+  order: [:alpha, :beta, :rc, :stable]
+)
+
+component = Versionian::ComponentTypes::Enum.parse("beta", definition)
+component.value  # => :beta
+
+# Comparison uses order array index
+component.to_comparable(:beta, definition)  # => 1
+component.to_comparable(:rc, definition)    # => 2
+----
+
+=== DatePart
+
+Calendar components (year, month, day, week, etc.) with range validation.
+
+[source,ruby]
+----
+definition = Versionian::ComponentDefinition.new(
+  name: :month,
+  type: :date_part,
+  subtype: :month
+)
+
+component = Versionian::ComponentTypes::DatePart.parse("06", definition)
+component.value  # => 6
+
+# Validates ranges (month: 1-12, day: 1-31, etc.)
+----
+
+=== Prerelease
+
+SemVer-style prerelease identifiers (alpha.1, beta.2, etc.)
+
+[source,ruby]
+----
+component = Versionian::ComponentTypes::Prerelease.parse("alpha.1", definition)
+component.value  # => [:alpha, 1]
+
+# Comparison follows SemVer rules
+component.to_comparable(:alpha.1, definition)  # => [:alpha, 1]
+----
+
+=== Postfix
+
+SoloVer-style postfixes (+hotfix, -beta, etc.)
+
+[source,ruby]
+----
+component = Versionian::ComponentTypes::Postfix.parse("+hotfix", definition)
+component.value  # => {prefix: "+", identifier: "hotfix"}
+----
+
+=== Hash
+
+Git commit hashes or similar identifiers.
+
+[source,ruby]
+----
+component = Versionian::ComponentTypes::Hash.parse("abc123def", definition)
+component.value  # => "abc123def"
+
+# Compares by length first, then lexicographically
+component.to_comparable("abc123def", definition)  # => [9, "abc123def"]
+----
+
+== Custom Component Types
+
+You can register your own component types:
+
+[source,ruby]
+----
+module Versionian
+  module ComponentTypes
+    class CustomType < Base
+      def self.parse(value, definition)
+        # Parse logic here
+      end
+
+      def self.to_comparable(value, definition)
+        # Return comparable value
+      end
+
+      def self.format(value)
+        # Format for display
+      end
+    end
+  end
+end
+
+# Register the type
+Versionian::ComponentTypes.register(:custom, Versionian::ComponentTypes::CustomType)
+----

data/docs/_pages/declarative-schemes.adoc

@@ -0,0 +1,260 @@
+---
+layout: default
+title: Declarative Schemes
+nav_order: 2
+parent: Core Topics
+---
+
+= Declarative Schemes
+
+== General
+
+Declarative schemes define version formats using segment definitions instead of regular expressions. Each component specifies its type, separator, prefix, and optional status, allowing the parser to extract components in O(n) time.
+
+Benefits over regex-based patterns:
+
+* **No ReDoS vulnerabilities** - State machine parsing is immune to catastrophic backtracking
+* **O(n) performance** - Single pass through the string
+* **Declarative syntax** - Clear, readable component definitions
+* **Type-aware parsing** - Each component type handles its own validation
+
+== YAML schema
+
+[source,yaml]
+----
+name: my_scheme               <1>
+type: declarative             <2>
+description: Custom scheme    <3>
+components:                  <4>
+  - name: major
+    type: integer
+    separator: "."           <5>
+  - name: minor
+    type: integer
+    separator: "."           <6>
+  - name: patch
+    type: integer            <7>
+----
+<1> Unique scheme identifier (symbol).
+<2> Scheme type: `declarative`.
+<3> Optional description of the scheme.
+<4> Array of component definitions in order.
+<5> Separator that precedes this component.
+<6> Each segment can have its own separator.
+<7> Last segment typically has no separator.
+
+Where,
+
+`name`:: Symbol identifier for the scheme.
+`type`:: Scheme type (`declarative`).
+`description`:: Human-readable description.
+`components`:: Array of component definitions.
+
+.Component attributes
+
+[cols="1,1"]
+|===
+|Attribute |Purpose
+
+|name
+|Component name (symbol)
+
+|type
+|Component type (integer, string, enum, date_part, etc.)
+
+|separator
+|String that precedes this component (e.g., `"."`)
+
+|prefix
+|String that identifies an optional component (e.g., `"-"`, `"+"`)
+
+|optional
+|Boolean: true if component may be absent
+
+|include_prefix_in_value
+|Boolean: include prefix in value for component type parsing
+
+|subtype
+|For date_part: `year`, `month`, `day`, `week`
+
+|values
+|For enum type: allowed values
+
+|order
+|For enum type: comparison order
+
+|validate
+|Hash with `min`/`max` validation rules
+|===
+
+== Loading declarative schemes
+
+[source,ruby]
+----
+# Load from YAML file
+scheme = Versionian::SchemeLoader.from_yaml_file('schemes/custom.yaml')
+
+# Register for use
+Versionian.register_scheme(:custom, scheme)
+
+# Use the scheme
+version = scheme.parse("1.2.3")
+puts version.major  # => 1
+----
+
+== Examples
+
+=== Semantic versioning
+
+[source,yaml]
+----
+name: semantic
+type: declarative
+description: Semantic versioning
+components:
+  - name: major
+    type: integer
+    separator: "."
+  - name: minor
+    type: integer
+    separator: "."
+  - name: patch
+    type: integer
+  - name: prerelease
+    type: string
+    prefix: "-"
+    optional: true
+  - name: build
+    type: string
+    prefix: "+"
+    optional: true
+----
+
+Usage:
+
+[source,ruby]
+----
+scheme = Versionian::SchemeLoader.from_yaml_file('schemes/semantic.yaml')
+
+v = scheme.parse("1.2.3-alpha.1+build.123")
+v.major      # => 1
+v.minor      # => 2
+v.patch      # => 3
+v.prerelease # => "alpha.1"
+v.build      # => "build.123"
+
+# Optional components are nil when absent
+v = scheme.parse("1.2.3")
+v.prerelease # => nil
+v.build      # => nil
+----
+
+=== Calendar versioning
+
+[source,yaml]
+----
+name: calver
+type: declarative
+description: Calendar versioning YYYY.MM.DD
+components:
+  - name: year
+    type: date_part
+    subtype: year
+    separator: "."
+  - name: month
+    type: date_part
+    subtype: month
+    separator: "."
+  - name: day
+    type: date_part
+    subtype: day
+----
+
+Usage:
+
+[source,ruby]
+----
+scheme = Versionian::SchemeLoader.from_yaml_file('schemes/calver.yaml')
+
+v = scheme.parse("2024.01.17")
+v.year   # => 2024
+v.month  # => 1 (not "01")
+v.day    # => 17
+
+# Invalid dates raise ParseError
+scheme.parse("2024.13.17")  # => Invalid month '13'
+scheme.parse("2024.02.30")  # => Invalid day '30'
+----
+
+=== SoloVer with postfix
+
+[source,yaml]
+----
+name: solover
+type: declarative
+description: Single number with optional postfix
+components:
+  - name: number
+    type: integer
+  - name: postfix
+    type: postfix
+    prefix: "+"
+    optional: true
+    include_prefix_in_value: true  <1>
+----
+<1> Postfix type handles prefix internally, so include it in the value.
+
+Usage:
+
+[source,ruby]
+----
+scheme = Versionian::SchemeLoader.from_yaml_file('schemes/solover.yaml')
+
+v = scheme.parse("5")
+v.number   # => 5
+v.postfix  # => nil
+
+v = scheme.parse("5+hotfix")
+v.number    # => 5
+v.postfix   # => {:prefix=>"+", :identifier=>"hotfix"}
+
+v = scheme.parse("5-beta")
+v.number    # => 5
+v.postfix   # => {:prefix=>"-", :identifier=>"beta"}
+----
+
+=== Enum with custom ordering
+
+[source,yaml]
+----
+name: stage
+type: declarative
+description: Release stage with ordering
+components:
+  - name: major
+    type: integer
+    separator: "."
+  - name: minor
+    type: integer
+    separator: "."
+  - name: stage
+    type: enum
+    prefix: "-"
+    optional: true
+    values: [alpha, beta, rc, stable]
+    order: [alpha, beta, rc, stable]
+----
+
+Usage:
+
+[source,ruby]
+----
+scheme = Versionian::SchemeLoader.from_yaml_file('schemes/stage.yaml')
+
+v = scheme.parse("1.2.0-beta")
+v.stage  # => :beta
+
+# Comparison respects order
+scheme.compare("1.2.0-alpha", "1.2.0-beta")  # => -1 (alpha < beta)
+scheme.compare("1.2.0-rc", "1.2.0-stable")    # => -1 (rc < stable)
+----

data/docs/_pages/index.adoc

@@ -0,0 +1,15 @@
+---
+layout: default
+title: Overview
+nav_order: 1
+has_children: true
+---
+
+= Core Topics
+
+Overview of Versionian's core concepts and features.
+
+* link:schemes.html[Version Schemes] - Supported versioning schemes
+* link:declarative-schemes.html[Declarative Schemes] - Custom segment-based schemes
+* link:component-types.html[Component Types] - Type system reference
+* link:range-matching.html[Range Matching] - Version range queries

data/docs/_pages/range-matching.adoc

@@ -0,0 +1,102 @@
+---
+layout: default
+title: Range Matching
+nav_order: 4
+parent: Core Topics
+---
+
+= Range Matching
+
+== Overview
+
+Versionian supports matching versions against range specifications, useful for
+dependency constraints, feature flags, and version compatibility checks.
+
+== Range Types
+
+[cols="2,3"]
+|===
+|Type |Description
+
+|:equals
+|Matches a specific version exactly
+
+|:before
+|Matches versions less than the boundary
+
+|:after
+|Matches versions greater than or equal to the boundary
+
+|:between
+|Matches versions within an inclusive range
+|===
+
+== Creating Ranges
+
+[source,ruby]
+----
+scheme = Versionian.get_scheme(:semantic)
+
+# Exact version
+equals_range = Versionian::VersionRange.new(:equals, scheme, version: "1.12.0")
+
+# Before a version
+before_range = Versionian::VersionRange.new(:before, scheme, version: "2.0.0")
+
+# After a version (inclusive)
+after_range = Versionian::VersionRange.new(:after, scheme, version: "1.12.0")
+
+# Between two versions
+between_range = Versionian::VersionRange.new(:between, scheme, from: "1.12.0", to: "2.0.0")
+----
+
+== Matching Versions
+
+[source,ruby]
+----
+range = Versionian::VersionRange.new(:after, scheme, version: "1.12.0")
+
+range.matches?("1.13.0")  # => true
+range.matches?("1.12.0")  # => true (inclusive)
+range.matches?("1.11.0")  # => false
+----
+
+== Scheme Methods
+
+You can also use the scheme's `matches_range?` method:
+
+[source,ruby]
+----
+scheme.matches_range?("1.12.0", range)  # => true
+----
+
+== Use Cases
+
+=== Dependency Constraints
+
+[source,ruby]
+----
+require 'version'
+
+MIN_VERSION = VersionRange.new(:after, scheme, version: "1.0.0")
+MAX_VERSION = VersionRange.new(:before, scheme, version: "2.0.0")
+
+def compatible?(version_string)
+  scheme.matches_range?(version_string, MIN_VERSION) &&
+    scheme.matches_range?(version_string, MAX_VERSION)
+end
+
+compatible?("1.5.0")  # => true
+compatible?("2.0.0")  # => false
+----
+
+=== Feature Flags
+
+[source,ruby]
+----
+FEATURE_VERSION = VersionRange.new(:after, scheme, version: "2.0.0")
+
+def new_feature_available?(current_version)
+  scheme.matches_range?(current_version, FEATURE_VERSION)
+end
+----