thor_enhance 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b07825b4f1216de172d6ce7b7ec2052bccee6793c38ceca8b50f094bcbf3deae
-  data.tar.gz: 4458ad58f0148f4a77da324893a538e40c1def979eb26305cdb2e005afa500f7
+  metadata.gz: 6298d393beb8a380215c08bc6fa78c97cfd29b3d804159f97b361628b5dd4707
+  data.tar.gz: 15533218c1806a98998f3b66781a9543a22c231f60126c7b98b6a58bc5cf9cd6
 SHA512:
-  metadata.gz: a10dfebf316a1ad8a5c6b63a91f90b7fe95391b3f40379bbe37dcfd2e89f9cffe8d48a975fa147210a229376ec736927301eaa042def05a146960646ac0e81ba
-  data.tar.gz: 0d96db3833f42a605f7c341dd8a0a43788f1d447767df9d632a0950543bec63f05adc620b8c298b46184e44f236ac39692ecafe7cf857c091261ecda005e3031
+  metadata.gz: a85cdd00c9939a3f0165fdb41950c9578b56d806cd42cfff90a7058e384fcf33d46ca9f2f79eea35524f305a791a57ee1167e38818d7587fe0b5115112945c84
+  data.tar.gz: 38e8c731b8696c6abb82df29fdaabe2468e742ac69b222ac06796b989d0b6de119dfd56af82c6d2cf833522d06c2fdd0802cbb1f2fffce28b6c37c2ce62cb5d3

data/CHANGELOG.md

@@ -5,22 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
 
-## [0.2.0] - 2022-06-18
+## [0.4.0]
+- Enable Enhancements on a klass basis
+- Add Enable/disable blocks for enhancements to allow for onboarding new tasks
+- Fix required command options
 
-### Added
-- New feature 1
-- New feature 2
+## [0.3.0]
+- remove `warn` hook in favor of enriched `deprecate` hook
+- method name validation on entry
+- Add examples and better documentation
 
-### Changed
-- Changed feature 1
-- Changed feature 2
-
-### Removed
-- Removed feature 1
-- Removed feature 2
-
-### Fixed
-- Bug fix 1
-- Bug fix 2
+## [0.2.0]
+- Stable Release

data/Gemfile

@@ -5,8 +5,8 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in GEMNAME.gemspec
 gemspec
 
-gem 'faker'
-gem 'pry'
-gem 'rspec', '~> 3.0'
-gem 'rspec_junit_formatter'
-gem 'simplecov', require: false, group: :test
+gem "pry"
+gem "pry-byebug"
+gem "rspec", "~> 3.0"
+gem "rspec_junit_formatter"
+gem "simplecov", "~> 0.17.0", require: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    thor_enhance (0.2.0)
+    thor_enhance (0.3.0)
       thor (~> 1.3)
 
 GEM
@@ -9,13 +9,9 @@ GEM
   specs:
     byebug (11.1.3)
     coderay (1.1.3)
-    concurrent-ruby (1.2.2)
     diff-lcs (1.5.0)
     docile (1.4.0)
-    faker (3.2.2)
-      i18n (>= 1.8.11, < 2)
-    i18n (1.14.1)
-      concurrent-ruby (~> 1.0)
+    json (2.6.3)
     method_source (1.0.0)
     pry (0.14.2)
       coderay (~> 1.1)
@@ -23,7 +19,6 @@ GEM
     pry-byebug (3.10.1)
       byebug (~> 11.0)
       pry (>= 0.13, < 0.15)
-    rake (12.3.3)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
@@ -39,25 +34,22 @@ GEM
     rspec-support (3.12.1)
     rspec_junit_formatter (0.6.0)
       rspec-core (>= 2, < 4, != 2.12.0)
-    simplecov (0.22.0)
+    simplecov (0.17.1)
       docile (~> 1.1)
-      simplecov-html (~> 0.11)
-      simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.12.3)
-    simplecov_json_formatter (0.1.4)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
     thor (1.3.0)
 
 PLATFORMS
   aarch64-linux
 
 DEPENDENCIES
-  faker
   pry
   pry-byebug
-  rake (~> 12.0)
   rspec (~> 3.0)
   rspec_junit_formatter
-  simplecov
+  simplecov (~> 0.17.0)
   thor_enhance!
 
 BUNDLED WITH

data/README.md

@@ -1,5 +1,8 @@
 # ThorEnhance
 
+`ThorEnhance` enhances thor's capabiltiies. It allows customizable method options and task options.
+
+Additionally it provides hooks into each method option that allows deprecation dynamically.
 
 ## Installation
 
@@ -11,8 +14,33 @@ gem 'thor_enhance'
 
 ## Usage
 
+### Hooks
+Hooks allow you to deprecate, warn, or do some other custimizable action when a user calls thor with the specific option
+
+[Hook documentation](docs/hooks.md)
+[Hook examples](examples/hooks.md)
+
+### Method option Injection
+Method option injection allows you to enhance specific commands. When used inconjunction with [ThorEnhance::Tree](docs/tree.md), the added fields to the method options are avaialable in your code with ease.
+
+[Method option documentation](docs/method_option.md)
+
+
+### Command option Injection
+Command option injection is very powerful. This allows add low level documentation in line with the actual code.
+
+[Command option documentation](docs/command.md)
+
+### [Future Plans] Automatic ReadMe Generation
+The beauty of ThorEnhance is that it forces all your documentation to live with the code. As your code changes, the documentation naturally changes with it.
+
+In the near future, we plan to allow for automatic readme generation based on the enhanced commands provided.
+
+
 ### Initialization
 
+[Refere to documentation](docs/initialization.md)
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at

data/docs/command.md

@@ -0,0 +1,54 @@
+# Command Method Injection
+
+Command Method injection allows you to easily enrich Thor Commands with additional data.
+
+## When to use:
+This should be used when you want to enrich your command data. This data can then be retrieved by using the [ThorEnhance::Tree](tree.md) class.
+
+## How to use
+
+Additional configuration is needed prior to loading the your Thor instance
+
+```ruby
+# thor_enhance_config.rb
+ThorEnhance.configure do |c|
+  # Adds `example` method to the command
+  # Value can be anything and is a repeatable command
+  c.add_command_method_enhance "example", repeatable: true
+
+  # Adds `validate` method to the command
+  # Value must be one of :some or :thing
+  c.add_command_method_enhance "validate", enum: [:some, :thing]
+
+  # Adds `enhace` method to the command
+  # Value must be of type CustomClass
+  # It is repeatble and required
+  c.add_command_method_enhance "enhance", allowed_klasses: [CustomClass], repeatable: true, required: true
+end
+```
+The `add_option_enhance` takes the name as argument 1 followed by options.
+
+The available options are:
+
+**enums**:
+- When provided, the value of the `name` must be a value in the `enums` array
+EX: `publish: true` succeeds. `publish: :fail` fails.
+- Default: `nil`
+
+**allowed_klasses**
+- When provided, this is expected to be an array of class types the value can be.
+- Default: `nil`
+
+**required**
+- When flag is set to true, this option will be required on all `method_option` immediately. An error is raised if validation fails
+- Default: `false`
+
+**repeatable**
+- When flag is set to true, this option will allow the same command to reference the method multiple times. The value will be retreable as an Array from [ThorEnhance::Tree](tree.md) class.
+- Default: `false`
+
+# Examples:
+
+[Basic Example](../examples/basic_example.md)
+[Basic Example with Subcommand](../examples/basic_example_with_subcommand.md)
+

data/docs/hooks.md

@@ -0,0 +1,59 @@
+# Hooks:
+
+Hooks allow you to slowly deprecate options over time. There are three basic Hooks available on every method_option
+
+## Arguments:
+Both `deprecate` and `hook` are expected to be a `proc`. The input arguments will be `input, options`
+
+### Argument: Input
+The `input` argument is the first argument. It is the value that the user inputted. When there is no user input, the hook will not run.
+
+### Argument: Option
+The `option` argument is the second argument. It is the `Thor::Option` struct for that existing method. The instance will have all ThorEnhance methods available.
+
+## Deprecate:
+The `deprecate` hook is available on every `method_option`. It expects a `Proc` class. The returned value from the proc is expected as either an Hash or a String.
+
+This hook should be used when you want to either immediately depreacte a method or over time deprecate a command while migrating to a new command. The decision to raise or warn is dynamic in real time.
+
+### When returned an String
+If the method option is provided, it will raise `ThorEnhance::OptionDeprecated` every time
+
+### When returned a Hash
+**hash[:raise]**: Expected a boolean value on weather to raise or warn. When true, it will raise `ThorEnhance::OptionDeprecated`. When false it will send WARNING to console
+**hash[:warn]**: Console message used when `:raise` is false. Does not output when `:raise` is true
+**hash[:msg]**: Message for both raise and warn. This should a short message on how to migrate to new command or syntax
+
+```ruby
+# When provided `--value1 "string"`:
+# This will raise `ThorEnhance::OptionDeprecated` with a message that looks like:
+# Passing value for option --value1 is deprecated. Provided `string`. Please migrate to `--value4`
+method_option :value1, type: :string, deprecate: ->(input, option) { "Please migrate to `--value4`" }
+
+# When provided `--value2 "string"` and deprecated criteria is not met:
+# This will send a WARNING message to the console. It will resemble:
+# Passing value for option --value1 is deprecated. Provided `string`. Please migrate to `--value4`
+method_option :value2, type: :string, deprecate: ->(input, option) { { raise: Date.today > Date.today, warn: "This option will deprecate after #{Date.today}", msg: "Please migrate to --value4"} }
+
+# When provided `--value3 "string"` and deprecated criteria is:
+# This will raise `ThorEnhance::OptionDeprecated` with a message that looks like:
+# Passing value for option --value3 is deprecated. Provided `string`. Please migrate to `--value4`
+method_option :value3, type: :string, deprecate: ->(input, option) { { raise: true, warn: "This option will deprecate after #{Date.today}", msg: "Please migrate to --value4"} }
+```
+
+## Hook
+The `hook` hook is available on every `method_option`. It expects a `Proc` class. No return value is expected. When the input is provided, custom code can get executed
+
+```ruby
+# When provided `--value1 "string"`:
+# This will raise `ThorEnhance::OptionDeprecated` with a message that looks like:
+# Passing value for option --value1 is deprecated. Provided `string`. Please migrate to `--value4`
+method_option :value1, type: :string, hook: ->(input, option) { Kernel.puts "#{input} is a good choice for #{option.name}" }
+```
+
+---
+
+# Examples
+
+For examples, [please navigate here](../examples/hooks.md)
+

data/docs/initialization.md

@@ -0,0 +1,62 @@
+# Initialize ThorEnhance
+
+ThorEnhance requires initialization prior to your custom Thor classes loading.
+
+## How to initialize
+
+ThorEnhance provides several ways to enforce options on downstream classes.
+
+### Preferred route
+When creating the Thor Class, set `thor_enhance_allow!` at the top of the class. This will allow `ThorEnhance` to know that what class to allow and enforce enhancments for
+```ruby
+class Enhance < Thor
+  thor_enhance_allow!
+  ...
+end
+```
+
+If you have methods are are not ready to abide by the enformence, No worries. Simple use the enable/disable wrappers.
+
+```ruby
+class Enhance < Thor
+  thor_enhance_allow!
+
+  disable_thor_enhance! do
+    desc task1 # No enhancements are required
+    def task1;end;
+
+    enable_thor_enhance! do
+      desc task2 # All enhancements are required
+      def task2;end;
+    end
+  end
+
+  desc task3 # All enhancements are required
+  def task3;end;
+end
+```
+
+
+### Alternate route
+When initializing the `ThorEnhance` gem in the configuration, add the following code:
+```ruby
+ThorEnhance.configure do |c|
+  ...
+  c.allowed = :all
+  ...
+end
+```
+
+The above code will enforce all Thor classes have required ThorEnhanced enhancements.
+
+**Caution**: Other gems that utilize thor like `Rake` `RSpec` `Rails` may fail on boot when utilizing the `:all` option. Use with caution
+
+
+
+[Method Options](method_option.md)
+[Command Options](command.md)
+
+## Example
+
+[Basic Example](../examples/basic_example.md)
+[Basic Example with Subcommand](../examples/basic_example_with_subcommand.md)

data/docs/method_option.md

@@ -0,0 +1,51 @@
+# Method Option Injection
+
+Method option injection allows you to easily add additional flags to the `method_option` for commands. You can set them as required for every option. You can even set allowable values or allowable classes
+
+## When to use:
+This should be used when you want to enrich your command data. This data can then be retrieved by using the [ThorEnhance::Tree](tree.md) class.
+
+## How to use
+
+Additional configuration is needed prior to loading the your Thor instance
+
+```ruby
+# thor_enhance_config.rb
+ThorEnhance.configure do |c|
+  # Adds `classify` method to the option class
+  # Value of classify must be one of the enums
+  # It is not a required field on every method
+  c.add_option_enhance "classify", allowed_klasses: [String, Symbol, NilClass], required: false
+
+  # Adds `publish` method to the option
+  # Value of classify must be one of the enums
+  # It is a required field on every option
+  c.add_option_enhance :publish, enums: [true, false], required: true
+
+  # Adds `avoid method to the option
+  # Value is not restricted to any type or enum
+  # Not a required field
+  c.add_option_enhance :avoid
+end
+```
+The `add_option_enhance` takes the name as argument 1 followed by options.
+
+The available options are:
+
+**enums**:
+- When provided, the value of the `name` must be a value in the `enums` array
+EX: `publish: true` succeeds. `publish: :fail` fails.
+- Default: `nil`
+
+**allowed_klasses**
+- When provided, this is expected to be an array of class types the value can be.
+- Default: `nil`
+
+**required**
+- When flag is set to true, this option will be required on all `method_option` immediately. An error is raised if validation fails
+- Default: `false`
+
+# Examples:
+
+[Basic Example](../examples/basic_example.md)
+[Basic Example with Subcommand](../examples/basic_example_with_subcommand.md)

data/docs/tree.md

@@ -0,0 +1,42 @@
+# ThorEnhance::Tree
+
+The thor tree is a powerful tool to do introspection on all Thor commands within a repo.
+
+## How to use:
+
+MyTestClass definitiona can be found in [spec_helper.rb](../spec/spec_helper.rb)
+
+```ruby
+require "thor_enhance"
+
+tree = ThorEnhance::Tree.tree(base: MyTestClass)
+
+# View all commands on parent tree:
+tree.children.map(&:command)
+
+# View all commands including subcommands
+
+def iterate_base(base:)
+  tree.map do |name, object|
+    if object.children?
+      iterate_base(base: object)
+    else
+      object.command
+    end
+  end.flatten
+end
+
+iterate_base(base: tree)
+
+# View specific command
+command = tree["test_meth"].command
+
+# View specific sub command
+sub_command_innard = tree["sub"].children["innard"].command
+
+# View Options on specific command
+command.options
+
+# View specific Option on specific command
+sub_command_innard.options[:t]
+```

data/examples/basic_example.md

@@ -0,0 +1,48 @@
+```ruby
+# thor_enhance_config.rb
+
+require "thor_enhance"
+
+ThorEnhance.configure do |c|
+  # Adds `classify` method to the option class
+  # Value of classify must be one of the enums
+  # It is not a required field on every method
+  c.add_option_enhance "classify", enums: [:allowed, :future, :existing], required: false
+
+  # Adds `publish` method to the option
+  # Value of classify must be one of the enums
+  # It is a required field on every option
+  c.add_option_enhance :publish, enums: [true, false], required: true
+
+  # Adds `example` method to the command
+  # Value can be anything and is a repeatable command
+  c.add_command_method_enhance "example", repeatable: true
+end
+```
+
+```ruby
+# thor_cli.rb
+
+require "rubygems"
+require "bundler/setup"
+require "thor_enhance_config"
+
+class ThorEnhancement < Thor
+  thor_enhance_allow!
+
+  dec "test", "Testing method"
+  example "thor_cli.rb test --value 'This is rad'"
+  example "thor_cli.rb test"
+  method_option :value, type: :string, publish: true
+  def test
+    command = ThorEnhance::Tree.tree(base: self.class)["test"].command
+    # example was set as `repeatable` so it gets returned as an array
+    command.example.each { puts _1 }
+
+    command.options[:value].publish == true
+    command.options[:value].classify == nil
+  end
+end
+
+ThorEnhancement.start
+```

data/examples/example_with_subcommand.md

@@ -0,0 +1,76 @@
+```ruby
+# thor_enhance_config.rb
+
+require "thor_enhance"
+
+ThorEnhance.configure do |c|
+  # Adds `classify` method to the option class
+  # Value of classify must be one of the enums
+  # It is not a required field on every method
+  c.add_option_enhance :classify, allowed_klasses: [Symbol], required: false
+
+  # Adds `publish` method to the option
+  # Value of classify must be one of the enums
+  # It is a required field on every option
+  c.add_option_enhance "publish", allowed_klasses: [TrueClass, FalseClass], required: true
+
+  # Adds `example` method to the command
+  # Value can be anything and is a repeatable command
+  c.add_command_method_enhance :example, repeatable: true
+end
+```
+
+```ruby
+# thor_cli.rb
+
+require "rubygems"
+require "bundler/setup"
+require "thor_enhance_config"
+
+class ThorEnhancement < Thor
+  thor_enhance_allow!
+
+  dec "test", "Testing method"
+  example "thor_cli.rb test --value 'This is rad'"
+  example "thor_cli.rb test"
+  method_option :value, type: :string, publish: true
+  def test
+    command = ThorEnhance::Tree.tree(base: self.class)["test"].command
+    # example was set as `repeatable` so it gets returned as an array
+    command.example.each { puts _1 }
+
+    command.options[:value].publish == true
+    command.options[:value].classify == nil
+  end
+
+  class SubCommand < Thor
+    thor_enhance_allow!
+
+    desc "sub_command", "Command for SubCommand"
+    example "bin/thor sub_command innard -t something -s better"
+    example "bin/thor sub_command innard -s better"
+    example "bin/thor sub_command innard"
+
+    method_option :t, type: :string, classify: :allowed, publish: true
+    method_option :s, type: :string, classify: :erase, publish: false
+    def sub_command
+      parent = ThorEnhance::Tree.tree(base: self.class)["sub"]
+      parent.example.each { puts _1 } # 1 example
+
+      command = parent.children["sub_command"].command
+      command.children? == false
+
+      command.example.each { puts _1 } # 3 examples
+
+      command.options[:t].publish == true
+      command.options[:t].classify == :allowed
+    end
+  end
+
+  desc "sub", "Submodule command line"
+  example "bin/thor sub ***"
+  subcommand "sub", SubCommand
+end
+
+ThorEnhancement.start
+```

data/examples/hooks.md

@@ -0,0 +1,58 @@
+# Hook Examples
+
+For more information on how to use hooks, [view documentation here](../docs/hooks.md)
+
+```ruby
+# thor_enhance_config.rb
+
+require "thor_enhance"
+
+ThorEnhance.configure do |c|
+  # Adds `classify` method to the option class
+  # Value of classify must be one of the enums
+  # It is not a required field on every method
+  c.add_option_enhance "classify", enums: [:allowed, :future, :existing], required: false
+
+  # Adds `publish` method to the option
+  # Value of classify must be one of the enums
+  # It is a required field on every option
+  c.add_option_enhance :publish, enums: [true, false], required: true
+
+  # Adds `example` method to the command
+  # Value can be anything and is a repeatable command
+  c.add_command_method_enhance "example", repeatable: true
+end
+```
+
+```ruby
+# thor_cli.rb
+
+require "rubygems"
+require "bundler/setup"
+require "thor_enhance_config"
+
+VERSION = Gem::Version.new("1.2.3")
+MAX_VERSION = Gem::Version.new("2.0.0")
+
+class ThorEnhancement < Thor
+  thor_enhance_allow!
+  dec "test", "Testing method"
+  example "thor_cli.rb test --value 'This is rad'"
+  example "thor_cli.rb test"
+  method_option :value, type: :string, publish: true, deprecate: ->(input, option) { { raise: VERSION > MAX_VERSION, warn: "This option will deprecate with version #{MAX_VERSION}", msg: "Please migrate to --value4"} }
+
+  # Deprecate hook
+  method_option :option, type: :string, publish: false,
+  method_option :test, type: :string, publish: false,
+  def test
+    command = ThorEnhance::Tree.tree(base: self.class)["test"].command
+    # example was set as `repeatable` so it gets returned as an array
+    command.example.each { puts _1 }
+
+    command.options[:value].publish == true
+    command.options[:value].classify == nil
+  end
+end
+
+ThorEnhancement.start
+```

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_hook.rb

@@ -23,13 +23,23 @@ module ThorEnhance
           input_tags = [option.switch_name] + option.aliases
           next unless input_tags.any? { raw_args.include?(_1) }
 
-          proc_value = proclamation.(given_value)
+          proc_value = proclamation.(given_value, option)
 
-          case object[:behavior]
-          when :raise
-            raise ThorEnhance::OptionDeprecated, "Passing value for option #{option.switch_name} is deprecated. Provided `#{given_value}`. #{proc_value}"
-          when :warn
-            Kernel.warn("WARNING: Provided `#{given_value}` for option #{option.switch_name}. #{proc_value}")
+          if object[:behavior] == :request
+            if Hash === proc_value && proc_value.keys.sort == [:raise, :warn, :msg].sort
+              warn_msg = proc_value[:warn].to_s
+              msg = proc_value[:msg].to_s
+              if proc_value[:raise]
+                raise ThorEnhance::OptionDeprecated, "Passing value for option #{option.switch_name} is deprecated. " \
+                  "Provided `#{given_value}`. #{proc_value[:msg]}"
+              else
+                Kernel.warn("WARNING: Provided `#{given_value}` for option #{option.switch_name}. " \
+                  "#{proc_value[:warn]}. #{proc_value[:msg]}")
+              end
+            else
+              raise ThorEnhance::OptionDeprecated, "Passing value for option #{option.switch_name} is deprecated. " \
+                "Provided `#{given_value}`. #{proc_value}"
+            end
           end
         end
       end

data/lib/thor_enhance/command_method.rb

@@ -8,29 +8,50 @@ 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
+        # 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|
+          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
+
+          # 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
           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
           end
 
           instance_variable_set("@#{name}", value)
         end
       end
-
-      ::Thor.include ThorEnhance::CommandMethod
     end
 
     def self.included(base)
@@ -38,20 +59,91 @@ 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)
+
+              # 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_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

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, WARNING = :warn, HOOK = :hook]
+    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,6 +30,31 @@ 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
 
@@ -39,10 +62,31 @@ module ThorEnhance
       @command_method_enhance ||= {}
     end
 
+    def allowed_klasses
+      @klass_procs ||= []
+    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 ||= {
-        WARNING => { allowed_klasses: [Proc], behavior: :warn, required: false },
-        DEPRECATE => { allowed_klasses: [Proc], behavior: :raise, required: false },
+        DEPRECATE => { allowed_klasses: [Proc], behavior: :request, required: false },
         HOOK => { allowed_klasses: [Proc], behavior: nil, required: false },
       }
     end
@@ -64,6 +108,16 @@ module ThorEnhance
     private
 
     def add_to_variable(storage, methods, name, allowed_klasses, enums, required, repeatable = 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"
+      end
+
+      # If name contains characters other than upper or lower case letters and _ FAIL
+      unless name =~ /^[A-Za-z_]+$/
+        raise ArgumentError, "Invalid name received. Received [#{name}] does not match /^[A-Za-z_]+$/."
+      end
+
       if methods.include?(name.to_sym)
         raise OptionNotAllowed, "[#{name}] is not allowed as an enhancement"
       end
@@ -74,7 +128,12 @@ 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
 
       storage[name.to_sym] = { allowed_klasses: allowed_klasses, enums: enums, required: required, repeatable: repeatable }

data/lib/thor_enhance/option.rb

@@ -11,24 +11,30 @@ module ThorEnhance
       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/version.rb

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

data/lib/thor_enhance.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "thor_enhance/base"
 require "thor_enhance/command"
 require "thor_enhance/command_hook"
 require "thor_enhance/command_method"

data/thor_enhance.gemspec

@@ -30,9 +30,4 @@ 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"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: thor_enhance
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Matt Taylor
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-21 00:00:00.000000000 Z
+date: 2023-11-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -24,62 +24,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
-- !ruby/object:Gem::Dependency
-  name: pry-byebug
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  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
 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
@@ -102,7 +46,16 @@ files:
 - bin/console
 - bin/setup
 - docker-compose.yml
+- 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/base.rb
 - lib/thor_enhance/command.rb
 - lib/thor_enhance/command_hook.rb
 - lib/thor_enhance/command_method.rb