thor_enhance 0.4.0 → 0.5.1

data/lib/thor_enhance/autogenerate.rb

@@ -0,0 +1,87 @@
+# 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|
+        Command.new(name: name, leaf: leaf, basename: basename, root: options.generated_root)
+      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
+      children_result = save_generated_readmes!(commands: youthful_kids, generated_root: options.generated_root, apply: options.apply)
+      return children_result if children_result[:status] != :pass
+
+      root_result = save_generated_readmes!(commands: command_structure, generated_root: options.generated_root, apply: options.apply)
+      return root_result if root_result[:status] != :pass
+
+      self_for_roots = root_result[:saved_status].collect { _1[:self_for_root] }
+      # Add saved results from the children
+      root_result[:saved_status] += children_result[:saved_status]
+      # Add root savior saved results
+      root_result[:saved_status] << root_savior!(basename: basename, apply: options.apply, full_root: root_result[:full_root], self_for_roots: self_for_roots)
+
+      root_result
+    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
+
+      { status: :pass, full_root: full_root, saved_status: saved_status }
+    end
+
+    def root_savior!(basename:, full_root:, self_for_roots:, apply:)
+      full_path = "#{full_root}/Readme.md"
+      regenerate_thor_command = "#{basename} thor_enhance_autogenerate --apply"
+      footer = ThorEnhance::Autogenerate::Command::FOOTER_TEMPLATE.result_with_hash({ regenerate_thor_command: regenerate_thor_command })
+
+      root_erb_result = (self_for_roots.map do |root_child|
+        ROOT_TEMPLATE.result_with_hash({ root_child: root_child })
+      end + [footer]).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)
@@ -98,7 +100,10 @@ module ThorEnhance
               # 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
+              if ::Thor.__thor_enhance_definition == ThorEnhance::CommandMethod::ClassMethods::THOR_ENHANCE_DISABLE
+                ::Thor.__thor_enhance_definition_ignored << meth.to_sym
+                next
+              end
 
               # Skip if the expected command method was not required
               next unless object[:required]
@@ -106,6 +111,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. " \
@@ -129,8 +138,35 @@ module ThorEnhance
         @__thor_enhance_definition_stack ||= []
       end
 
+      def __thor_enhance_definition_ignored
+        @__thor_enhance_definition_ignored ||= []
+      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?
 

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,58 @@
+# 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."
+      title "Innard command for Subtask Subcommand"
+      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"
+    title "Subcommand for sample class"
+    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
+    method_option :count, type: :numeric, enum: [1,2,3,4,5], default: 1, desc: "How many times to output text", readme: :important
+    def sample
+      options[:count].times { Kernel.puts "Executed Sample method" }
+    end
+
+    desc "autobots", "Command outputs what Optimus prime is thniking"
+    when_should_i_use_this <<~README
+    Do you ever feel angry about how powerful the Decepticons are compared to the Autobots? It seems unfair.
+    Trust...The autobots agree.
+    README
+    example "sample", desc: "yo yo ma"
+    example "sample --boolean", desc: "yo yo ma"
+    method_option :bumble, aliases: "-b", type: :boolean, desc: "Enable bumblee bee flag", readme: :important
+    def autobots
+      Kernel.puts "Optimus prime requires megatron must be eliminated"
+      if options.bumble
+        Kernel.puts "Bumble bee agrees"
+      end
+    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.1"
 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: thor_enhance
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Matt Taylor
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-26 00:00:00.000000000 Z
+date: 2023-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
 description: Have you ever wanted your thor commands to tell a story of what they
   are? Or have you ever wanted to deprecate an option over time easily? ThorEnhance
   allows to to annote methods and commands in a human readable way
@@ -45,7 +59,9 @@ files:
 - README.md
 - bin/console
 - bin/setup
+- bin/thor_enhance
 - docker-compose.yml
+- docs/autogenerate/Readme.md
 - docs/command.md
 - docs/hooks.md
 - docs/initialization.md
@@ -54,13 +70,31 @@ files:
 - examples/basic_example.md
 - examples/example_with_subcommand.md
 - examples/hooks.md
+- generated_readme/commands/Readme.md
+- generated_readme/commands/autobots.md
+- generated_readme/commands/sample.md
+- generated_readme/commands/sub/Readme.md
+- generated_readme/commands/sub/innard.md
 - lib/thor_enhance.rb
+- lib/thor_enhance/autogenerate.rb
+- lib/thor_enhance/autogenerate/command.rb
+- lib/thor_enhance/autogenerate/configuration.rb
+- lib/thor_enhance/autogenerate/option.rb
+- lib/thor_enhance/autogenerate/templates/aggregate_options.rb.erb
+- lib/thor_enhance/autogenerate/templates/class_options.rb.erb
+- lib/thor_enhance/autogenerate/templates/command.rb.erb
+- lib/thor_enhance/autogenerate/templates/footer.rb.erb
+- lib/thor_enhance/autogenerate/templates/option.rb.erb
+- lib/thor_enhance/autogenerate/templates/root.rb.erb
+- lib/thor_enhance/autogenerate/validate.rb
 - lib/thor_enhance/base.rb
 - lib/thor_enhance/command.rb
 - lib/thor_enhance/command_hook.rb
 - lib/thor_enhance/command_method.rb
 - lib/thor_enhance/configuration.rb
 - lib/thor_enhance/option.rb
+- lib/thor_enhance/sample.rb
+- lib/thor_enhance/thor_auto_generate_inject.rb
 - lib/thor_enhance/tree.rb
 - lib/thor_enhance/version.rb
 - thor_enhance.gemspec