qb 0.3.25 → 0.4.0

data/lib/qb/options/types.rb

@@ -0,0 +1,73 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+require 'nrser/refinements/types'
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+using NRSER::Types
+
+
+# Definitions
+# =======================================================================
+
+# Custom types, available by factory name in QB metadata. Neat huh?!
+# 
+module  QB
+class   Options
+module  Types
+  extend t::Factory
+  
+  def_factory :glob do
+    t.array t.path, name: 'FileGlob', from_s: ->( glob ) {
+      if glob.start_with? '//'
+        glob = NRSER.git_root( Dir.getwd ).join( glob[2..-1] ).to_s
+      end
+      
+      Dir[glob]
+    }
+  end
+  
+  
+  def_factory(
+    :qb_default_dir_strategy,
+    aliases: [ :default_dir_strategy ],
+  ) do |name: 'QBDefaultDirStrategy', **options|
+    t.one_of \
+      t.nil,
+      t.false,
+      'cwd',
+      'git_root',
+      t.shape( 'exe'        => t.path ),
+      t.shape( 'find_up'    => t.rel_path ),
+      t.shape( 'from_role'  => t.non_empty_str ),
+      name: name,
+      **options
+  end
+  
+  
+  def_factory(
+    :qb_default_dir,
+    aliases: [ :default_dir ],
+  ) do |name: 'QBDefaultDir', **options|
+    t.one_of \
+      qb_default_dir_strategy,
+      t.array( qb_default_dir_strategy ),
+      **options
+  end
+  
+end; end; end # module QB::Options::Types

data/lib/qb/package.rb

@@ -18,7 +18,6 @@ require_relative './package/version'
 # Refinements
 # =======================================================================
 
-using NRSER
 using NRSER::Types
 
 

data/lib/qb/package/version.rb

@@ -1,3 +1,6 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
 # Requirements
 # =======================================================================
 
@@ -17,20 +20,10 @@ require 'qb/util/resource'
 # Refinements
 # =======================================================================
 
-require 'nrser/refinements'
-using NRSER
-
 require 'nrser/refinements/types'
 using NRSER::Types
 
 
-# Declarations
-# =======================================================================
-
-module QB; end
-class QB::Package < QB::Util::Resource; end
-
-
 # Definitions
 # =======================================================================
 
@@ -39,7 +32,104 @@ class QB::Package < QB::Util::Resource; end
 # 
 # Intended to be immutable for practical purposes.
 # 
-class QB::Package::Version < QB::Util::Resource
+# Based off [SemVer 2][] and - in particular - the [Node semver package][]
+# interpretation / implementation, though we don't use that package at all
+# at this point (sub-shelling out became too expensive, and explorations into
+# Ruby Racer, etc. didn't pan out (don't remember exactly why)).
+# 
+# [SemVer 2]: https://semver.org/spec/v2.0.0.html
+# [Node semver package]: https://www.npmjs.com/package/semver
+# 
+# Let's start the show with some fun...
+# 
+# Terminology
+# ----------------------------------------------------------------------------
+# 
+# Working off what's in the [SemVer 2][] spec as much as possible.
+# 
+# We're going to start from the bottom and build up...
+# 
+# 
+# ### Identifiers
+# 
+# *Identifiers* ([SemVer 2][] spec term) are the atoms of the version:
+# the values that will not be further divided.
+# 
+# They come in two types (my terms):
+# 
+# 1.  *Number Identifiers*
+#     
+#     Non-negative integers. Their string representations may not include
+#     leading zeros.
+# 
+# 2.  *Name Identifiers*
+#     
+#     Non-empty strings that contain only `a-z`, `A-Z` and `-` and are
+#     **not** number identifiers.
+# 
+# All identifiers must be exclusively one type or the other.
+# 
+# Parse and validate identifiers with
+# {QB::Package::Version::From.identifier_for}.
+# 
+# 
+# ### Segments
+# 
+# *Segments* (my term) are sequences of zero or more *identifiers*.
+# 
+# In string representation, the *identifiers* in a *segment* are separated
+# by the dot (`.`) character.
+# 
+# > **NOTE**
+# >
+# > As identifiers can not be empty, a segment's string representation may not
+# > start or end with `.`, and may not contain consecutive `.`.
+# 
+# There are three types of segments:
+# 
+# 1.  *Release Segment*
+#     
+#     Composed of exactly three *number identifiers*:
+#     
+#     1.  *Major*
+#     2.  *Minor*
+#     3.  *Patch*
+#     
+#     > **NOTE**
+#     >
+#     > Ruby's Gem version format doesn't require anything but the *major*
+#     > identifier, in which case we default missing ones to `0`.
+#     
+# 2.  *Prerelease Segment*
+#     
+#     Composed of zero or more *identifiers* - number or name, in any order.
+# 
+# 3.  *Build Segment*
+#     
+#     Composed of zero or more *identifiers* - number or name, in any order.
+# 
+# 
+# ### Versions
+# 
+# A *version* is exactly one release segment, prerelease segment and build
+# segment, in which the prerelease and build segments may be empty as noted
+# above.
+# 
+# In SemVer string representation, the release segment is always present, and
+# a non-empty prerelease segment may follow it, separated by a `-` character.
+# 
+# A non-empty build segment may follow those, separated by a `+` character.
+# 
+module  QB
+class   Package < QB::Util::Resource
+class   Version < QB::Util::Resource
+  
+  # Sub-Tree Requirements
+  # ========================================================================
+  
+  require_relative './version/leveled'
+  require_relative './version/from'
+  
   
   # Mixins
   # =====================================================================
@@ -51,9 +141,23 @@ class QB::Package::Version < QB::Util::Resource
   # Constants
   # =====================================================================
   
+  # Pattern to match string *identifiers* that are version "numlets" (the
+  # non-negative integer number part of version "numbers").
+  # 
+  # @return [Regexp]
+  # 
+  NUMBER_IDENTIFIER_RE = /\A(?:0|(?:[1-9]\d*))\z/
+  
+  
+  # What separates *identifiers* (the base undivided values).
+  # 
+  # @return [String]
+  # 
+  IDENTIFIER_SEPARATOR = '.'
+  
   NUMBER_SEGMENT = t.non_neg_int
-  NAME_SEGMENT = t.str
-  MIXED_SEGMENT = t.union NUMBER_SEGMENT, NAME_SEGMENT
+  NAME_SEGMENT = t.str & /\A[0-9A-Za-z\-]+\z/
+  MIXED_SEGMENT = t.xor NUMBER_SEGMENT, NAME_SEGMENT
   
   
   # Reasonably simple regular expression to extract things that might be
@@ -89,27 +193,53 @@ class QB::Package::Version < QB::Util::Resource
   # Props
   # =====================================================================
 
-  prop :raw,            type: t.maybe(t.str),         default: nil
-  prop :major,          type: NUMBER_SEGMENT
-  prop :minor,          type: NUMBER_SEGMENT,         default: 0
-  prop :patch,          type: NUMBER_SEGMENT,         default: 0
-  prop :prerelease,     type: t.array(MIXED_SEGMENT), default: ->{ [] }
-  prop :build,          type: t.array(MIXED_SEGMENT), default: ->{ [] }
-
-  prop :release,        type: t.str,            source: :@release
-  prop :is_release,     type: t.bool,           source: :release?
-  prop :is_prerelease,  type: t.bool,           source: :prerelease?
-  prop :is_build,       type: t.bool,           source: :build?
-  prop :semver,         type: t.str,            source: :semver
-  prop :docker_tag,     type: t.str,            source: :docker_tag
-  prop :build_commit,   type: t.maybe(t.str),   source: :build_commit
-  prop :is_build_dirty, type: t.maybe(t.bool),  source: :build_dirty?
-
-
-  # Attributes
-  # =====================================================================
-
-  attr_reader :release
+  prop :raw,            type:     t.maybe(t.str),
+                        default:  nil
+  
+  prop :major,          type:     NUMBER_SEGMENT
+  
+  prop :minor,          type:     NUMBER_SEGMENT,
+                        default:  0
+  
+  prop :patch,          type:     NUMBER_SEGMENT,
+                        default:  0
+  
+  prop :revision,       type:     t.array( NUMBER_SEGMENT ),
+                        default:  ->{ [] }
+  
+  prop :prerelease,     type:     t.array( MIXED_SEGMENT ),
+                        default:  ->{ [] }
+  
+  prop :build,          type:     t.array( MIXED_SEGMENT ),
+                        default:  ->{ [] }
+  
+  
+  # Derived Props
+  # --------------------------------------------------------------------------
+  
+  prop :release,        type:     t.str,
+                        source:   :@release
+  
+  prop :is_release,     type:     t.bool,
+                        source:   :release?
+  
+  prop :is_prerelease,  type:     t.bool,
+                        source:   :prerelease?
+  
+  prop :is_build,       type:     t.bool,
+                        source:   :build?
+  
+  prop :semver,         type:     t.str,
+                        source:   :semver
+  
+  prop :docker_tag,     type:     t.str,
+                        source:   :docker_tag
+  
+  prop :build_commit,   type:     t.maybe(t.str),
+                        source:   :build_commit
+  
+  prop :is_build_dirty, type:     t.maybe(t.bool),
+                        source:   :build_dirty?
   
   
   # Class Methods
@@ -201,26 +331,24 @@ class QB::Package::Version < QB::Util::Resource
   end
   
   
-  # @todo Document build_dirty? method.
+  # Is the build "dirty"?
   # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
-  # @return [return_type]
-  #   @todo Document return value.
+  # @return [Boolean]
   # 
   def build_dirty?
     if build?
-      build.include? 'dirty'
+      build.any? { |seg| seg.is_a?( String ) && seg.include?( 'dirty' ) }
     end
   end # #build_dirty?
   
+  alias_method :dirty?, :build_dirty?
+  
   
   # Derived Properties
   # ---------------------------------------------------------------------
   
   def release
-    [major, minor, patch].join '.'
+    [major, minor, patch, *revision].join '.'
   end
   
   
@@ -291,22 +419,21 @@ class QB::Package::Version < QB::Util::Resource
   # 
   # @return [QB::Package::Version]
   # 
-  def build_version branch: nil, ref: nil, time: nil, dirty: nil
-    time = self.class.to_time_segment(time) unless time.nil?
+  def build_version *build, branch: nil, ref: nil, time: nil, dirty: nil
     
-    segments = [
+    repo_segments = [
       branch,
       ref,
       ('dirty' if dirty),
-      time,
-    ].reject &:nil?
+      (self.class.to_time_segment(time) if dirty && time),
+    ].compact
     
-    if segments.empty?
+    if repo_segments.empty?
       raise ArgumentError,
-            "Need to provide at least one of branch, ref, time."
+            "Need to provide at least one of branch, ref, dirty."
     end
     
-    merge raw: nil, build: segments
+    merge raw: nil, build: [*build, repo_segments.join( '-' )]
   end
   
   
@@ -367,6 +494,7 @@ class QB::Package::Version < QB::Util::Resource
       major,
       minor,
       patch,
+      revision,
       prerelease,
       build,
     ]
@@ -387,11 +515,4 @@ class QB::Package::Version < QB::Util::Resource
     "#<QB::Package::Version #{ @raw }>"
   end
   
-end # class QB::Package::Version
-
-
-# Post-Processing
-# =======================================================================
-
-require 'qb/package/version/leveled'
-require 'qb/package/version/from'
+end; end; end # class QB::Package::Version

data/lib/qb/package/version/from.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
+
 # Refinements
 # =======================================================================
 
-using NRSER
 using NRSER::Types
 
 
@@ -51,91 +51,232 @@ module QB::Package::Version::From
   # 
   # @return [QB::Package::Version]
   # 
-  def self.gemver version
-    version = Gem::Version.new( version ) if version.is_a?( String )
+  def self.gemver source
+    gem_version = case source
+    when ::Gem::Version
+      source
+    else
+      ::Gem::Version.new source.to_s
+    end
     
     # release segments are everything before a string
-    release_segments = version.segments.take_while { |seg|
+    release_segments = gem_version.segments.take_while { |seg|
       !seg.is_a?(String)
     }
     
-    # We don't support > 3 release segments to make life somewhat
-    # reasonable. Yeah, I think I've seen projects do it. We'll cross that
-    # bridge if and when we get to it.
-    if release_segments.length > 3
-      raise ArgumentError,
-            "We don't handle releases with more than 3 segments " +
-            "(found #{ release_segments.inspect } in #{ version })"
-    end
-    
-    prerelease_segments = version.segments[release_segments.length..-1]
+    prerelease_segments = gem_version.segments[release_segments.length..-1]
     
     prop_values \
-      raw: version.to_s,
-      major: release_segments[0] || 0,
+      raw: source.to_s,
+      major: release_segments[0],
       minor: release_segments[1] || 0,
       patch: release_segments[2] || 0,
+      revision: release_segments[3..-1] || [],
       prerelease: prerelease_segments,
       build: []
   end
   
   singleton_class.send :alias_method, :gem_version, :gemver
-
-
-  def self.semver version
-    stmt = NRSER.squish <<-END
-      var Semver = require('semver');
-      
-      console.log(
-        JSON.stringify(
-          Semver(#{ JSON.dump version })
-        )
-      );
-    END
+  
+  
+  def self.split_identifiers string
+    string.split QB::Package::Version::IDENTIFIER_SEPARATOR
+  end
+  
+  
+  # Parse and/or validate version *identifiers*.
+  # 
+  # See {QB::Package::Version} for details on *identifiers*.
+  # 
+  # @param [String | Integer] value
+  #   A value that is either already an *identifier* or a string that can
+  #   be parsed into one.
+  # 
+  # @return [String | Integer]
+  #   A valid *identifier*.
+  # 
+  def self.identifier_for value
+    case value
+    when QB::Package::Version::NUMBER_IDENTIFIER_RE
+      value.to_i
+    when QB::Package::Version::MIXED_SEGMENT
+      value
+    else
+      raise ArgumentError.new binding.erb <<~END
+        Can't parse identifier <%= value.inspect %>
+        
+        Expected one of:
+        
+        1.  <%= QB::Package::Version::NUMBER_IDENTIFIER_RE %>
+        2.  <%= QB::Package::Version::MIXED_SEGMENT %>
+        
+      END
+    end
+  end # .identifier_for
+  
+  
+  def self.segment_for string
+    split_identifiers( string ).map { |s| identifier_for s }
+  end
+  
+  
+  # Load a SemVer¹ string into a {QB::Package::Version}.
+  # 
+  # @see https://semver.org
+  # 
+  # > **¹**
+  # >   Through a combination of need, failure and frustration we are a
+  # >   *wee bit* looser than the SemVer spec. This really comes from needing
+  # >   to be able to handle more than three *release segments* because:
+  # >
+  # >   1.  Well, some projects use more than three and we can't change that.
+  # >   2.  It seemed over-complicated to add another "almost-semver" parsing
+  # >       option.
+  # >
+  # >   Details below. You can enforce our best attempt at pure SemVer with
+  # >   the `strict:` keyword option.
+  # 
+  # ##### Gory Details #####
+  # 
+  # Oh, semver... what a pain you're been.
+  # 
+  # Right now, I just finished writing our own parser. It probably has a lot
+  # of problems and I can't imagine it conforms to the spec even where it's
+  # meant to. I didn't want to go this road, it was out of desperation.
+  # 
+  # First, QB was shelling-out to Node and using it's [semver][Node semver]
+  # package, since that seems to kind of be the de-facto reference
+  # implementation of the spec.
+  # 
+  # That was far too slow to process large lists of version like you might
+  # get from `git tag`, and it means we depended on Node and had to bundle
+  # the `semver` package in or install it otherwise, which was a pain for
+  # a single function call.
+  # 
+  # Yeah, there are other ways to go about it, but they all suck too.
+  # 
+  # Next I tried the [semver2][Ruby semver2] Ruby gem. It never struck me as
+  # super solid, and when faced with `1.2.3.4-pre`-style versions it just
+  # tossed everything after the `3` and didn't mention it, which led me to
+  # toss it too.
+  # 
+  # This happen when I realized we couldn't side-step "fourth release segment"
+  # because I needed the system to handle OpenResty's Docker image versions,
+  # which are `M.m.p.r` format, leading to add the
+  # {QB::Package::Version#revision} property and write my own parsing logic
+  # here.
+  # 
+  # [Node semver]: https://www.npmjs.com/package/semver
+  # 
+  # @param [#to_s] source
+  #   Where to get the source string.
+  # 
+  # @param [Boolean] strict:
+  #   When `true`, we attempt to adhere strictly to the SemVer spec, raising
+  #   if we find any departures.
+  # 
+  # @raise [ArgumentError]
+  #   1.  If there are **less than** `3` *release segments*.
+  #       
+  #       This helps us not loading things like `2018-new-stuff` into a
+  #       version, as might be found in a Git tag.
+  #       
+  #       It does not let us avoid loading `2018.10.11-new-stuff` info a
+  #       version, so fair warning.
+  #       
+  #   2.  If `strict: true` and there are not **exactly** `3`
+  #       *release segments*.
+  # 
+  def self.semver source, strict: false
+    source = source.to_s unless source.is_a?( String )
     
-    parse = JSON.load Cmds.new(
-      "node --eval %s", args: [stmt], chdir: QB::ROOT
-    ).out!
+    identifier_for_ref = method :identifier_for
     
-    prop_values \
-      raw: version,
-      major: parse['major'],
-      minor: parse['minor'],
-      patch: parse['patch'],
-      prerelease: parse['prerelease'],
-      build: parse['build']
+    if source.include?( '-' ) && source.include?( '+' )
+      release_str, _, rest = source.partition '-'
+      pre_str, _, build_str = rest.partition '+'
+    elsif source.include?( '-' )
+      release_str, _, pre_str = source.partition '-'
+      build_str = ''
+    elsif source.include?( '+' )
+      release_str, _, build_str = source.partition '+'
+      pre_str = ''
+    else
+      release_str = source
+      pre_str = build_str = ''
+    end
+    
+    release_segs, pre_segs, build_segs = \
+      [release_str, pre_str, build_str].map { |str|
+        split_identifiers( str ).map &identifier_for_ref
+      }
+    
+    # Check release segments length
+    if strict && release_segs.length != 3
+      raise NRSER::ArgumentError.new \
+        "Strict SemVer versions *MUST* have at exactly 3 release segments",
+        source: source,
+        release_segments: release_segs
+        
+    elsif release_segs.length < 3
+      raise NRSER::ArgumentError.new \
+        "SemVer versions *MUST* have at lease 3 release segments",
+        source: source,
+        release_segments: release_segs
+      
+    end
+    
+    prop_values **{
+      raw: source,
+      major: release_segs[0],
+      minor: release_segs[1],
+      patch: release_segs[2],
+      revision: release_segs[3..-1] || [],
+      prerelease: pre_segs,
+      build: build_segs,
+    }.compact
   end
   
-  singleton_class.send :alias_method, :npm_version, :semver
+  
+  def npm_version source
+    semver source, strict: true
+  end
 
 
   # Parse Docker image tag version and create an instance.
   # 
-  # @param [String] version
+  # @param [#to_s] source
   #   String version to parse.
   # 
   # @return [QB::Package::Version]
   # 
-  def self.docker_tag version
-    string( version.gsub( '_', '+' ) ).merge raw: version
+  def self.docker_tag source
+    source = source.to_s unless source.is_a?( String )
+    self.string( source.gsub( '_', '+' ) ).merge raw: source
   end # .docker_tag
 
 
   # Parse string version into an instance. Accept Semver, Ruby Gem and
   # Docker image tag formats.
   # 
-  # @param [String]
+  # @param [#to_s] source
   #   String version to parse.
   # 
   # @return [QB::Package::Version]
   # 
-  def self.string string
-    if string.include? '_'
-      docker_tag string
-    elsif string.include?( '-' ) || string.include?( '+' )
-      semver string
+  def self.string source
+    source = source.to_s unless source.is_a?( String )
+    
+    t.non_empty_str.check source
+    
+    if source.include? '_'
+      docker_tag source
+    elsif ( source.include?( '-' ) ||
+            source.include?( '+' ) ) &&
+          source =~ /\A\d+\.\d+\.\d+/
+      semver source
     else
-      gem_version string
+      gemver source
     end
   end
 
@@ -148,8 +289,8 @@ module QB::Package::Version::From
       string object
     when Hash
       prop_values **object
-    when Gem::Version
-      gem_version object
+    when ::Gem::Version
+      gemver object
     else
       raise TypeError.new binding.erb <<-END
         `object` must be String, Hash or Gem::Version