cartage 1.2 → 2.0.rc1

data/lib/cartage/minitest.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'cartage'
+
+##
+# Provide helper methods for testing Cartage and plug-ins using Minitest.
+module Cartage::Minitest
+  #:nocov:
+
+  ##
+  # A helper to stub ENV lookups against an +env+ hash. If +options+ has a key
+  # <tt>:passthrough</tt>, will reach for the original ENV value.
+  #
+  # Tested thoroughly only with Minitest::Moar::Stubbing. This helper will
+  # probably be moved to a different gem in the future.
+  def stub_env(env, options = {}, *block_args, &block)
+    mock = lambda { |key|
+      env.fetch(key) { |k|
+        ENV.send(:'__minitest_stub__[]', k) if options[:passthrough]
+      }
+    }
+
+    if defined?(Minitest::Moar::Stubbing)
+      stub ENV, :[], mock, *block_args, &block
+    else
+      ENV.stub :[], mock, *block_args, &block
+    end
+  end
+
+  # A helper to stub capturing shell calls (<tt>`echo true`</tt> or <tt>%x(echo
+  # true)</tt>) to return +value+.
+  #
+  # This helper will probably be moved to a different gem in the future.
+  def stub_backticks(value)
+    Kernel.send(:alias_method, :__minitest_stub_backticks__, :`)
+    Kernel.send(:define_method, :`) { |*| value }
+    yield
+  ensure
+    Kernel.send(:remove_method, :`)
+    Kernel.send(:alias_method, :`, :__minitest_stub_backticks__)
+    Kernel.send(:remove_method, :__minitest_stub_backticks__)
+  end
+
+  # A helper to stub Cartage#repo_url to return +value+.
+  def stub_cartage_repo_url(value = nil, &block)
+    stub_instance_method Cartage, :repo_url, -> { value || 'git://host/repo-url.git' },
+      &block
+  end
+
+  ##
+  # An assertion that Pathname#write receives the +expected+ value.
+  def assert_pathname_write(expected)
+    string_io = StringIO.new
+    stub_instance_method Pathname, :write, ->(v) { string_io.write(v) } do
+      yield
+      assert_equal expected, String.new(string_io.string)
+    end
+  end
+
+  # A helper to stub Pathname#expand_path to return <tt>Pathname(value)</tt>.
+  def stub_pathname_expand_path(value, &block)
+    stub_instance_method Pathname, :expand_path, Pathname(value), &block
+  end
+
+  # A helper to define one or more methods (identified in +names+) on +target+
+  # with the same +block+, which defaults to an empty callable.
+  def disable_unsafe_method(target, *names, &block)
+    block ||= ->(*) {}
+    names.each { |name| target.define_singleton_method name, &block }
+  end
+
+  # A helper to stub Dir.chdir, which was not stubbing cleanly. This also
+  # asserts that the path provided to Dir.chdir will be the +expected+ value.
+  def stub_dir_chdir(expected)
+    assert_equal = method(:assert_equal)
+
+    Dir.singleton_class.send(:alias_method, :__minitest_stub_chdir__, :chdir)
+    Dir.singleton_class.send(:define_method, :chdir) do |path, &block|
+      assert_equal.(expected, path)
+      block.call(path) if block
+    end
+
+    yield
+  ensure
+    Dir.singleton_class.send(:remove_method, :chdir)
+    Dir.singleton_class.send(:alias_method, :chdir, :__minitest_stub_chdir__)
+    Dir.singleton_class.send(:remove_method, :__minitest_stub_chdir__)
+  end
+
+  # Stubs Cartage#run and asserts that the array of commands provided are
+  # matched for each call and that they are all consumed.
+  def stub_cartage_run(*expected)
+    expected = [ expected ].flatten(1)
+    stub_instance_method Cartage, :run, ->(v) { assert_equal expected.shift, v } do
+      yield
+    end
+    assert_empty expected
+  end
+
+  #:nocov:
+
+  private
+
+  # Ripped and slightly modified from minitest-stub-any-instance.
+  def stub_instance_method(klass, name, val_or_callable, &block)
+    if defined?(::Minitest::Moar::Stubbing)
+      instance_stub klass, name, val_or_callable, &block
+    elsif defined?(::Minitest::StubAnyInstance)
+      klass.stub_any_instance(name, val_or_callable, &block)
+    else
+      begin
+        new_name = "__minitest_stub_instance_method__#{name}"
+        owns_method = instance_method(name).owner == klass
+        klass.class_eval do
+          alias_method new_name, name if owns_method
+
+          define_method(name) do |*args|
+            if val_or_callable.respond_to?(:call)
+              instance_exec(*args, &val_or_callable)
+            else
+              val_or_callable
+            end
+          end
+        end
+
+        yield
+      ensure
+        klass.class_eval do
+          remove_method name
+          if owns_method
+            alias_method name, new_name
+            remove_method new_name
+          end
+        end
+      end
+    end
+  end
+
+  Minitest::Test.send(:include, self)
+end

data/lib/cartage/plugin.rb

@@ -1,27 +1,57 @@
+# frozen_string_literal: true
+
 class Cartage
-  # Cartage::Plugin is the basis of the Cartage plugin system. All plug-ins
-  # must inherit from this class.
+  # Cartage::Plugin is the basis of the Cartage plug-in system that extends
+  # core functionality. All plug-ins of this sort must inherit from this class.
+  # (Command extensions are handled by extending Cartage::CLI.)
   class Plugin
     class << self
-      # Register a subclass.
-      def inherited(klass) #:nodoc:
-        registered << klass
+      # Register a plugin.
+      def inherited(plugin) #:nodoc:
+        registered[plugin.plugin_name] = plugin
       end
 
-      # The plugins registered with Cartage.
+      # The plugins registered with Cartage as a dictionary of plug-in name
+      # (the key used for plug-in configuration) and plug-in class.
       def registered
-        @registered ||= []
+        @registered ||= {}
+      end
+
+      # The name of the plugin.
+      def plugin_name
+        @name ||= name.split(/::/).last.gsub(/([A-Z])/, '_\1').downcase.
+          sub(/^_/, '')
+      end
+
+      # Iterate the plugins by +name+.
+      def each # :yields: name
+        registered.each_key { |k| yield k }
+      end
+
+      # The version of the plug-in.
+      def version
+        if const_defined?(:VERSION, false)
+          VERSION
+        else
+          Cartage::VERSION
+        end
+      end
+
+      # A utility method to load and decorate an object with Cartage plug-ins.
+      def load_for(klass) #:nodoc:
+        load
+        decorate(klass)
       end
 
-      # A utility method that will find all Cartage plugins and load them. A
-      # Cartage plugin is found with 'cartage/*.rb' and descends from
-      # Cartage::Plugin.
+      # A utility method that will find all Cartage plug-ins and load them. A
+      # Cartage plug-in is found in the Gems as <tt>cartage/plugins/*.rb</tt>
+      # and descends from Cartage::Plugin.
       def load #:nodoc:
         @found ||= {}
         @loaded ||= {}
-        @files ||= Gem.find_files('cartage/*.rb')
+        @files ||= Gem.find_files('cartage/plugins/*.rb')
 
-        @files.reverse.each do |path|
+        @files.reverse_each do |path|
           name = File.basename(path, '.rb').to_sym
           @found[name] = path
         end
@@ -33,16 +63,15 @@ class Cartage
 
       # Decorate the provided class with lazy initialization methods.
       def decorate(klass) #:nodoc:
-        registered.each do |plugin|
-          name = plugin.name.split(/::/).last.gsub(/([A-Z])/, '_\1').downcase.
-            sub(/^_/, '')
+        registered.each do |name, plugin|
           ivar = "@#{name}"
 
+          klass.send(:undef_method, name) if klass.method_defined?(name)
           klass.send(:define_method, name) do
             instance = instance_variable_defined?(ivar) &&
               instance_variable_get(ivar)
 
-            instance ||= instance_variable_set(ivar, plugin.new(self))
+            instance || instance_variable_set(ivar, plugin.new(self))
           end
         end
       end
@@ -59,22 +88,105 @@ class Cartage
       end
     end
 
-    # These are the command classes provided to the cartage binary. Despite the
-    # name being plural, the return can either be a single CmdParse::Command
-    # class, or an array of CmdParse::Command class. These command classes
-    # should inherit from Cartage::Command, since they will be initialized with
-    # a cartage parameter.
-    def self.commands
-      []
+    # Returns +true+ if the feature identified by +name+ is offered by this
+    # plug-in. Requires that subclasses implement the #offer_feature? private
+    # method.
+    def offer?(name)
+      enabled? && offer_feature?(name.to_sym)
     end
 
-    # A plug-in is initialized with the Cartage instance that owns it.
+    # Returns +true+ if the plug-in has been explicitly disabled in
+    # configuration.
+    def disabled?
+      !!@disabled
+    end
+
+    # Returns +true+ if the plug-in is enabled (it has not been explicitly
+    # disabled).
+    def enabled?
+      !disabled?
+    end
+
+    # The name of this plug-in.
+    def plugin_name
+      self.class.plugin_name
+    end
+
+    # The version of this plug-in
+    def version
+      self.class.version
+    end
+
+    # A plug-in is given, as +cartage+, the instance of Cartage that owns it.
     def initialize(cartage)
+      fail NotImplementedError, 'not a subclass' if instance_of?(Cartage::Plugin)
       @cartage = cartage
+      @disabled = false
     end
 
     private
-    def resolve_config!(*)
+
+    # The instance of Cartage that owns this plug-in instance.
+    attr_reader :cartage # :doc:
+
+    # This method should not be overridden by implementors.
+    def resolve_config!(config)
+      @disabled = config.disabled
+      resolve_plugin_config!(config)
+    end
+
+    # Plug-ins that have configuration that needs resolution before use should
+    # implement this method. It is provided +config+, which is just the subset
+    # of the overall Cartage::Config object that applies to this plug-in.
+    def resolve_plugin_config!(config) # :doc:
+    end
+
+    # This is an extension point for plug-ins to indicate that they offer the
+    # feature with the given +name+. The default implementation should be
+    # sufficient for most plug-ins, because it matches the way that plug-in
+    # methods are called.
+    def offer_feature?(name) # :doc:
+      respond_to?(name)
+    end
+  end
+
+  # A collection of Cartage::Plugin held by a Cartage instance.
+  class Plugins
+    def initialize # :nodoc:
+      @plugins = []
+    end
+
+    # Adds one or more +plugins+ to the collection.
+    def add(*plugins)
+      @plugins.push(*plugins)
+    end
+
+    # Return enabled plug-ins.
+    def enabled
+      @plugins.select(&:enabled?)
+    end
+
+    # Map +method+ over all plug-ins offering +feature+. Used to collect data
+    # from plug-ins that offer this +feature+.
+    def request_map(feature, method = feature)
+      feature = feature.to_sym
+      method = method.to_sym
+      offering(feature).map(&method)
+    end
+
+    # Run +method+ on plug-ins offering +feature+. Used to run code in plug-ins
+    # that offer this +feature+.
+    def request(feature, method = feature)
+      feature = feature.to_sym
+      method = method.to_sym
+      offering(feature).each(&method)
+    end
+
+    private
+
+    def offering(name)
+      name = name.to_sym
+      @plugins.select { |plugin| plugin.offer?(name) }
     end
   end
 end

data/lib/cartage/plugins/build_tarball.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+##
+# Create the release package as a tarball.
+#
+# Offers:
+# *  +:build_package+
+class Cartage::BuildTarball < Cartage::Plugin
+  # Create the package.
+  #
+  # Requests:
+  # *  +:pre_build_tarball+
+  # *  +:post_build_tarball+
+  def build_package
+    cartage.plugins.request(:pre_build_tarball)
+    run_command
+    cartage.plugins.request(:post_build_tarball)
+  end
+
+  # The final tarball name.
+  def package_name
+    @package_name ||=
+      Pathname("#{cartage.final_name}.tar#{cartage.tar_compression_extension}")
+  end
+
+  private
+
+  def run_command
+    command = [
+      'tar',
+      "cf#{cartage.tar_compression_flag}",
+      package_name.to_s,
+      '-C',
+      cartage.tmp_path.to_s,
+      cartage.name
+    ]
+
+    cartage.run command
+  end
+end

data/lib/cartage/{manifest.rb → plugins/manifest.rb}

@@ -1,27 +1,28 @@
+# frozen_string_literal: true
+
 require 'tempfile'
+
 # Manage and use the package manifest ('Manifest.txt') and the ignore file
 # ('.cartignore').
 class Cartage::Manifest < Cartage::Plugin
   # This exception is raised if the package manifest is missing.
-  MissingError = Class.new(StandardError) do
-    def message
+  class MissingError < StandardError
+    def message # :nodoc:
       <<-exception
 Cartage cannot create a package without a Manifest.txt file. You may generate
 or update the Manifest.txt file with the following command:
 
+    cartage manifest generate
+
       exception
     end
   end
 
-  DIFF     = if system('gdiff', __FILE__, __FILE__) #:nodoc:
-               'gdiff'
-             else
-               'diff'
-             end
-
-  def initialize(cartage) #:nodoc:
-    @cartage = cartage
-  end
+  DIFF = if system('gdiff', __FILE__, __FILE__) #:nodoc:
+           'gdiff'
+         else
+           'diff'
+         end
 
   # Resolve the Manifest to something that can be used by <tt>tar -T</tt>. The
   # manifest should be relative to the files in the repository, as reported
@@ -35,14 +36,17 @@ or update the Manifest.txt file with the following command:
   # front of every line in the Manifest.
   #
   # If +path+ is not provided, Dir.pwd is used.
-  def resolve(path = nil, command: nil) # :yields: resolved manifest filename
-    raise MissingError unless manifest_file.exist?
+  #
+  # A block is required and is provided the +resolved_path+.
+  def resolve(path = nil) # :yields: resolved_path
+    fail MissingError unless manifest_file.exist?
+    fail ArgumentError, 'A block is required.' unless block_given?
 
     data = strip_comments_and_empty_lines(manifest_file.readlines)
-    raise "Manifest.txt is empty." if data.empty?
+    fail 'Manifest.txt is empty.' if data.empty?
 
     path = Pathname(path || Dir.pwd).expand_path.basename
-    tmpfile = Tempfile.new('Manifest')
+    tmpfile = Tempfile.new('Manifest.')
 
     tmpfile.puts prune(data, with_slugignore: true).map { |line|
       path.join(line).to_s
@@ -65,20 +69,29 @@ or update the Manifest.txt file with the following command:
 
   # Checks Manifest.txt
   def check
-    raise MissingError unless manifest_file.exist?
+    fail MissingError unless manifest_file.exist?
     tmp = create_file_list('Manifest.tmp')
-    system(DIFF, '-du', manifest_file.basename.to_s, tmp.to_s)
+
+    args = [ DIFF, '-du', manifest_file.basename.to_s, tmp.to_s ]
+
+    if cartage.quiet
+      %x(#{(args << '-q').join(' ')})
+    else
+      system(*args)
+    end
+
     $?.success?
   ensure
     tmp.unlink if tmp
   end
 
-  # Installs the default .cartignore file.
+  # Installs the default .cartignore file. Will either +overwrite+ or +merge+
+  # based on the provided +mode+.
   def install_default_ignore(mode: nil)
-    mode = mode.to_s.downcase.strip
     save = mode || !ignore_file.exist?
 
-    if mode == :merge
+    if mode == 'merge'
+      cartage.display('Merging .cartignore...')
       data = strip_comments_and_empty_lines(ignore_file.readlines)
 
       if data.empty?
@@ -87,11 +100,14 @@ or update the Manifest.txt file with the following command:
         data += strip_comments_and_empty_lines(DEFAULT_IGNORE.split($/))
         data = data.uniq.join("\n")
       end
-    else
+    elsif save
+      cartage.display('Creating .cartignore...')
       data = DEFAULT_IGNORE
+    else
+      cartage.display('.cartignore already exists, skipping...')
     end
 
-    ignore_file.open('w') { |f| f.puts data } if save
+    ignore_file.write(data) if save
   end
 
   private
@@ -109,11 +125,8 @@ or update the Manifest.txt file with the following command:
   end
 
   def create_file_list(filename)
-    Pathname(filename).tap { |file|
-      file.open('w') { |f|
-        f.puts prune(%x(git ls-files).split.map(&:chomp)).sort.uniq.join("\n")
-      }
-    }
+    files = prune(%x(git ls-files).split.map(&:chomp)).sort.uniq.join("\n")
+    Pathname(filename).tap { |f| f.write("#{files}\n") }
   end
 
   def ignore_patterns(with_slugignore: false)
@@ -128,10 +141,10 @@ or update the Manifest.txt file with the following command:
     pats = strip_comments_and_empty_lines(pats)
 
     pats.map { |pat|
-      if pat =~ %r{/\z}
-        Regexp.new(%r{\A#{pat}})
-      elsif pat =~ %r{\A/[^*?]+\z}
+      if pat =~ %r{\A/[^*?]+\z}
         Regexp.new(%r{\A#{pat.sub(%r{\A/}, '')}/})
+      elsif pat =~ %r{/\z}
+        Regexp.new(/\A#{pat}/)
       else
         pat
       end
@@ -154,12 +167,13 @@ or update the Manifest.txt file with the following command:
     files.reject { |file| prune?(file, exclusions) }
   end
 
-  def prune?(file, exclusions = ignore_patterns())
+  def prune?(file, exclusions = ignore_patterns)
     exclusions.any? do |pat|
       case pat
       when /[*?]/
-        File.fnmatch?(pat, file, File::FNM_PATHNAME | File::FNM_EXTGLOB |
-                      File::FNM_DOTMATCH)
+        File.fnmatch?(
+          pat, file, File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_DOTMATCH
+        )
       when Regexp
         file =~ pat
       else
@@ -220,5 +234,3 @@ tmp/
 vendor/bundle/
   EOM
 end
-
-require_relative 'manifest/commands'