cli-mastermind 1.2.5 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b0de9e93e04cee67c931bcb124cbcefd75c68c27a2f7d8e44eba083dd4f9fbf
-  data.tar.gz: 559924cdd1e35d6498b6ccb23def42fdd2d0a669b9fedae234d62e5837161e95
+  metadata.gz: 7e6d02e18aa42a0c2c627dcdc76f2989b30a89c222bfd183a177a186f54c9953
+  data.tar.gz: 92541c8f669b777e89ba6c273b31f05ab3c51831653e4a2eacedd262d013ca10
 SHA512:
-  metadata.gz: 434badb48e238d256391e1667284ab24a1d67ffb7c79a4a38625b015a84b325daec31c8626cd5163abb215d49cab82dd874346100a2b811928534ef077b5bbc9
-  data.tar.gz: 1019f97fd8602609a1bedd3eb1ac578fe56da1c2376200fd0d04aeec366571f9b919ffc2a167618c435b3f5b20c541c241bf2484823c3a577dcad60080aee07d
+  metadata.gz: fbea7750593009ed092d09055dd5ee120a1ea3ee442a9576adff043d0d7214bee30f825956c99645e0eac2df177d739d505fc4efbf42a9c8ce7105f158be19ca
+  data.tar.gz: cc50ce47da3cc8aee137b85ae0c7bb04ca8060759a6e2a22999316ef3ee14e2a98ab5a36a41e354304158fad38c3651f642d425b912b765c525b70d689d06a7f

data/lib/cli/mastermind.rb

@@ -13,50 +13,86 @@ require 'cli/mastermind/executable_plan'
 require 'cli/mastermind/version'
 
 module CLI
+  # The main Mastermind module handles initial setup, user interaction, and final plan execution
   module Mastermind
     extend UserInterface
 
     class << self
-      # Expose the configuration loaded during +execute+.
+      # Lazy-load configuration object
+      #
+      # @return [Configuration] the loaded configuration
       def configuration
-        @config ||= spinner('Loading configuration') { Configuration.new @base_path }
+        @config ||= spinner('Loading configuration') do
+          Configuration.new(@base_path).tap do |config|
+
+            # Load any autoloads
+            if @autoloads && @autoloads.any?
+              @autoloads.each { |masterplan| config.load_masterplan masterplan }
+            end
+          end
+        end
       end
 
       # Allows utilities wrapping Mastermind to specify that only plans under a
       # particular path should be loaded.
+      #
+      # @param base_path [String] the path to the planfiles that should be loaded
+      # @return [Void]
       def base_path=(base_path)
         @base_path = base_path
       end
 
       # Allows utilities wrapping Mastermind to specify a top level plan without
       # having to monkey with the incomming arguments.
+      #
+      # @param base_plan [String] the top-level plan that should be automatically selected
+      # @return [Void]
       def base_plan=(base_plan)
         @base_plan = base_plan
       end
 
-      # Allows utilities wrapping Mastermind to specify planfiles that should be
-      # automatically loaded.  Plans loaded this way are loaded _after_ all other
-      # planfiles and so should only be used to set default values.
-      def autoload_masterplan(plan_file_path)
-        path = Pathname.new plan_file_path
-        raise Error, "`#{plan_file_path}` is not an absolute path" unless path.absolute?
-        raise Error, "`#{plan_file_path}` does not exist or is not a file" unless path.file?
+      # Convenience method for ArgParse.add_option
+      #
+      # @see ArgParse.add_option
+      #
+      # @param args arguments passed directly to OptionParser#on
+      # @param block [Proc] block passed as the handler for the above arguments
+      # @return [Void]
+      def add_argument(*args, &block)
+        ArgParse.add_option(*args, &block)
+      end
+
+      # Allows utilities wrapping Mastermind to specify masterplans that should be
+      # automatically loaded.  Masterplans loaded this way are loaded _after_ all
+      # others and so should only be used to set default values.
+      #
+      # Adding a new autoload after configuration has been initialized will
+      # immediately load the new masterplan.
+      #
+      # @param masterplan_path [String] the path to the masterplan to load
+      # @return [Void]
+      def autoload_masterplan(masterplan_path)
+        path = Pathname.new masterplan_path
+        raise Error, "`#{masterplan_path}` is not an absolute path" unless path.absolute?
+        raise Error, "`#{masterplan_path}` does not exist or is not a file" unless path.file?
         @autoloads ||= []
-        @autoloads << plan_file_path
+        @autoloads << masterplan_path
+
+        # Don't use configuration method here to avoid loading configuration early
+        @config.load_masterplan masterplan_path unless @config.nil?
       end
 
       # Process incoming options and take an appropriate action.
       # This is normally called by the mastermind executable.
+      #
+      # @param cli_args [Array<String>] the arguments to pass into {ArgParse}
+      # @return [Void]
       def execute(cli_args=ARGV)
         @arguments = ArgParse.new(cli_args)
 
         enable_ui if @arguments.display_ui?
 
         frame('Mastermind') do
-          if @autoloads && @autoloads.any?
-            @autoloads.each { |masterplan| configuration.load_masterplan masterplan }
-          end
-
           if @arguments.dump_config?
             do_print_configuration
             exit 0
@@ -102,6 +138,10 @@ module CLI
       # While it's entirely valid to have a plan name that inlcudes a space, you
       # should avoid them if you plan to look up your plan using this method.
       #
+      # Plans with spaces in the name can be looked up using only the first form
+      # of this method.
+      #
+      # @param plan_stack [Array<String>] an array of plans to navigate to
       def [](*plan_stack)
         # Allow for a single space-separated string
         if plan_stack.size == 1 and plan_stack.first.is_a?(String)
@@ -113,12 +153,18 @@ module CLI
         end
       end
 
+      # Lazy-load the plans to be used by Mastermind
+      #
+      # @return [ParentPlan] the top-level parent plan which holds all loaded plans
       def plans
         @plans ||= spinner('Loading plans') { Loader.load_all configuration.plan_files }
       end
 
       private
 
+      # Prints the configuration object built from the loaded masterplan files.
+      #
+      # @return [Void]
       def do_print_configuration
         frame('Configuration') do
           fade_code = CLI::UI::Color.new(90, '').code
@@ -153,6 +199,9 @@ module CLI
         end
       end
 
+      # Filters and displays plans based on the pattern from the passed in arguements
+      #
+      # @return [Void]
       def do_filtered_plan_display
         filter_plans @arguments.pattern
 
@@ -165,6 +214,14 @@ module CLI
         end
       end
 
+      # Builds the string that describes a plan.
+      #
+      # Used for human-readable output of a plan's name, aliases, and description.
+      #
+      # @param plans [ParentPlan,Hash<name, Plan>] the plans to be displayed
+      # @param prefix [String] a prefix to print at the beginning of the output line
+      #
+      # @return [String] the display string for the given plans
       def build_display_string(plans=self.plans, prefix='')
         fade_code = CLI::UI::Color.new(90, '').code
         reset     = CLI::UI::Color::RESET.code
@@ -198,6 +255,14 @@ module CLI
         display_string.gsub(/\n{3,}/, "\n\n")
       end
 
+      # Removes plans whose names don't match the given pattern from the tree.
+      #
+      # Modifies +plans+ in place!
+      #
+      # @param pattern [Regexp] the pattern to match against
+      # @param plans [ParentPlan, Hash<name, Plan>] the plans to filter
+      #
+      # @return [Void]
       def filter_plans(pattern, plans=self.plans)
         plans.keep_if do |name, plan|
           # Don't display plans without a description or children
@@ -211,6 +276,11 @@ module CLI
         end
       end
 
+      # Processes command line arguements to build the starting plan stack.
+      #
+      # @see ArgParse
+      #
+      # @return [Void]
       def process_plan_names
         @arguments.do_command_expansion!(configuration)
 
@@ -235,6 +305,11 @@ module CLI
         end
       end
 
+      # Asks the user to select a plan from the current list of plans.
+      #
+      # Repeated invokations of this command allow the user to traverse the plan tree.
+      #
+      # @return [Void]
       def do_interactive_plan_selection
         options = (@selected_plan || plans).map { |k,v| [titleize(k.to_s), v] }.to_h
 
@@ -242,14 +317,22 @@ module CLI
         @plan_stack << titleize(@selected_plan.name)
       end
 
+      # @return [Boolean] if the currently selected plan is executable
       def executable_plan_selected?
         not (@selected_plan.nil? or @selected_plan.has_children?)
       end
 
+      # Interaction can be skipped via command line flags (see {ArgParse}) or configuration
+      # from a masterplan (see {Configuration})
+      #
+      # @return [Boolean] if the user is sure they want to execute the given plan
       def user_is_sure?
         !@arguments.ask? or !configuration.ask? or confirm("Execute plan #{@plan_stack.join('/')}?")
       end
 
+      # Executes the selected plan
+      #
+      # @return [Void]
       def execute_plan!
         @selected_plan.call(@arguments.plan_arguments)
       end

data/lib/cli/mastermind/arg_parse.rb

@@ -1,16 +1,35 @@
 require 'optparse'
 
 module CLI::Mastermind
+  # Processes command line arguments and provides a more useful representation of
+  # the provided options.
   class ArgParse
-    # When set, used to display available plans
+    # @return [Regexp] the pattern to use when filtering plans for display
     attr_reader :pattern
 
-    # Used by mastermind to lookup plans
-    # attr_reader :mastermind_arguments
-
-    # Passed as-is into plans
+    # @return [Array<String>] additional command line arguements passed into the executed plan
     attr_reader :plan_arguments
 
+    class << self
+      # @see ArgParse.add_option
+      # @return [Array] a set of extra options added to the argument parser
+      attr_reader :extra_options
+
+      # Adds arbitrary options to the argument parser.
+      #
+      # Mostly useful for tools wrapping mastermind to add options that all methods
+      # should have access to.
+      #
+      # @param args arguments passed directly to OptionParser#on
+      # @param block [Proc] block passed as the handler for the above arguments
+      # @return [Void]
+      def add_option(*args, &block)
+        @extra_options ||= []
+        @extra_options << [args, block]
+      end
+    end
+
+    # @param arguments [Array<String>] the arguements to parse
     def initialize(arguments=ARGV)
       @initial_arguments = arguments
       @ask = true
@@ -21,6 +40,36 @@ module CLI::Mastermind
       parse_arguments
     end
 
+    # Uses configured user aliases to perform command expansion.
+    #
+    # For example, an alias defined in a masterplan like so:
+    #
+    #     define_alias 'foo', 'foobar'
+    #
+    # when invoked like `mastermind foo` would operate as if the user had actually
+    # typed `mastermind foobar`.
+    #
+    # User aliases (defined in a masterplan) are much more powerful than planfile
+    # aliases (defined in a planfile).  Unlike planfile aliases, user aliases
+    # can define entire "plan stacks" and are recursively expanded.
+    #
+    # For example, the following aliases:
+    #
+    #     define_alias 'foo', 'foobar'
+    #     define_alias 'bar', 'foo sub'
+    #
+    # invoked as `mastermind bar` would operate as if the user had actually typed
+    # `mastermind foobar sub`.
+    #
+    # Plan arguments can also be specified in a user alias.  For example:
+    #
+    #     define_alias '2-add-2', 'calculator add -- 2 2'
+    #
+    # would expand as expected with the extra arguements (`'2 2'`) being passed
+    # into the executed plan.
+    #
+    # @param config [Configuration] the configuration object to use when expanding user aliases
+    # @return [Void]
     def do_command_expansion!(config)
       @alias_arguments = []
 
@@ -35,39 +84,51 @@ module CLI::Mastermind
     end
 
     # Adds the given base plan to the beginning of the arguments array
+    #
+    # @param base_plan [String] the base plan to add to the beginning of the arguments
     def insert_base_plan!(base_plan)
       @mastermind_arguments.unshift base_plan
       nil # prevent @mastermind_arguments from leaking
     end
 
+    # @return [Boolean] if the user has requested plan display
     def display_plans?
       !@pattern.nil?
     end
 
+    # @return [Boolean] if additional plan names exist in mastermind's arguments
     def has_additional_plan_names?
       @mastermind_arguments.any?
     end
 
+    # Removes and returns the plan name at the beginning of the argument list.
+    #
+    # @return [String] the name of the next plan in the list of arguments
     def get_next_plan_name
       @mastermind_arguments.shift
     end
 
+    # @return [Boolean] if the UI is displayed
     def display_ui?
       @display_ui
     end
 
+    # @return [Boolean] if the user should be asked for confirmation prior to plan execution
     def ask?
       @ask
     end
 
+    # @return [Boolean] if the user requested their configuration be displayed
     def dump_config?
       @show_config
     end
 
+    # @return [Boolean] if callable attributes should be resolved prior to being displayed
     def resolve_callable_attributes?
       @call_blocks
     end
 
+    # @return [OptionParser] the parser to process command line arguments with
     def parser
       @parser ||= OptionParser.new do |opt|
         opt.banner = 'Usage: mastermind [--help, -h] [--plans[ PATTERN], --tasks[ PATTERN], -T [PATTERN], -P [PATTERN] [PLAN[, PLAN[, ...]]] -- [PLAN ARGUMENTS]'
@@ -93,11 +154,21 @@ module CLI::Mastermind
           @call_blocks = @show_config
           @show_config = true
         end
+
+        self.class.extra_options.each do |(arguments, block)|
+          opt.on(*arguments, &block)
+        end
       end
     end
 
     private
 
+    # Performs alias expansion using the provided configuration object
+    #
+    # @param config [Configuration] the configuration object used to perform expansion
+    # @param argument [String] the argument to be expanded
+    #
+    # @return [Array<String>, String] the expanded arguments
     def expand_argument(config, argument)
       dealiased = config.map_alias(argument)
 
@@ -121,6 +192,10 @@ module CLI::Mastermind
       dealiased
     end
 
+    # Splits the incoming arguments and processes those before the first `--`.
+    #
+    # Arguments after the first `--` on the command line are passed verbatim into
+    # the executed plan.
     def parse_arguments
       @mastermind_arguments = @initial_arguments.take_while { |arg| arg != '--' }
       @plan_arguments = @initial_arguments[(@mastermind_arguments.size + 1)..-1] || []

data/lib/cli/mastermind/configuration.rb

@@ -3,20 +3,28 @@ require 'set'
 module CLI
   module Mastermind
     ##
-    # Main configuration object.  Walks up the file tree looking for masterplans
-    # and loading them into to build a the configuration used by the CLI.
+    # Main configuration object.  Walks up the file tree looking for masterplan
+    # files and loading them to build a the configuration used by the CLI.
     #
-    # Masterplans are loaded such that configuration specified closest to the
-    # point of invocation override configuration from farther masterplans.
-    # This allows you to add folder specific configuration while still falling
-    # back to more and more general configuration options.
+    # These masterplan files are loaded starting from the current working directory
+    # and traversing up until a masterplan with a `at_project_root` directive or
+    # or the directory specified by a `project_root` directive is reached.
+    #
+    # Configuration options set with `configure` are latched once set to something
+    # non-nil.  This, along with the aforementioned load order of masterplan files,
+    # means that masterplan files closest to the source of your invokation will
+    # "beat" other masterplan files.
     #
     # A global masterplan located at $HOME/.masterplan (or equivalent) is loaded
     # _last_.  You can use this to specify plans you want accessible everywhere
     # or global configuration that should apply everywhere (unless overridden by
-    # more specific masterplans).
+    # more proximal masterplans).
+    #
+    # Additionally, there is a directive (`see_other`) that allows for masterplan
+    # files outside of the lookup tree to be loaded.
     #
-    # @see Configuration::DSL
+    # See {DSL} for a full list of the commands provided by Mastermind and a sample
+    # masterplan file.
     class Configuration
       # Filename of masterplan files
       PLANFILE = '.masterplan'
@@ -24,9 +32,15 @@ module CLI
       # Path to the top-level masterplan
       MASTER_PLAN = File.join(Dir.home, PLANFILE)
 
+      # The set of planfiles to load
       attr_reader :plan_files
 
       # Adds an arbitrary attribute given by +attribute+ to the configuration class
+      #
+      # @param attribute [String,Symbol] the attribute to define
+      #
+      # @!macro [attach] add_attribute
+      #   @!attribute [rw] $1
       def self.add_attribute(attribute)
         return if self.method_defined? attribute
 
@@ -49,6 +63,7 @@ module CLI
       # masterplans, so it's important that it be set.
       add_attribute :project_root
 
+      # @param base_path [String,nil] plans outside of the base path will be ignored
       def initialize(base_path=nil)
         @base_path = base_path
         @loaded_masterplans = Set.new
@@ -62,7 +77,12 @@ module CLI
         load_masterplan MASTER_PLAN
       end
 
-      # Adds a set of filenames for plans into the set of +@plan_files+
+      # Adds a set of filenames for plans into the set of +@plan_files+.
+      #
+      # Plans with paths outside the +@base_path+, if set, will be ignored.
+      #
+      # @param planfiles [Array<String>] new planfiles to add to the set of planfiles
+      # @return [Void]
       def add_plans(planfiles)
         allowed_plans = if @base_path.nil?
                           planfiles
@@ -74,6 +94,9 @@ module CLI
       end
 
       # Loads a masterplan using the DSL, if it exists and hasn't been loaded already
+      #
+      # @param filename [String] the path to the masterplan to load
+      # @return [Void]
       def load_masterplan filename
         if File.exists? filename and !@loaded_masterplans.include? filename
           @loaded_masterplans << filename
@@ -81,26 +104,44 @@ module CLI
         end
       end
 
+      # Defines a user alias
+      #
+      # @param alias_from [String] the string to be replaced during expansion
+      # @param alias_to [String, Array<String>] the expanded argument
+      # @return [Void]
       def define_alias(alias_from, alias_to)
         arguments = alias_to.split(' ') if alias_to.is_a? String
 
         @aliases[alias_from] = arguments unless @aliases.has_key? alias_from
       end
 
+      # Maps an input string to an alias.
+      #
+      # @param input [String] the value to be replaced
+      # @return [String,Array<String>] the replacement alias or the input, if no replacement exists
       def map_alias(input)
         @aliases[input]
       end
 
+      # @return [Boolean] the user's ask_for_confirmation setting
       def ask?
         @ask_for_confirmation
       end
 
+      # Sets +@ask_for_confirmation+ to `false`.
+      #
+      # @return [false]
       def skip_confirmation!
         @ask_for_confirmation = false
       end
 
       private
 
+      # Override the default NoMethodError with a more useful MissingConfigurationError.
+      #
+      # Since the configuration object is used directly by plans for configuration information,
+      # accessing non-existant configuration can lead to unhelpful NoMethodErrors.  This replaces
+      # those errors with more helpful errors.
       def method_missing(symbol, *args)
         super
       rescue NoMethodError
@@ -108,6 +149,8 @@ module CLI
       end
 
       # Walks up the file tree looking for masterplans.
+      #
+      # @return [Void]
       def lookup_and_load_masterplans
         load_masterplan File.join(Dir.pwd, PLANFILE)
 
@@ -123,6 +166,8 @@ module CLI
       # See the .masterplan file in the root of this repo for a full example of
       # the available options.
       class DSL
+        # @param config [Configuration] the configuration object used by the DSL
+        # @param filename [String] the path to the masterplan to be loaded
         def initialize(config, filename)
           @config = config
           @filename = filename
@@ -131,12 +176,17 @@ module CLI
 
         # Specifies that another masterplan should also be loaded when loading
         # this masterplan.  NOTE: This _immediately_ loads the other masterplan.
+        #
+        # @param filename [String] the path to the masterplan to be loaded
         def see_also(filename)
           @config.load_masterplan(File.expand_path(filename))
         end
 
         # Specifies the root of the project.
         # +root+ must be a directory.
+        #
+        # @param root [String] the root directory of the project
+        # @raise [InvalidDirectoryError] if +root+ is not a directory
         def project_root(root)
           unless Dir.exist? root
             raise InvalidDirectoryError.new('Invalid project root', root)
@@ -147,12 +197,17 @@ module CLI
 
         # Syntactic sugar on top of `project_root` to specify that the current
         # masterplan resides in the root of the project.
+        #
+        # @see project_root
         def at_project_root
           project_root File.dirname(@filename)
         end
 
         # Specify that plans exist in the given +directory+.
-        # Must be a valid directory
+        # Must be a valid directory.
+        #
+        # @param directory [String] path to a directory containing planfiles
+        # @raise [InvalidDirectoryError] if +directory+ is not a directory
         def plan_files(directory)
           unless Dir.exist? directory
             raise InvalidDirectoryError.new('Invalid plan file directory', directory)
@@ -166,11 +221,15 @@ module CLI
 
         # Syntactic sugar on top of `plan_files` to specify that plans exist in
         # a +plans/+ directory in the current directory.
+        #
+        # @see plan_files
         def has_plan_files
           plan_files File.join(File.dirname(@filename), 'plans')
         end
 
         # Specifies that a specific plan file exists at the given +filename+.
+        #
+        # @param files [Array<String>] an array of planfile paths
         def plan_file(*files)
           files = files.map { |file| File.expand_path file }
 
@@ -179,6 +238,19 @@ module CLI
 
         # Add arbitrary configuration attributes to the configuration object.
         # Use this to add plan specific configuration options.
+        #
+        # @overload configure(attribute, value=nil, &block)
+        #   @example configure(:foo, 'bar')
+        #   @example configure(:foo) { 'bar' }
+        #   @param attribute [String,Symbol] the attribute to define
+        #   @param value [] the value to assign
+        #   @param block [#call,nil] a callable that will return the value
+        #
+        # @overload configure(attribute)
+        #   @example configure(foo: 'bar')
+        #   @example configure('foo' => -> { 'bar' } # not recommended, but should work
+        #   @param attribute [Hash] a single entry hash with the key as the attribute
+        #     name and value as the corresponding value
         def configure(attribute, value=nil, &block)
           attribute, value = attribute.first if attribute.is_a? Hash
 
@@ -189,6 +261,9 @@ module CLI
 
         # Define a user alias.  User aliases are expanded as part of plan selection.
         # @see ArgParse#do_command_expansion!
+        #
+        # @param name [String] the string to be replaced
+        # @param arguments [String,Array<String>] the replacement
         def define_alias(name, arguments)
           @config.define_alias(name, arguments)
         end
@@ -201,6 +276,9 @@ module CLI
 
         private
 
+        # Used during planfile loading with a Dir.glob to load only supported planfiles
+        #
+        # @return [String] a comma separated list of supported file extensions
         def supported_extensions
           Loader.supported_extensions.join(',')
         end

data/lib/cli/mastermind/executable_plan.rb

@@ -1,8 +1,14 @@
 module CLI
   module Mastermind
+    # Executable Plan implementation.  Used in Planfile Loader to generate executable
+    # plans from its DSL.
     class ExecutablePlan
       include Plan
 
+      # Implementation of {Plan#call} which calls the block this plan was created with
+      #
+      # @param (see Plan#call)
+      # @see Plan#call
       def call(options=nil)
         case @block.arity
         when 1, -1 then instance_exec(options, &@block)

data/lib/cli/mastermind/loader.rb

@@ -1,13 +1,26 @@
 module CLI::Mastermind
+  # Loader handles loading planfiles (+not+ masterplans) and is used directly by
+  # Mastermind.  Subclasses handle the actual parsing of plans, this class is
+  # primarily concerned with finding the correct loader to load a particular
+  # file.
+  #
+  # Loader subclasses are automatically added to the list of loaders.  Thus, adding
+  # a new loader is as simple as subclassing and adding the appropriate methods.
   class Loader
     class << self
       attr_reader :loadable_extensions
       @@loaders = []
 
+      # Adds a newly subclasses loader into the set of loaders.
       def inherited(subclass)
         @@loaders << subclass
       end
 
+      # Finds the correct loader for a given extension
+      #
+      # @param extension [String] the extensions to search with
+      # @raise [UnsupportedFileTypeError] if no compatible loader is found
+      # @return [Loader] the loader for the given +extension+.
       def find_loader(extension)
         loader = @@loaders.find { |l| l.can_load? extension }
 
@@ -16,19 +29,32 @@ module CLI::Mastermind
         loader
       end
 
+      # @return [Array<String>] all loadable extensions
       def supported_extensions
         @@loaders.flat_map { |l| l.loadable_extensions }
       end
 
+      # @param extension [String] the extension to check
+      # @return [Boolean] if the +extension+ is loadable
       def can_load?(extension)
         @loadable_extensions.include? extension
       end
 
+      # @abstract
+      # Used to load a given plan.
+      #
+      # @param filename [String] the path to the planfile to be loaded
       def load(filename)
         raise NotImplementedError
       end
 
-      # Loads a particular plan from the filesystem.
+      # Loads plans from the filesystem.
+      #
+      # The returned ParentPlan is intended for use by Mastermind itself.
+      #
+      # @param files [Array<String>] the list of planfiles to load
+      # @return [ParentPlan] a ParentPlan containing all the loaded plans
+      # @private
       def load_all(files)
         temp_plan = ParentPlan.new('INTERNAL PLAN HOLDER')
 

data/lib/cli/mastermind/loader/planfile_loader.rb

@@ -1,5 +1,7 @@
 module CLI::Mastermind
   class Loader
+    # Loader implementation to handle the default .plan format
+    # @private
     class PlanfileLoader < Loader
       @loadable_extensions = %w[ .plan ].freeze
 
@@ -15,8 +17,17 @@ module CLI::Mastermind
       class DSL
         extend Forwardable
 
+        # @return [Array<Plan>] the plans defined by the loaded file or block
         attr_reader :plans
 
+        # Loads and evaluates a local file or a given block.
+        #
+        # If given both, the block takes priority.
+        #
+        # @example DSL.new('path/to/file.plan')
+        # @example DSL.new { ...methods go here... }
+        # @param filename [String,nil] the name of the file that contains this plan
+        # @param block [#call,nil] a block to evaluate
         def initialize(filename=nil, &block)
           @plans = []
           @filename = filename
@@ -30,6 +41,10 @@ module CLI::Mastermind
           end
         end
 
+        # Describes a ParentPlan
+        #
+        # @param name [String] the name of the plan
+        # @param block [#call] passed to a new DSL object to define more plans
         def plot(name, &block)
           plan = ParentPlan.new name, @description, @filename
           @description = nil
@@ -38,17 +53,27 @@ module CLI::Mastermind
         end
         alias_method :namespace, :plot
 
+        # @param text [String] the description of the next plan
         def description(text)
           @description = text
         end
         alias_method :desc, :description
 
+        # Defines an executable plan
+        #
+        # @param name [String] the name of the plan
+        # @param plan_class [Plan] the plan class
+        # @param block [#call] passed into the newly created plan
+        # @return [void]
         def plan(name, plan_class = ExecutablePlan, &block)
           @plans << plan_class.new(name, @description, @filename, &block)
           @description = nil
         end
         alias_method :task, :plan
 
+        # Sets an alias on the previously created plan
+        #
+        # @param alias_to [String] the alias to add
         def set_alias(alias_to)
           @plans.last.add_alias(alias_to)
         end

data/lib/cli/mastermind/parent_plan.rb

@@ -1,5 +1,8 @@
 module CLI
   module Mastermind
+    # Plan implementation designed to hold other plans forming the intermediate
+    # nodes on the tree of loaded plans.
+    # @private
     class ParentPlan
       extend Forwardable
       include Plan
@@ -8,13 +11,21 @@ module CLI
       # Used in the interactive plan selector to display child plans
       attr_reader :children
 
+      # @param (see Plan)
+      # @see Plan
       def initialize(name, description=nil, filename=nil, &block)
         super
 
         @children = {}
       end
 
-      # Get the child plan with the specified +name+
+      # Get the child plan with the specified +name+.
+      #
+      # This method also checks plan aliases, so the given +name+ can also be a
+      # plan's alias.
+      #
+      # @param name [String] the name of the child plan to retrieve
+      # @return [Plan,nil] the child plan, if it exists
       def get_child(name)
         return @children[name] if @children.has_key? name
         @children.each_value.find { |child| child.aliases.include? name }
@@ -22,23 +33,50 @@ module CLI
       alias_method :[], :get_child
       alias_method :dig, :get_child
 
+      # For Enumerable support
       def_delegators :@children, :each, :keep_if, :empty?
 
+      # Adds new children to this plan
+      #
+      # @param plans [Array<Plan>] the plans to add
+      # @return [Void]
       def add_children(plans)
         raise InvalidPlanError, 'Cannot add child plans to a plan with an action' unless @block.nil?
         plans.each(&method(:incorporate_plan))
       end
 
+      # @return [Boolean] if this plan has any children
       def has_children?
         @children.any?
       end
 
       private
 
+      # Adds a new plan to the children hash
+      #
+      # @param plan [Plan] the plan to add
+      # @see resolve_conflicts
       def incorporate_plan(plan)
         @children[plan.name] = resolve_conflicts(plan.name, plan)
       end
 
+      # Resolves plan name collisions.
+      #
+      # If two child plans have the same name, how they're resolved depends on
+      # what kind of plan they are.  The following situations are convered by
+      # this method:
+      #
+      # 1) Both plans have children.
+      #   * In this case, the incoming plan's children are merged into the existing
+      #     plan and the incoming plan is discarded.
+      #
+      # 2) One or both plans have no children.
+      #   * In this case, it's assumed that the childless plans are executable.
+      #     A warning is printed an the incoming plan replaces the existing plan.
+      #
+      # @param key [String] the key the incoming plan will be stored under
+      # @param plan [Plan] the incoming plan
+      # @return [Plan] the plan to store
       def resolve_conflicts(key, plan)
         # If this namespace isn't taken we're good
         return plan unless @children.has_key?(key)

data/lib/cli/mastermind/plan.rb

@@ -33,23 +33,42 @@ module CLI
         end
       end
 
+      # @param name [String] the name of the plan
+      # @param description [String] the description of the plan
+      # @param filename [String] the name of the file which defined this plan
+      # @param block [#call,nil] a callable used by ExecutablePlan
       def initialize(name, description=nil, filename=nil, &block)
         @name = name.to_s.freeze
         @description = description.freeze
         @filename = filename
+        # TODO: Move this to ExecutablePlan?
         @block = block
         @aliases = Set.new
       end
 
+      # If this plan has children.
+      #
+      # Implemented for compatibility with ParentPlan to make plan traversal easier.
+      #
+      # @return [false] Plans have no children by default
       def has_children?
         false
       end
 
+      # Entrypoint called by Mastermind
+      #
+      # @abstract
+      # @param options [Array<String>,nil] options passed from the command line
+      # @raise [NotImplementedError]
       def call(options=nil)
         raise NotImplementedError
       end
       alias_method :execute, :call
 
+      # Defines a plan alias which allows this plan to be accessed using another
+      # string than its name.
+      #
+      # @param alias_to [String] the alias to accept
       def add_alias(alias_to)
         @aliases.add alias_to.to_s
       end

data/lib/cli/mastermind/user_interface.rb

@@ -6,14 +6,19 @@ module CLI::Mastermind::UserInterface
     CLI::UI::StdoutRouter.enable
   end
 
-  # :private:
+  # @private
+  # @return [Boolean] if the StdoutRouter is enabled
   def ui_enabled?
     CLI::UI::StdoutRouter.enabled?
   end
 
   # Display a spinner with a +title+ while data is being loaded
-  # @returns the value of the given block
+  #
   # @see https://github.com/Shopify/cli-ui#spinner-groups
+  #
+  # @param title [String] the title to display
+  # @param block [#call] passed to the underlying spinner implementation.
+  # @return the result of calling the given +block+
   def spinner(title, &block)
     return yield unless ui_enabled?
 
@@ -30,6 +35,10 @@ module CLI::Mastermind::UserInterface
   # The only difference between the two is that +AsyncSpinners+ provides a
   # mechanism for exfiltrating results by using +await+ instead of the usual
   # +add+.
+  #
+  # @see AsyncSpinners
+  #
+  # @yieldparam group [AsyncSpinners]
   def concurrently
     group = AsyncSpinners.new
 
@@ -42,6 +51,9 @@ module CLI::Mastermind::UserInterface
 
   # Uses +CLI::UI.fmt+ to format a string
   # @see https://github.com/Shopify/cli-ui#symbolglyph-formatting
+  #
+  # @param string [String] the string to format
+  # @return [String] the formatted string
   def stylize(string)
     CLI::UI.fmt string
   end
@@ -55,12 +67,19 @@ module CLI::Mastermind::UserInterface
 
   # Ask the user for some text.
   # @see https://github.com/Shopify/cli-ui#free-form-text-prompts
+  #
+  # @param question [String] the question to ask the user
+  # @param default [String] the default answer
+  # @return [String] the user's answer
   def ask(question, default: nil)
     CLI::UI.ask(question, default: default)
   end
 
   # Ask the user a yes/no +question+
   # @see https://github.com/Shopify/cli-ui#interactive-prompts
+  #
+  # @param question [String] the question to ask the user
+  # @return [Boolean] how the user answered
   def confirm(question)
     CLI::UI.confirm(question)
   end
@@ -69,13 +88,11 @@ module CLI::Mastermind::UserInterface
   # If less than 2 options would be displayed, the default value is automatically
   # returned.
   #
-  # @param +question+ The question to ask the user
-  # @param +options:+ Array|Hash the options to display
-  # @param +default:+ The default value for this question.  Defaults to the first
-  #                   option.  The default option is displayed first.  Assumed to
-  #                   exist within the given options.
-  #
-  # Any other keyword arguments given are passed down into +CLI::UI::Prompt.ask+.
+  # @param question [String] The question to ask the user
+  # @param options [Array<String>,Hash] the options to display
+  # @param default [String] The default value for this question.  Assumed to exist
+  #   within the given options.
+  # @param opts [Hash] additional options passed into +CLI::UI::Prompt.ask+.
   #
   # @see https://github.com/Shopify/cli-ui#interactive-prompts
   def select(question, options:, default: options.first, **opts)
@@ -111,14 +128,16 @@ module CLI::Mastermind::UserInterface
   end
 
   # Titleize the given +string+.
+  #
   # Replaces any dashes (-) or underscores (_) in the +string+ with spaces and
   # then capitalizes each word.
   #
-  # Examples:
-  #   titleize('foo') => 'Foo'
-  #   titleize('foo bar') => 'Foo Bar'
-  #   titleize('foo-bar') => 'Foo Bar'
-  #   titleize('foo_bar') => 'Foo Bar'
+  # @example titleize('foo') => 'Foo'
+  # @example titleize('foo bar') => 'Foo Bar'
+  # @example titleize('foo-bar') => 'Foo Bar'
+  # @example titleize('foo_bar') => 'Foo Bar'
+  #
+  # @param string [String] the string to titleize.
   def titleize(string)
     string.gsub(/[-_-]/, ' ').split(' ').map(&:capitalize).join(' ')
   end
@@ -133,6 +152,11 @@ module CLI::Mastermind::UserInterface
   # Optionally, a block may be passed to modify the output of the line prior to
   # printing.
   #
+  # @param command [Array<String>] the command to execute
+  # @param kwargs [Hash] additional arguments to be passed into +IO.popen+
+  #
+  # @yieldparam line [String] a line of output to be processed
+  #
   # @see IO.popen
   # @see Open3.popen
   def capture_command_output(*command, **kwargs, &block)
@@ -141,6 +165,8 @@ module CLI::Mastermind::UserInterface
     IO.popen(command.flatten, **kwargs) { |io| io.each_line { |line| print block.call(line) } }
   end
 
+  # Implementation of CLI::UI::SpinGroup with that keeps track of the results from
+  # individual spinners.
   class AsyncSpinners < CLI::UI::SpinGroup
     attr_reader :results
 
@@ -149,6 +175,11 @@ module CLI::Mastermind::UserInterface
       super
     end
 
+    # Waits for a block to execute while displaying a spinner.
+    #
+    # @param title [String] the title to display
+    #
+    # @yieldparam spinner [CLI::UI::Spinner]
     def await(title)
       @results[title] = nil
 

data/lib/cli/mastermind/version.rb

@@ -7,8 +7,8 @@ module CLI
 
     module VERSION
       RELEASE = 1
-      MAJOR = 2
-      MINOR = 5
+      MAJOR = 3
+      MINOR = 0
       PATCH = nil
 
       STRING = [RELEASE, MAJOR, MINOR, PATCH].compact.join('.').freeze

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cli-mastermind
 version: !ruby/object:Gem::Version
-  version: 1.2.5
+  version: 1.3.0
 platform: ruby
 authors:
 - Chris Hall
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-12-04 00:00:00.000000000 Z
+date: 2020-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cli-ui
@@ -58,6 +58,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.24
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.24
 description: |2
                            Take over the world from your command line!
                            With mastermind, you can quickly build and generate