thor_enhance 0.3.0 → 0.5.0

data/lib/thor_enhance/autogenerate/configuration.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ThorEnhance
+  module Autogenerate
+    class Configuration
+      attr_reader :question_headers, :custom_headers, :configuration, :readme_empty_group, :readme_skip_key, :readme_enums
+
+      DEFAULT_SKIP_KEY = :skip
+
+      def initialize(required: false)
+        @required = required
+        @configuration = { add_option_enhance: {}, add_command_method_enhance: {} }
+        @readme_enums = []
+        @custom_headers = []
+        @question_headers = []
+      end
+
+      def set_default_required(value)
+        @required = value
+      end
+
+      def default
+        ThorEnhance::Configuration.allow_changes?
+
+        example
+        header
+        title
+        readme
+      end
+
+      def title(required: false)
+        ThorEnhance::Configuration.allow_changes?
+
+        required = required.nil? ? @required : required
+        configuration[:add_command_method_enhance][:title] = { repeatable: false, required: required }
+      end
+
+      def example(required: nil, repeatable: true)
+        ThorEnhance::Configuration.allow_changes?
+
+        required = required.nil? ? @required : required
+        configuration[:add_command_method_enhance][:example] = { repeatable: repeatable, required: required, required_kwargs: [:desc] }
+      end
+
+      def header
+        ThorEnhance::Configuration.allow_changes?
+
+        configuration[:add_command_method_enhance][:header] = { repeatable: true, required: false, required_kwargs: [:name, :desc], optional_kwargs: [:tag] }
+      end
+
+      def custom_header(name, question: false, repeatable: false, required: false)
+        ThorEnhance::Configuration.allow_changes?
+
+        raise ArgumentError, "Custom Header name must be unique. #{name} is already defined as a custom header. " if custom_headers.include?(name.to_sym)
+
+        custom_headers << name.to_sym
+        question_headers << name.to_sym if question
+        configuration[:add_command_method_enhance][name.to_sym] = { repeatable: repeatable, required: required, optional_kwargs: [:tag] }
+      end
+
+      def readme(required: nil, empty_group: :unassigned, skip_key: DEFAULT_SKIP_KEY, enums: [:important, :advanced, skip_key.to_sym].compact)
+        ThorEnhance::Configuration.allow_changes?
+
+        @readme_empty_group = empty_group
+        @readme_skip_key = skip_key
+        @readme_enums = enums.map(&:to_sym)
+        required = required.nil? ? @required : required
+        configuration[:add_option_enhance][:readme] = { enums: enums, required: required }
+      end
+    end
+  end
+end

data/lib/thor_enhance/autogenerate/option.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module ThorEnhance
+  module Autogenerate
+    class Option
+      TEMPLATE_ERB = "#{File.dirname(__FILE__)}/templates/option.rb.erb"
+      OPTION_TEMPLATE = ERB.new(File.read(TEMPLATE_ERB))
+
+      attr_reader :name, :option
+
+      def initialize(name:, option:)
+        @name = name
+        @option = option
+      end
+
+      def template_text
+        text = []
+        text << "# What: #{option.description}"
+        text << "# Type: #{option.type}"
+        text << "# Required: #{option.required}"
+        text << "# Allowed Inputs: #{option.enum}" if option.enum
+        text << invocations.map { "#{_1}"}.join(" | ")
+
+        text.join("\n")
+      end
+
+      def invocations
+        base = [option.switch_name] + option.aliases
+        if option.type == :boolean
+          counter = option.switch_name.sub("--", "--no-")
+          base << counter
+        end
+
+        base
+      end
+
+      def readme_type
+        option.readme || ThorEnhance.configuration.autogenerated_config.readme_empty_group
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+<% ThorEnhance.configuration.autogenerated_config.readme_enums.each_with_index do |group_name, index| %>
+<% next if method_options[group_name].nil? %>
+<details <%= "open" if index == 0 %>>
+  <summary> <h3> <%= group_name.to_s.titlecase %> options </h3> </summary>
+
+```bash
+<%= method_options[group_name].map { _1.template_text }.join("\n") %>
+```
+
+</details>
+
+<% end %>

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/base.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module ThorEnhance
+  module Base
+    module BuildOption
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def build_option(name, options, scope)
+          # Method is monkey patched in order to make options aware of the klass that creates it if available
+          # This allows us to enable and disable required options based on the class
+          scope[name] = Thor::Option.new(name, {check_default_type: check_default_type}.merge!(options), self)
+        end
+      end
+    end
+
+    module AllowedKlass
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def thor_enhance_allow!
+          ThorEnhance.configuration.allowed_klasses << self
+        end
+      end
+    end
+  end
+end
+
+

data/lib/thor_enhance/command.rb

@@ -12,11 +12,6 @@ module ThorEnhance
         define_method(name) { instance_variable_get("@#{name}") }
         define_method("#{name}=") { instance_variable_set("@#{name}", _1) }
       end
-
-      # Prepend it so we can call this run method first
-      ::Thor::Command.prepend ThorEnhance::CommandHook
-
-      ::Thor::Command.include ThorEnhance::Command
     end
   end
 end

data/lib/thor_enhance/command_method.rb

@@ -8,29 +8,52 @@ module ThorEnhance
     def self.thor_enhance_injection!
       return false unless ThorEnhance::Configuration.allow_changes?
 
-      # This will dynamically define a class on the Thor module
+      # This will dynamically define class metohds on the Thor Base class
       # This allows us to add convenience helpers per method
+      # Allows us to add inline helper class functions for each desc task
       ThorEnhance.configuration.command_method_enhance.each do |name, object|
-        # This is how thor works -- at the class level using memoization
-        # Interesting approach and it works because thor should boot before everything else -- and only boots once
-        ClassMethods.define_method("#{name}") do |input|
-          value = instance_variable_get("@#{name}")
-          value ||= {}
+        # 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 = nil, *args, **kwargs|
+          return nil unless ThorEnhance.configuration.allowed?(self)
+
+          # 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
+          elsif !object[:enums].nil?
+            unless object[:enums].include?(input)
+              raise ValidationFailed, "#{@usage} recieved command method `#{name}` with incorrect enum. Received: [#{input}]. Expected: [#{object[:enums]}]"
+            end
+          elsif !object[:allowed_klasses].nil?
+            unless object[:allowed_klasses].include?(value.class)
+              raise ValidationFailed, "#{@usage} recieved command method `#{name}` with incorrect class type. Received: [#{input.class}]. Expected: #{object[:allowed_klasses]}"
+            end
+          end
+
           if object[:repeatable]
             value[@usage] ||= []
-            value[@usage] << input
+            value[@usage] << { input: input, arguments: { kwargs: kwargs, positional: args } }
           else
-            value[@usage] = input
+            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: input, arguments: { kwargs: kwargs, positional: args } }
           end
 
           instance_variable_set("@#{name}", value)
         end
       end
-
-      ::Thor.include ThorEnhance::CommandMethod
     end
 
     def self.included(base)
@@ -38,20 +61,119 @@ module ThorEnhance
     end
 
     module ClassMethods
+      THOR_ENHANCE_ENABLE = :enable
+      THOR_ENHANCE_DISABLE = :disable
+
+      def disable_thor_enhance!(&block)
+        __thor_enhance_access(type: THOR_ENHANCE_DISABLE, &block)
+      end
+
+      def enable_thor_enhance!(&block)
+        __thor_enhance_access(type: THOR_ENHANCE_ENABLE, &block)
+      end
 
       # Call all things super for it (super in thor also calls super as well)
-      # If the command exists, then add the initi
+      # If the command exists, then set the instance variable
       def method_added(meth)
-        super(meth)
+        value = super(meth)
 
-        # Skip if the we should not be creating the command
+        # Skip if the command does not exist -- Super creates the command
         if command = all_commands[meth.to_s]
-          ThorEnhance.configuration.command_method_enhance.each do |name, object|
-            # When value is not required and not present, it will not exist. Rescue and return nil
-            value = instance_variable_get("@#{name}")[meth.to_s] rescue nil
-            command.send("#{name}=", value)
+
+          if ThorEnhance.configuration.allowed?(self)
+            ThorEnhance.configuration.command_method_enhance.each do |name, object|
+
+              instance_variable = instance_variable_get("@#{name}")
+              # instance variable was correctly assigned and exists as a hash
+              if Hash === instance_variable
+                # Expected key exists in the hash
+                # This key already passed validation for type and enum
+                # Set it and move on
+                if instance_variable.key?(meth.to_s)
+                  value = instance_variable[meth.to_s]
+                  command.send("#{name}=", value)
+                  next
+                end
+              end
+
+              # At this point, the key command method was never invoked on for the `name` thor task
+              # The value is nil/unset
+
+              # If we have disabled required operations, go ahead and skip this
+              next if ::Thor.__thor_enhance_definition == ThorEnhance::CommandMethod::ClassMethods::THOR_ENHANCE_DISABLE
+
+              # Skip if the expected command method was not required
+              next unless object[:required]
+
+              # 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. " \
+                "Ensure it is added after the `desc` task is invoked"
+            end
           end
         end
+
+        value
+      end
+
+      def __thor_enhance_definition
+        @__thor_enhance_definition
+      end
+
+      def __thor_enhance_definition=(value)
+        @__thor_enhance_definition = value
+      end
+
+      def __thor_enhance_definition_stack
+        @__thor_enhance_definition_stack ||= []
+      end
+
+      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?
+
+        # capture original value. This allows us to do nested enable/disables
+        ::Thor.__thor_enhance_definition_stack << ::Thor.__thor_enhance_definition.dup
+        ::Thor.__thor_enhance_definition = type
+
+        yield
+
+        nil
+      ensure
+        # Return the state to the most recently set stack
+        ::Thor.__thor_enhance_definition = ::Thor.__thor_enhance_definition_stack.pop
       end
     end
   end