qb 0.3.8 → 0.3.9

data/lib/qb/github/resource.rb

@@ -0,0 +1,59 @@
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+
+# Declarations
+# =======================================================================
+
+
+# Definitions
+# =======================================================================
+
+
+# @todo document QB::GitHub::Resource class.
+class QB::GitHub::Resource < QB::Util::Resource
+  
+  # Constants
+  # ======================================================================
+  
+  
+  # Class Methods
+  # ======================================================================
+  
+  
+  # Attributes
+  # ======================================================================
+  
+  
+  # Constructor
+  # ======================================================================
+  
+  # Instantiate a new `QB::GitHub::Resource`.
+  def initialize octokit_resource
+    @octokit_resource = octokit_resource
+  end # #initialize
+  
+  
+  # Instance Methods
+  # ======================================================================
+  
+  
+end # class QB::GitHub::Resource
+
+
+
+# Post-Processing
+# =======================================================================

data/lib/qb/github/types.rb

@@ -0,0 +1,45 @@
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+require 'nrser/refinements'
+using NRSER
+
+require 'nrser/refinements/types'
+using NRSER::Types
+
+
+# Declarations
+# =======================================================================
+
+module QB; end
+module QB::GitHub; end
+
+
+# Definitions
+# =======================================================================
+
+module QB::GitHub::Types
+  
+  def self.repo_name
+    t.path_seg name: 'GitHubRepoName(String)'
+  end
+  
+  def self.repo_owner
+    t.path_seg name: 'GitHubRepoOwner(String)'
+  end
+  
+end # module QB::GitHub::Types
+

data/lib/qb/package.rb

@@ -92,6 +92,137 @@ class QB::Package < QB::Util::Resource
   prop  :name, type: t.non_empty_str
   
   
+  # @!attribute [r] repo_rel_path
+  #   @todo Doc repo_rel_path property...
+  #   
+  #   @return [PropRubyType]
+  #   
+  prop  :repo_rel_path,
+        type: t.maybe( t.dir_path ),
+        source: :repo_rel_path
+  
+  
+  # Constructor
+  # =====================================================================
+  
+  def initialize repo: NRSER::NO_ARG, **props
+    @repo = repo
+    super **props
+  end # #initialize
+  
+  
+  # Instance Methods
+  # =====================================================================
+  
+  # Repository
+  # ---------------------------------------------------------------------
+  
+  # @todo Document repo method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def repo
+    if @repo == NRSER::NO_ARG
+      @repo = QB::Repo.from_path root_path
+    end
+    
+    @repo
+  end # #repo
+  
+  
+  # @return [Boolean]
+  #   `true` if {#root_path} is in a repo type we recognize.
+  # 
+  def in_repo?
+    !!repo
+  end # #in_repo?
+  
+  
+  # Relative path from the {#repo} root to the {#root_path}.
+  # 
+  # Used as the version tag prefix (unless it's `.` - when the repo root is 
+  # the root path).
+  # 
+  # @return [Pathname]
+  #   
+  def repo_rel_path
+    root_path.relative_path_from( repo.root_path ) if in_repo?
+  end
+  
+  
+  # Get the string prefix for tagging versions of this package.
+  # 
+  # Only makes any sense if the package is in a recognized repo, and will error
+  # out if that's not the case.
+  # 
+  # The most basic prefix is "v" for packages located at the root of the 
+  # repository.
+  # 
+  # @example
+  #   repo_root = '.'
+  #   package_root = repo_root
+  #   QB::Package.from_path( package_root ).version_tag_prefix
+  #   # => 'v'
+  #   # (an actual tag would look like 'v0.1.2')
+  # 
+  # To support "multi-package" repos - which is a way of dealing with apps that
+  # are composed of multiple versioned services without having to create a new
+  # submodule for every micro-service - packages that do not share the same
+  # root of the repo are prefixed by the relative path from the repo root to
+  # the package root.
+  # 
+  # @example
+  #   repo_root = Pathname.new '.'
+  #   package_root = repo_root / 'services' / 'some-service'
+  #   QB::Package.from_path( package_root ).version_tag_prefix
+  #   # => 'services/some-service/v'
+  #   # (an actual tag would look like 'services/some-service/v0.1.2')
+  # 
+  # This creates a unique and intuitive namespace scheme for supporting
+  # multiple independent package versions in a single repo, which has proved
+  # handy for container-ized apps.
+  # 
+  # Unless, of course, you change the package's path. Then it will get wonky.
+  # We'll burn that bridge when we come to it.
+  # 
+  # @return [String]
+  # 
+  def version_tag_prefix
+    if root_path == repo.root_path
+      'v'
+    else
+      (repo_rel_path / 'v').to_s
+    end
+  end # #version_tag_prefix
+  
+  
+  
+  # 
+  # 
+  # @return [String]
+  # 
+  def version_tag
+    version_tag_prefix + version.semver
+  end # #version_tag
+  
+  
+  # @todo Document versions method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def versions
+    # method body...
+  end # #versions
+  
+  
 end # class QB::Package
 
 

data/lib/qb/package/gem.rb

@@ -71,9 +71,9 @@ class QB::Package::Gem < QB::Package
     # @raise [QB::FSStateError]
     #   If `path` is not a directory.
     #     
-    def from_root_path path
+    def from_root_path path, repo: NRSER::NO_ARG
       # Values we will use to construct the resource instance.
-      values = {}
+      values = {repo: repo}
       
       # Whatever we were passes is the reference path
       values[:ref_path] = path
@@ -129,8 +129,6 @@ class QB::Package::Gem < QB::Package
       }
     end # #from_root_path!
     
-    
-    
   end # class << self (Eigenclass)
   
   

data/lib/qb/package/version.rb

@@ -17,6 +17,9 @@ require 'qb/util/resource'
 # Refinements
 # =======================================================================
 
+require 'nrser/refinements'
+using NRSER
+
 require 'nrser/refinements/types'
 using NRSER::Types
 
@@ -41,6 +44,7 @@ class QB::Package::Version < QB::Util::Resource
   # Mixins
   # =====================================================================
   
+  include Comparable
   include QB::Util::DockerMixin
   
   
@@ -52,6 +56,36 @@ class QB::Package::Version < QB::Util::Resource
   MIXED_SEGMENT = t.union NUMBER_SEGMENT, NAME_SEGMENT
   
   
+  # Reasonably simple regular expression to extract things that might be 
+  # versions from strings.
+  # 
+  # Intended for use on reasonably short strings like `git tag` output or
+  # what-not... probably not well suited for sifting through mountains of
+  # text.
+  # 
+  # Structure:
+  # 
+  # 1.  The major version number, matched by a digit `1-9` followed by any
+  #     number of digits.
+  # 2.  A separator to the next segment, which is:
+  #     1.  `.` separating to the minor version number
+  #     2.  `-` separating to the prerelease
+  #     3.  `+` separating to the build
+  # 3.  One or more of `a-z`, `A-Z`, `0-9`, `.`, `-`, `_`, `+`
+  # 4.  Ends with one of those that is *not* `.`, `_` or `+`, so `a-z`, `A-Z`,
+  #     `0-9`.
+  # 
+  # This will match *many* strings that are not versions, but it should not
+  # miss any that are. It cold obviously be refined and improve to reduce 
+  # false positives at the cost of additional complexity, but I wanted to 
+  # start simple and complicate it as needed.
+  # 
+  # @return [Regexp]
+  # 
+  POSSIBLE_VERSION_RE = \
+    /(?:0|[1-9]\d*)[\.\-\+][a-zA-Z0-9\.\-\_\+]*[a-zA-Z0-9\-]+/
+  
+  
   # Props
   # =====================================================================
 
@@ -89,9 +123,13 @@ class QB::Package::Version < QB::Util::Resource
   # Utilities
   # ---------------------------------------------------------------------
   
+  # Time formatted to be stuck in a version segment per [Semver][] spec.
+  # We also strip out '-' to avoid possible parsing weirdness.
+  # 
+  # [Semver]: https://semver.org/
+  # 
   # @return [String]
-  #   Time formatted to be stuck in a version segment per Semver spec.
-  #   We also strip out '-' to avoid possible parsing weirdness.
+  # 
   def self.to_time_segment time
     time.utc.iso8601.gsub /[^0-9A-Za-z]/, ''
   end
@@ -131,6 +169,7 @@ class QB::Package::Version < QB::Util::Resource
         build: []
   end
   
+  
   def self.from_npm_version version
     stmt = NRSER.squish <<-END
       var Semver = require('semver');
@@ -186,6 +225,27 @@ class QB::Package::Version < QB::Util::Resource
     end
   end
   
+  singleton_class.send :alias_method, :from_s, :from_string
+  
+  
+  # Extract version number from a string.
+  # 
+  # @param [String] string
+  #   String containing versions.
+  # 
+  # @return [Array<QB::Package::Version]
+  #   Any versions extracted from the string.
+  # 
+  def self.extract string
+    string.scan( POSSIBLE_VERSION_RE ).map { |possible_version_string|
+      begin
+        from_string possible_version_string
+      rescue
+        nil
+      end
+    }.compact
+  end # .extract
+  
   
   # Constructor
   # =====================================================================
@@ -388,6 +448,114 @@ class QB::Package::Version < QB::Util::Resource
   end # #prerelease_version
   
   
+  # Bumping
+  # ---------------------------------------------------------------------
+  
+  
+  # @todo Document bump_dev method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def bump_to_dev
+    props = { prerelease: ['dev'] }
+    
+    case self.level
+    when 'release'
+      merge patch: patch.succ, **props
+    when 'rc'
+      merge **props
+    when 'dev'
+      self
+    end
+  end # #bump_dev
+  
+  
+  # Bump to next release-candidate version.
+  # 
+  # This is a little tricky because we need to know what the *last* rc
+  # version was, which is not in the version in most cases.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def bump_to_rc existing_versions: nil
+    case self.level
+    when 'release'
+      merge patch: patch.succ, prerelease: ['rc', 0]
+    when 'rc'
+      merge prerelease: ['rc', prerelease[1].succ]
+    when 'dev'
+      if existing_versions.nil?
+        raise ArgumentError.squished <<-END
+          Can't bump to next rc version without knowing what rc versions have
+          already been used.
+        END
+      elsif existing_versions.is_a? String
+        existing_versions = self.class.extract existing_versions
+      end
+      
+      last_existing_rc = existing_versions.
+        select { |version|
+          version.rc? && version.release == release
+        }.
+        sort.
+        last
+      
+      rc_number = if last_existing_rc.nil?
+        0
+      else
+        last_existing_rc.prerelease[1].succ
+      end
+      
+      merge prerelease: ['rc', rc_number]
+    end
+  end # #bump_rc
+  
+  
+  # @todo Document bump_to_release method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def bump_to_release
+    case self.level
+    when 'release'
+      # bump forward to next release, M.m.p -> M.m.(p+1)
+      merge patch: patch.succ
+    when 'rc', 'dev'
+      # bump forward to release version for rc or dev
+      release
+    end
+  end # #bump_to_release
+  
+  
+  # @todo Document bump method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def bump level:, **options
+    method_name = "bump_to_#{ level }"
+    if options.empty?
+      public_send method_name
+    else
+      public_send method_name, **options
+    end
+  end # #bump
+  
   
   # Language Interface
   # =====================================================================
@@ -408,6 +576,11 @@ class QB::Package::Version < QB::Util::Resource
   end # #==
   
   
+  def <=> other
+    to_a <=> other.to_a
+  end
+  
+  
   # Return array of the version elements in order from greatest to least
   # precedence.
   #