thor_enhance 0.4.0 → 0.5.0

data/lib/thor_enhance/autogenerate/templates/command.rb.erb

@@ -0,0 +1,49 @@
+# <%= title.to_s.titlecase %>
+
+## Description
+<%= command.long_description || command.description %>
+
+```bash
+# Base command for `<%= command.usage %>`
+<%= basename_string %>
+```
+
+<%= custom_headers %>
+
+<% headers.each do |header| %>
+## <%= header[:name] %>
+<%= header[:desc]%>
+<% end %>
+<% if drawn_out_examples %>
+---
+
+## Examples
+<% drawn_out_examples.each do |ex|%>
+```bash
+<%= ex %>
+```
+<% end %>
+<% end %>
+<% if !method_options_erb.strip.empty? %>
+---
+
+<% if children_descriptors.empty? %>
+## Method Options
+
+<%= method_options_erb %>
+<% end %>
+<% else %>
+<% children_descriptors.each do |child| %>
+### [<%= child[:title]%>](<%= child[:link] %>)
+
+<%= child[:description] %>
+
+```bash
+<%= child[:basename_string]%> <options>
+<%= child[:examples].map { _1 }.join("\n") %>
+```
+<% end %>
+<% end %>
+---
+
+<%= footer_erb %>

data/lib/thor_enhance/autogenerate/templates/footer.rb.erb

@@ -0,0 +1,3 @@
+> AutoGenerateted by [ThorEnhance](https://github.com/matt-taylor/thor_enhance) <br>
+> Regenerate file with: <%= regenerate_single_command %> <br>
+> Regenerate all files with: <%= regenerate_thor_command %>

data/lib/thor_enhance/autogenerate/templates/option.rb.erb

@@ -0,0 +1,14 @@
+# What: <%= option.description %>
+# Type: <%= option.type %>
+# Required: <%= option.required %>
+# <%= "**Allowed inputs:** #{option.enum}" if option.enum %>
+# <%= name.to_s.titlecase %>
+<%= invocations.map { "`#{_1}`"}.join(" | ") %>
+
+**What:** <%= option.description %><br>
+**Invocation:** <br>
+**Type:** <%= option.type %><br>
+**Default:** <%= option.default || "none" %><br>
+**Required:** <%= option.required %><br>
+<%= "**Allowed inputs:** #{option.enum}" if option.enum %>
+

data/lib/thor_enhance/autogenerate/templates/root.rb.erb

@@ -0,0 +1,9 @@
+## [<%= root_child[:title]%>](<%= root_child[:link] %>)
+<%= root_child[:description] %>
+
+```bash
+# Help Command
+<%= root_child[:basename_string]%> <options>
+
+<%= root_child[:examples].map { _1 }.join("\n") %>
+```

data/lib/thor_enhance/autogenerate/validate.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ThorEnhance
+  module Autogenerate
+    module Validate
+      module_function
+
+      def validate(options:, root: nil)
+        root_result = validate_root(options: options, root: root)
+        return root_result if root_result[:status] != :pass
+
+        trunk = root_result[:trunk]
+        constant = root_result[:constant]
+
+        subcommand_result = validate_subcommand(options: options, trunk: trunk)
+        return subcommand_result if subcommand_result[:status] != :pass
+
+        trunk = subcommand_result[:trunk]
+        command_result = validate_command(options: options, trunk: trunk, constant: constant)
+        return command_result if command_result[:status] != :pass
+        command = command_result[:command]
+        { command: command, trunk: trunk, constant: constant, status: :pass }
+      end
+
+      def validate_root(options:, root:)
+        begin
+          constant = root || Object.const_get(options.root.to_s)
+        rescue NameError => e
+          msg_array = [
+            "Unable to load provided --root|-r option `#{options.root}`",
+            "Please check the spelling and ensure the klass has loaded"
+          ]
+          return { error: e, msg_array: msg_array, status: :fail }
+        end
+
+        begin
+          trunk = ThorEnhance::Tree.tree(base: constant)
+        rescue TreeFailure => e
+          msg_array = [
+            "--root|-r option is not a Thor klass.",
+            "Please ensure that the provided klass is a child of Thor"
+          ]
+          return { error: e, msg_array: msg_array, status: :fail }
+        end
+
+        { trunk: trunk, constant: constant, status: :pass }
+      end
+
+      def validate_command(options:, trunk:, constant:)
+        # Return early when command is not present in the options object
+        command = options.command
+        return { status: :pass, trunk: trunk, command: nil } if command.nil?
+
+        # Return early when command is found in the tree trunk
+        command = trunk.children[options.command] rescue trunk[options.command]
+        return { status: :pass, trunk: trunk, command: command } if command
+
+        # Command option was available but command was not found in the trunk
+        msg_array = ["Failed to find --command|-c `#{options.command}`"]
+        msg_array << "Provided root command `#{constant}`"
+        msg_array << "With Provided subcommand `#{options.subcommand}`" if options.subcommand
+        msg_array << "does not have command `#{options.command}` as a child" if options.subcommand
+
+        { msg_array: msg_array, status: :fail }
+      end
+
+      def validate_subcommand(options:, trunk:)
+        subcommands = options.subcommand
+        return { trunk: trunk, status: :pass } if subcommands.nil?
+
+        subcommands = subcommands.dup
+        subcommand = subcommands.shift
+        temp_trunk = trunk[subcommand]
+        while subcommand != nil
+          if temp_trunk.nil? || !temp_trunk.children?
+            msg_array = [
+              "Order is important with --subcommands|-s options",
+              "Provided with: #{options.subcommand}",
+              "Subcommand `#{subcommand}` does not have any child commands",
+              "Every provided subcommand must have children",
+              "If the subcommand `#{subcommand}` is meant to be a command",
+              "Pass `#{subcommand}` in as `--command|-c #{subcommand}` instead",
+            ]
+            return { msg_array: msg_array, status: :fail }
+          end
+          subcommand = subcommands.shift
+          # Will always be in the child hash at this point if subcommand exists
+          temp_trunk = temp_trunk.children[subcommand] if subcommand
+        end
+
+        { trunk: temp_trunk, subcommands: options.subcommand, status: :pass }
+      end
+    end
+  end
+end

data/lib/thor_enhance/autogenerate.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "thor_enhance/autogenerate/configuration"
+require "thor_enhance/autogenerate/validate"
+require "thor_enhance/autogenerate/option"
+require "thor_enhance/autogenerate/command"
+
+module ThorEnhance
+  module Autogenerate
+    module_function
+
+    ROOT_ERB = "#{File.dirname(__FILE__)}/autogenerate/templates/root.rb.erb"
+    ROOT_TEMPLATE = ERB.new(File.read(ROOT_ERB))
+
+    def execute!(options:, basename: File.basename($0), root: nil)
+      validate_result = Validate.validate(options: options, root: root)
+      return validate_result if validate_result[:status] != :pass
+
+      command = validate_result[:command]
+      trunk = validate_result[:trunk]
+      leaves =
+        if command
+          { options.command => command }
+        elsif Hash === trunk
+          # Parent trunk is a hash -- structure needs to change
+          trunk
+        else
+          # if not parent, grab the children
+          trunk.children
+        end
+
+      command_structure = leaves.map do |name, leaf|
+        parent = Command.new(name: name, leaf: leaf, basename: basename)
+      end
+
+      # flatten_children returns all kids, grandkids, great grandkids etc of the commands returned from the above mapping
+      youthful_kids = command_structure.map(&:flatten_children).flatten
+
+      # this is a flat map of the entire family tree. Each node knows where it is so we can flatten it
+      family_tree = command_structure + youthful_kids
+
+      save_generated_readmes!(commands: family_tree, generated_root: options.generated_root, apply: options.apply)
+    end
+
+    def save_generated_readmes!(commands:, generated_root:, apply:)
+      parent = generated_root || ENV["THOR_ENHANCE_GENERATED_ROOT_PATH"]
+      full_root = "#{parent}/commands"
+      saved_status = commands.map do |command|
+        command.save_self!(root: full_root, apply: apply)
+      end
+      self_for_roots =  saved_status.collect { _1[:self_for_root] }
+      saved_status << root_savior!(apply: apply, full_root: full_root, self_for_roots: self_for_roots)
+
+      { status: :pass, saved_status: saved_status }
+    end
+
+    def root_savior!(full_root:, self_for_roots:, apply:)
+      full_path = "#{full_root}/Readme.md"
+      root_erb_result = self_for_roots.map do |root_child|
+        ROOT_TEMPLATE.result_with_hash({ root_child: root_child })
+      end.join("\n")
+
+      FileUtils.mkdir_p(full_root)
+      if File.exist?(full_path)
+        content = File.read(full_path)
+        diff = root_erb_result == content ? :same : :overwite
+      else
+        diff = :new
+      end
+
+      if apply
+        File.write(full_path, root_erb_result)
+      end
+
+      { path: full_path, diff: diff, apply: apply }
+    end
+  end
+end

data/lib/thor_enhance/command_method.rb

@@ -14,16 +14,18 @@ module ThorEnhance
       ThorEnhance.configuration.command_method_enhance.each do |name, object|
         # Define a new method based on the name of each enhanced command method
         # Method takes care all validation except requirment -- Requirement is done during command initialization
-        ClassMethods.define_method("#{name}") do |input|
+        ClassMethods.define_method("#{name}") do |input = nil, *args, **kwargs|
           return nil unless ThorEnhance.configuration.allowed?(self)
 
-          value = instance_variable_get("@#{name}")
-          value ||= {}
           # Usage is nil when the `desc` has not been defined yet -- Under normal circumstance this will never happen
           if @usage.nil?
             raise ArgumentError, "Usage is not set. Please ensure `#{name}` is defined after usage is set"
           end
 
+          __thor_enhance_validate_arguments!(object, input, args, kwargs)
+          value = instance_variable_get("@#{name}")
+          value ||= {}
+
           # Required check gets done on command initialization (defined below in ClassMethods)
           if input.nil?
             # no op when it is nil
@@ -39,14 +41,14 @@ module ThorEnhance
 
           if object[:repeatable]
             value[@usage] ||= []
-            value[@usage] << input
+            value[@usage] << { input: input, arguments: { kwargs: kwargs, positional: args } }
           else
             if value[@usage]
               raise ValidationFailed, "#{@usage} recieved command method `#{name}` with repeated invocations of " \
                 "`#{name}`. Please remove the secondary invocation. Or set `#{name}` as a repeatable command method"
             end
 
-            value[@usage] = input
+            value[@usage] = { input: input, arguments: { kwargs: kwargs, positional: args } }
           end
 
           instance_variable_set("@#{name}", value)
@@ -106,6 +108,10 @@ module ThorEnhance
               # Skip if the method is part of the ignore list
               next if ThorEnhance::Tree.ignore_commands.include?(meth.to_s)
 
+              # subcommands/subtasks need not require things that regular commands need
+              # If user wants them on the sucommand, thats cool, but we will never enforce it
+              next if subcommands.map(&:to_s).include?(meth.to_s)
+
               # At this point, the command method is missing, we are not in disable mode, and the command method was required
               # raise all hell
               raise ThorEnhance::RequiredOption, "`#{meth}` does not have required command method #{name} invoked. " \
@@ -131,6 +137,30 @@ module ThorEnhance
 
       private
 
+
+      def __thor_enhance_validate_arguments!(object, input, args, kwargs)
+        expected_arity = object.dig(:arity)
+        if args.length != expected_arity
+          raise ArgumentError, "Excluding #{input}, the expected arity command method `#{name}` for #{@usage} is #{expected_arity}. Provided #{args.length}"
+        end
+
+        # checks if there are extra kwargs present that are not expected
+        available_kwargs = object.dig(:kwargs).keys
+        extra_keys = kwargs.keys - available_kwargs
+        unless extra_keys.empty?
+          raise ArgumentError, "#{@usage} received command method `#{name}` with unknown KWargs #{extra_keys}"
+        end
+
+        # Checks if all the required kwargs are present
+        req_kwargs = object.dig(:kwargs).select { _2 }.keys
+        missing_required_kwargs = req_kwargs - kwargs.keys
+
+        # binding.pry if expected_arity > 0 || available_kwargs.length > 0
+        return if missing_required_kwargs.empty?
+
+        raise ArgumentError, "#{@usage} received command method `#{name}` with missing KWargs #{missing_required_kwargs}"
+      end
+
       def __thor_enhance_access(type:, &block)
         raise ArgumentError, "Expected to receive block. No block given" unless block_given?
 

data/lib/thor_enhance/configuration.rb

@@ -58,6 +58,30 @@ module ThorEnhance
       self.class.disallow_changes!
     end
 
+    def readme_enhance!(required: false, &block)
+      # only inject readme things if it is required client side
+      require "thor_enhance/thor_auto_generate_inject"
+      require "thor_enhance/autogenerate"
+
+      if defined?(@autogenerated_config)
+        raise ValidationFailed, "ReadMe Enhance has already been initialized."
+      end
+
+      autogenerated_config.set_default_required(required)
+      autogenerated_config.default
+      yield(autogenerated_config) if block_given?
+
+      autogenerated_config.configuration.each do |meth, object|
+        object.each do |name, args|
+          public_send(meth, name, **args)
+        end
+      end
+    end
+
+    def autogenerated_config
+      @autogenerated_config ||= Autogenerate::Configuration.new
+    end
+
     def command_method_enhance
       @command_method_enhance ||= {}
     end
@@ -66,6 +90,14 @@ module ThorEnhance
       @klass_procs ||= []
     end
 
+    def basename
+      @basename
+    end
+
+    def basename=(name)
+      @basename = name
+    end
+
     def allowed
       @allowed ||= DEFAULT_ALLOWED
     end
@@ -92,14 +124,21 @@ module ThorEnhance
     end
 
     # Adding a new method to enhance the overall command
-    def add_command_method_enhance(name, allowed_klasses: nil, enums: nil, required: false, repeatable: false)
+    def add_command_method_enhance(name, allowed_klasses: nil, enums: nil, required: false, repeatable: false, arity: 0, required_kwargs: [], optional_kwargs: [])
+      return if ENV["SKIP_TESTING_METHOD"]
+
       self.class.allow_changes?
 
-      add_to_variable(command_method_enhance, ::Thor::Command.instance_methods, name, allowed_klasses, enums, required, repeatable)
+      kwargs = {}
+      required_kwargs.each { kwargs[_1.to_sym] = true }
+      optional_kwargs.each { kwargs[_1.to_sym] = false }
+      add_to_variable(command_method_enhance, ::Thor::Command.instance_methods, name, allowed_klasses, enums, required, repeatable, arity, kwargs)
     end
 
     # add a new flag on the command option
     def add_option_enhance(name, allowed_klasses: nil, enums: nil, required: false)
+      return if ENV["SKIP_TESTING_METHOD"]
+
       self.class.allow_changes?
 
       add_to_variable(option_enhance, ::Thor::Option.instance_methods, name, allowed_klasses, enums, required)
@@ -107,7 +146,7 @@ module ThorEnhance
 
     private
 
-    def add_to_variable(storage, methods, name, allowed_klasses, enums, required, repeatable = false)
+    def add_to_variable(storage, methods, name, allowed_klasses, enums, required, repeatable = false, arity = 0, kwargs = false)
       # Reject if the name is not a Symbol or a string
       if [String, Symbol].none? { _1 === name }
         raise ArgumentError, "Invalid name type received. Received [#{name}] of type [#{name.class}]. Expected to be of type String or Symbol"
@@ -136,7 +175,11 @@ module ThorEnhance
         raise ArgumentError, "Recieved allowed_klasses with #{allowed_klasses}. When present, it is expected to be an Array"
       end
 
-      storage[name.to_sym] = { allowed_klasses: allowed_klasses, enums: enums, required: required, repeatable: repeatable }
+      if arity < 0
+        raise ArgumentError, "Recieved arity with #{arity}. When present, it is expected to be greater than 0"
+      end
+
+      storage[name.to_sym] = { allowed_klasses: allowed_klasses, enums: enums, required: required, repeatable: repeatable, kwargs: kwargs, arity: arity }
     end
   end
 end

data/lib/thor_enhance/option.rb

@@ -5,8 +5,6 @@ require "thor"
 module ThorEnhance
   module Option
     def self.thor_enhance_injection!
-      return false unless ThorEnhance::Configuration.allow_changes?
-
       # Create getter method for the enhance instance variable
       ThorEnhance.configuration.option_enhance.each do |name, object|
         define_method(name) { instance_variable_get("@#{name}") }

data/lib/thor_enhance/sample.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "thor_enhance"
+
+module ThorEnhance
+  class Sample < Thor
+    thor_enhance_allow!
+
+    class SubCommand < Thor
+      thor_enhance_allow!
+
+      desc "innard", "Validate that a subcommand works. This description can be as long as you want it to be."
+      long_desc "Wow, This longer description will take precedence over the desc above. This is what will be shown in the readme autogenerated page. Try me out!"
+      example "innard --count 5", desc: "Innard sub command with a count of 5"
+      example "innard --count 35", desc: "Innard sub command with a count of 35"
+      header name: "Deprecation warning", desc: "This command will get deprecated in the next major version"
+      when_should_i_use_this "Use sub command task to validate that subocommands work as expected"
+      method_option :count, type: :numeric, readme: :skip
+      def innard;end;
+    end
+
+    desc "sub", "Thor sub command validation for thor enhance"
+    subcommand "sub", SubCommand
+
+    desc "sample", "This Sample command does a lot of nothing"
+    when_should_i_use_this <<~README
+    Have you ever wanted your code to be useless?
+    Well, this command does absolutely nothing.
+    This output is to say that this command does absolutely nothing
+    README
+    how_does_this_help "Honestly, this does not help at all", tag: "h4"
+    how_does_this_help "But its cool because it is a repatable command", tag: "h1"
+    example "sample", desc: "yo yo ma"
+    example "sample --boolean", desc: "yo yo ma"
+    method_option :boolean, aliases: "-b", type: :boolean, desc: "Just a normal boolean", readme: :important
+    def sample
+      Kernel.puts "Executed Sample method"
+    end
+  end
+end

data/lib/thor_enhance/thor_auto_generate_inject.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+####################
+#
+# Injects a method directly into the thor base class
+# This allows the developer to have this convenience method
+# Just by utilizing ThorEnhance
+#
+####################
+require "thor"
+
+class Thor
+  desc "thor_enhance_autogenerate", "Auto Generate ReadMe material for your Thor commands"
+  method_option :subcommand, aliases: "-s", type: :string, repeatable: true, desc: "When provided, autogeneration will execute on the subcommand"
+  method_option :command, aliases: "-c", type: :string, desc: "When provided, autogeneration will occur only on this method. Note: When used with subcommand, method must exist on subcommand"
+  method_option :basename, aliases: "-b", type: :string, desc: "The name of the file that executes the Thor script"
+  method_option :generated_root, aliases: "-r", type: :string, default: File.expand_path("generated_readme"), desc: "The root location to store autogenerated files"
+  method_option :apply, aliases: "-a", type: :boolean, desc: "When comfortable with the changes made, enabling apply will save changes to generated files"
+
+  def thor_enhance_autogenerate
+    require "thor_enhance/autogenerate"
+    basename = options.basename || ThorEnhance.basename || File.basename($0)
+
+    result = ThorEnhance::Autogenerate.execute!(options: options, root: self.class, basename: basename)
+
+    if result[:status] == :pass
+      __auto_generate_success!(result[:saved_status])
+    else
+      __auto_generate_fail!(result[:msg_array])
+    end
+  end
+
+  no_tasks do
+    def __auto_generate_success!(statuses)
+      if statuses.all? { _1[:apply] == true }
+        say "Readme changes are enabled", [:green, :bold], true
+      else
+        say "Readme changes are not enabled. To apply changes, add `--apply` to the command", [:on_white, :black], true
+      end
+      statuses.each do |status|
+        case status[:diff]
+        when :new
+          say "  Added    : #{status[:path]}", [:green, :bold], true
+        when :same
+          say "  No Change: #{status[:path]}", [:yellow, :bold], true
+        when :overwite
+          say "  Changes  : #{status[:path]}", [:cyan, :bold], true
+        else
+          say "           : #{status[:path]}", [:bold], true
+        end
+      end
+    end
+
+    def __auto_generate_fail!(msg_array)
+      say_error set_color("*********************** FAILED OPERATION ***********************", :red, :bold)
+      say_error set_color("FAIL: Unable to continue", :red, :bold)
+      msg_array.each do |line|
+        say_error set_color("FAIL: #{line}", :red, :bold)
+      end
+      say_error set_color("*********************** FAILED OPERATION ***********************", :red, :bold)
+      exit 1
+    end
+  end
+end

data/lib/thor_enhance/tree.rb

@@ -2,7 +2,7 @@
 
 module ThorEnhance
   class Tree
-    DEFAULT_IGNORE_COMMANDS = ["help"]
+    DEFAULT_IGNORE_COMMANDS = ["help", "thor_enhance_autogenerate"]
 
     def self.add_ignore_commands(command)
       return false if ignore_commands.include?(command)
@@ -20,6 +20,8 @@ module ThorEnhance
     end
 
     def self.tree(base:, parent: nil)
+      raise TreeFailure, "#{base} does not respond to all_commands. Unable to continue" unless base.respond_to?(:all_commands)
+
       base.all_commands.map do |k, command|
         next if ignore_commands.include?(k)
 
@@ -36,7 +38,7 @@ module ThorEnhance
       @parent = parent
       @base = base
       @command = command
-      @children = []
+      @children = {}
 
       if !base.subcommand_classes.nil? && base.subcommand_classes[command.name]
         @children = self.class.tree(parent: self, base: base.subcommand_classes[command.name])

data/lib/thor_enhance/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ThorEnhance
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/thor_enhance.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "active_support"
+
 require "thor_enhance/base"
 require "thor_enhance/command"
 require "thor_enhance/command_hook"
@@ -10,10 +12,16 @@ require "thor_enhance/tree"
 
 module ThorEnhance
   class BaseError < StandardError; end
-  class OptionNotAllowed < StandardError; end
-  class ValidationFailed < StandardError; end
-  class RequiredOption < StandardError; end
-  class OptionDeprecated < StandardError; end
+  class OptionNotAllowed < BaseError; end
+  class ValidationFailed < BaseError; end
+  class RequiredOption < BaseError; end
+  class OptionDeprecated < BaseError; end
+  class TreeFailure < BaseError; end
+  class AutoGenerateFailure < BaseError; end
+
+  def self.basename
+    configuration.basename
+  end
 
   def self.configure
     yield configuration if block_given?

data/thor_enhance.gemspec

@@ -30,4 +30,5 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "thor", "~> 1.3"
+  spec.add_dependency "activesupport", ">=6"
 end