thor_enhance 0.3.0 → 0.5.0

data/lib/thor_enhance/configuration.rb

@@ -4,15 +4,13 @@ require "thor"
 
 module ThorEnhance
   class Configuration
-
-    # Order is important -- Ensure deoreacte is first
     HOOKERS = [DEPRECATE = :deprecate, HOOK = :hook]
+    ALLOWED_VALUES = [DEFAULT_ALLOWED = nil, ALLOW_ALL = :all]
 
     class << self
-      attr_accessor :allow_changes
-
       def allow_changes?(raise_error: true)
-        return true if allow_changes.nil?
+        return true unless defined?(@@allow_changes)
+        return true if @@allow_changes.nil?
 
         if raise_error
           raise BaseError, "Configuration changes are halted. Unable to change ThorEnhancements"
@@ -22,7 +20,7 @@ module ThorEnhance
       end
 
       def disallow_changes!
-        allow_changes = true
+        @@allow_changes = :prevent
       end
     end
 
@@ -32,13 +30,92 @@ module ThorEnhance
       ThorEnhance::Option.thor_enhance_injection!
       ThorEnhance::Command.thor_enhance_injection!
       ThorEnhance::CommandMethod.thor_enhance_injection!
+
+      ############
+      # Commands #
+      ############
+      # Prepend it so we can call our run method first
+      ::Thor::Command.prepend ThorEnhance::CommandHook
+      ::Thor::Command.include ThorEnhance::Command
+
+      ##################
+      # Command Method #
+      ##################
+      ::Thor.include ThorEnhance::CommandMethod
+
+      ###########
+      # Options #
+      ###########
+      # Must be prepended because we change the arity of the initializer here
+      ::Thor::Option.prepend ThorEnhance::Option
+      ::Thor.include ThorEnhance::Base::BuildOption
+
+      ####################
+      # Other Injections #
+      ####################
+      ::Thor.include ThorEnhance::Base::AllowedKlass
+
       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
 
+    def allowed_klasses
+      @klass_procs ||= []
+    end
+
+    def basename
+      @basename
+    end
+
+    def basename=(name)
+      @basename = name
+    end
+
+    def allowed
+      @allowed ||= DEFAULT_ALLOWED
+    end
+
+    def allowed=(value)
+      raise ArgumentError, "Unexpected value for `allowed =`. Given: #{value}. Expected one of #{ALLOWED_VALUES}" unless ALLOWED_VALUES.include?(value)
+
+      @allowed = value
+    end
+
+    def allowed?(klass)
+      return true if allowed == ALLOW_ALL
+      return true if allowed_klasses.include?(klass)
+
+      # At this point, allowed is false and not an includable klass -- dont allow
+      false
+    end
+
     def option_enhance
       @option_enhance ||= {
         DEPRECATE => { allowed_klasses: [Proc], behavior: :request, required: false },
@@ -47,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)
@@ -62,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"
@@ -83,10 +167,19 @@ module ThorEnhance
 
       # if enums is present and not an array
       if !enums.nil? && !enums.is_a?(Array)
-        raise ArgumentError, "Recieved enum of #{enums}. When present, it is expected to be an Array"
+        raise ArgumentError, "Recieved enums with #{enums}. When present, it is expected to be an Array"
+      end
+
+      # if allowed_klasses is present and not an array
+      if !allowed_klasses.nil? && !allowed_klasses.is_a?(Array)
+        raise ArgumentError, "Recieved allowed_klasses with #{allowed_klasses}. When present, it is expected to be an Array"
+      end
+
+      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 }
+      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,30 +5,34 @@ 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}") }
       end
-
-      ::Thor::Option.include ThorEnhance::Option
     end
 
-    def initialize(name, options = {})
-      super
+    # Monkey patched initializer
+    # Thor Option initializer only takes (name, options) as arguments
+    # Thor::Option.new is only called from `build_option` which gets monkey patched in thor_enhance/base
+    def initialize(name, options = {}, klass = nil)
+      super(name, options)
 
-      thor_enhance_definitions(options)
+      thor_enhance_definitions(options, klass)
     end
 
-    def thor_enhance_definitions(options)
+    def thor_enhance_definitions(options, klass)
+      return nil unless ThorEnhance.configuration.allowed?(klass)
+
       ThorEnhance.configuration.option_enhance.each do |name, object|
-        if options[name.to_sym].nil? && object[:required]
-          raise RequiredOption, "#{@name} does not have required option #{name}. Please add it to the option"
+        # When disabled, we do not do the required check, if present, it is still required to be a valid option otherwise
+        unless ::Thor.__thor_enhance_definition == ThorEnhance::CommandMethod::ClassMethods::THOR_ENHANCE_DISABLE
+          if options[name.to_sym].nil? && object[:required]
+            raise RequiredOption, "#{@name} does not have required option #{name}. Please add it to the option"
+          end
         end
 
         value = options[name.to_sym]
-        if value.nil? && object[:required] == false
+        if value.nil? # This can be nil here because we have already done a required check
           # no op when it is nil and not required
         elsif !object[:enums].nil?
           unless object[:enums].include?(value)

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.3.0"
+  VERSION = "0.5.0"
 end

data/lib/thor_enhance.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "active_support"
+
+require "thor_enhance/base"
 require "thor_enhance/command"
 require "thor_enhance/command_hook"
 require "thor_enhance/command_method"
@@ -9,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,9 +30,5 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "thor", "~> 1.3"
-
-  spec.add_development_dependency "pry-byebug"
-  spec.add_development_dependency "rake", "~> 12.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "simplecov", "~> 0.17.0"
+  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.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Matt Taylor
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-22 00:00:00.000000000 Z
+date: 2023-12-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -25,61 +25,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
-  name: pry-byebug
+  name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+        version: '6'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '12.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '12.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.17.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.17.0
+        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
@@ -101,20 +59,36 @@ 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
 - docs/method_option.md
 - docs/tree.md
 - examples/basic_example.md
 - examples/example_with_subcommand.md
 - examples/hooks.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/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