thor_enhance 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 921021cfeb7e6d2528aa29efeeeb0b282208b08cecef9dff992dd421696f13d6
-  data.tar.gz: e43f824f5d32922d71c385722b50f31f34a7c7912eb2e6b93e1cb507e7e9f8e3
+  metadata.gz: 8bd2c2b70158e1ab7a387dddfefde9c88c27c1809278ee05608dfca0f7de6484
+  data.tar.gz: eb3ed82f1b26e2239130ff9383971c7167975ac685815e08d48de42cf7eea74c
 SHA512:
-  metadata.gz: 74090f01c075d963fbffd046cb4f3968901cb5683d8bf1f1f91a181de618e75f1ec20368fd0d04815ed76962f00c12a409c24639e03e7c80b647e6ad980ddafd
-  data.tar.gz: 2d815c6bc7957019524de7785b4678d8b10ccaa38f9d172ea383f21241cfaf80cf9601573d859140c7e4b29b9d14cdc3ce5f492c3a2bd282f8b5be33100e81eb
+  metadata.gz: 52f31daa639f2db023690b1c5b67ae261f0de382a1e03c9ad0a4801162e2ddef4127a942d8b57ad9a2dd72392a17953e63ad9ebfa913bf3e6a70d753bc668617
+  data.tar.gz: b504a6e6087671967755adf851386e0ad499d568a9f66ae561b2aee44b77a2b84c882ace9656136a10f2ed91ce77101023ee8e1ee9b2136d79f02dc428c1e63b

data/CHANGELOG.md

@@ -6,6 +6,11 @@ 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).
 
 
+## [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
+
 ## [0.3.0]
 - remove `warn` hook in favor of enriched `deprecate` hook
 - method name validation on entry

data/Gemfile

@@ -5,8 +5,9 @@ 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", require: false
+gem "ice_age"

data/Gemfile.lock

@@ -1,29 +1,45 @@
 PATH
   remote: .
   specs:
-    thor_enhance (0.3.0)
+    thor_enhance (0.5.0)
+      activesupport (>= 6)
       thor (~> 1.3)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    activesupport (7.1.2)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      mutex_m
+      tzinfo (~> 2.0)
+    base64 (0.2.0)
+    bigdecimal (3.1.4)
     byebug (11.1.3)
     coderay (1.1.3)
     concurrent-ruby (1.2.2)
+    connection_pool (2.4.1)
     diff-lcs (1.5.0)
     docile (1.4.0)
-    faker (3.2.2)
-      i18n (>= 1.8.11, < 2)
+    drb (2.2.0)
+      ruby2_keywords
     i18n (1.14.1)
       concurrent-ruby (~> 1.0)
+    ice_age (0.2.0)
     method_source (1.0.0)
+    minitest (5.20.0)
+    mutex_m (0.2.0)
     pry (0.14.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
     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,6 +55,7 @@ GEM
     rspec-support (3.12.1)
     rspec_junit_formatter (0.6.0)
       rspec-core (>= 2, < 4, != 2.12.0)
+    ruby2_keywords (0.0.5)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
@@ -46,19 +63,22 @@ GEM
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.4)
     thor (1.3.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
 
 PLATFORMS
   aarch64-linux
+  arm64-darwin-22
+  arm64-darwin-23
 
 DEPENDENCIES
-  faker
+  ice_age
   pry
   pry-byebug
-  rake (~> 12.0)
   rspec (~> 3.0)
   rspec_junit_formatter
   simplecov
   thor_enhance!
 
 BUNDLED WITH
-   2.4.22
+   2.5.1

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,35 @@ 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)
+
+### 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.
+
+ThorEnhance can automatically generate your code bases Readme for you.
+
+[Autogenerate Readme](docs/autogenerate/Readme.md)
+
+
 ### Initialization
 
+[Refere to documentation](docs/initialization.md)
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at

data/bin/thor_enhance

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+require "rubygems"
+require "bundler/setup"
+require "pry"
+
+require "thor_enhance"
+
+ThorEnhance.configure do |c|
+  c.readme_enhance!(required: true) do |r|
+    r.custom_header(:how_does_this_help, repeatable: true)
+    r.custom_header(:when_should_i_use_this, required: true, question: true)
+  end
+end
+
+require "thor_enhance/sample"
+
+begin
+  ThorEnhance::Sample.start
+rescue Interrupt => e
+  $stdout.puts "\nThanks for using Better Dependabot 👋\n"
+end

data/docs/autogenerate/Readme.md

@@ -0,0 +1,152 @@
+# Autogenerate Readme
+
+A core component of `ThorEnhance` is the ability to autogenerate Readmes for your thor commands. This allows the code and the readme to be in lockstep without the worry of the Readme getting out of date.
+
+## How does this work?
+By building on top of [Command Method Injection](../command.md) and [Method Option Injection](../method_option.md), ThorEnhance allows Readme's to get autogenerated based on the description of the command and the methods.
+
+## How to use
+
+```ruby
+# thor_enhance_config.rb
+ThorEnhance.configure do |c|
+  c.readme_enhance!
+end
+```
+
+## Default capabilities
+
+### Example Command Option
+When `readme_enhance` is enabled, by default the `example`ew command option is available on for every command.
+
+```ruby
+desc "sample", "This Sample command"
+example "sample", desc: "Basic invocation of the useless command"
+example "sample --boolean", desc: "Basic invocation of the useless command with a flag"
+method_option :boolean, type: :boolean, desc: "Just a normal boolean"
+def sample;end;
+```
+
+The example command takes signature expects:
+```ruby
+# remove basename and any submodules from command execution
+example "command execution", desc: "Description of what the command does"
+```
+
+By default, `example` is not required for every command. To make example required for every command, modify the configuration to
+```ruby
+ThorEnhance.configure do |c|
+  c.readme_enhance! do |r|
+    r.example(required: true)
+  end
+end
+```
+
+### Header Command Option
+When `readme_enhance` is enabled, by default a the `header` option is available on every command.
+
+```ruby
+desc "sample", "This Sample command"
+header name: "When should I use this?", desc: "To add additional commentary to your command"
+header name: "I can have many headers", desc: "Headers can be different per command"
+def sample;end;
+```
+
+By default, `header` is not required for every command. It is an additive command that is customizable per command
+
+### Title Command Option
+When `readme_enhance` is enabled, by default a the `title` option is available on every command.
+
+This optional command option gets used for the Readme title. Otherwise, the method name gets used
+
+```ruby
+desc "sample", "This Sample command"
+title ""
+def sample;end;
+```
+
+By default, `title` is not required for every command. To make example required for every command, modify the configuration to
+```ruby
+ThorEnhance.configure do |c|
+  c.readme_enhance! do |r|
+    r.title(required: true)
+  end
+end
+```
+
+### Readme Method Option
+
+When `readme_enhance` is enabled, by default `readme` flag is available on every option.
+
+```ruby
+desc "sample", "This Sample command"
+method_option :boolean, type: :boolean, desc: "Just a normal boolean", readme: :important
+def sample;end;
+```
+
+The Default options for the value of `:readme` are [`:important`, `:advanced`, `:skip`].
+
+All methods flagged with `:important` will show up higher in the readme. Anything labled with `:skip`, will not show up on the readme.
+
+
+By default, `readme` is not required for every method.
+
+```ruby
+# This will require all method_options to have the `readme` flag
+ThorEnhance.configure do |c|
+  c.readme_enhance! do |r|
+    r.readme(required: true)
+  end
+end
+```
+
+```ruby
+# This will options without the `readme` flag to a group of :empty on the readme
+ThorEnhance.configure do |c|
+  c.readme_enhance! do |r|
+    r.readme(empty_group: :empty)
+  end
+end
+```
+
+```ruby
+# Setting enums will override the default readme groups
+# Only these values will be allowed as readme values
+# The order of the arry determines the order the group will be ouputted in the Readme
+ThorEnhance.configure do |c|
+  c.readme_enhance! do |r|
+    r.readme(enums: ["cool", :features, "live", "here".to_sym])
+  end
+end
+```
+
+### Custom Header Command Option
+
+Custom Headers must get manually added to the configuration.
+
+```ruby
+ThorEnhance.configure do |c|
+  c.readme_enhance! do |r|
+    # how_does_this_help will be required on every command
+    r.custom_header("how_does_this_help", required: true)
+    # when_should_i_use_this is a repeatable command
+    r.custom_header("when_should_i_use_this", repeatable: true)
+    # is_this_important is now a question. On the readme, `?` gets appened to the header
+    r.custom_header("is_this_important", question: true)
+  end
+end
+```
+
+The configuration enumerated above allows the ability to do the following:
+
+
+```ruby
+desc "sample", "This Sample command"
+how_does_this_help "This command will help enable additional configuration for each command. This will get appended to the Readme in the order it appears as originally configured", tag: "h4"
+when_should_i_use_this "Use this whenever you like"
+when_should_i_use_this "Or you dont ever have to use this", tag: "h2"
+is_this_important "Yes this is imporant. It even has a custom tag", tag: 1
+def sample;end;
+```
+
+Take special not of the `tag` option on the custom header. By default, header will output as an <h2> header tag. To change, this you can use numeric `1|2|3|4` or you can use string `h[1234]`

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

@@ -49,4 +49,3 @@ EX: `publish: true` succeeds. `publish: :fail` fails.
 
 [Basic Example](../examples/basic_example.md)
 [Basic Example with Subcommand](../examples/basic_example_with_subcommand.md)
-

data/examples/basic_example.md

@@ -28,6 +28,7 @@ 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'"

data/examples/example_with_subcommand.md

@@ -28,6 +28,7 @@ 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'"
@@ -43,6 +44,8 @@ class ThorEnhancement < Thor
   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"

data/examples/hooks.md

@@ -33,8 +33,9 @@ require "thor_enhance_config"
 
 VERSION = Gem::Version.new("1.2.3")
 MAX_VERSION = Gem::Version.new("2.0.0")
-class ThorEnhancement < Thor
 
+class ThorEnhancement < Thor
+  thor_enhance_allow!
   dec "test", "Testing method"
   example "thor_cli.rb test --value 'This is rad'"
   example "thor_cli.rb test"

data/lib/thor_enhance/autogenerate/command.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+require "thor_enhance/autogenerate/option"
+require "erb"
+
+module ThorEnhance
+  module Autogenerate
+    class Command
+      COMMAND_ERB = "#{File.dirname(__FILE__)}/templates/command.rb.erb"
+      COMMAND_TEMPLATE = ERB.new(File.read(COMMAND_ERB))
+
+      AGGREGATE_OPTIONS_ERB = "#{File.dirname(__FILE__)}/templates/aggregate_options.rb.erb"
+      AGGREGATE_OPTIONS_TEMPLATE = ERB.new(File.read(AGGREGATE_OPTIONS_ERB))
+
+      FOOTER_ERB = "#{File.dirname(__FILE__)}/templates/footer.rb.erb"
+      FOOTER_TEMPLATE = ERB.new(File.read(FOOTER_ERB))
+
+      attr_reader :leaf, :name, :basename, :child_commands, :parent
+
+      def initialize(leaf:, name:, basename:, parent: nil)
+        @leaf = leaf
+        @name = name
+        @basename = basename
+        @child_commands = []
+        @parent = parent
+        initialize_children!
+      end
+
+      def initialize_children!
+        return unless children?
+
+        @child_commands = leaf.children.map do |name, child_leaf|
+          self.class.new(leaf: child_leaf, name: name, basename: basename, parent: self)
+        end
+      end
+
+      def method_options
+        @method_options ||= begin
+          _options = options.map { |name, option| Option.new(name: name, option: option) }
+
+          _options.group_by { _1.readme_type }
+        end
+      end
+
+      def command_erb
+        @command_erb ||= begin
+          params = {
+            basename_string: basename_string,
+            children_descriptors: children_descriptors,
+            command: command,
+            custom_headers: custom_headers,
+            description: description,
+            drawn_out_examples: drawn_out_examples,
+            footer_erb: footer_erb,
+            headers: headers,
+            method_options_erb: method_options_erb,
+            parent_basename_string: parent_basename_string,
+            title: title,
+          }
+          COMMAND_TEMPLATE.result_with_hash(params)
+        end
+      end
+
+      def footer_erb
+        @footer_erb ||=  begin
+          regenerate_single_command = "#{parent_basename_string} thor_enhance_autogenerate --command #{command.usage} --apply"
+          regenerate_thor_command = "#{basename} thor_enhance_autogenerate --apply"
+          FOOTER_TEMPLATE.result_with_hash({ regenerate_single_command: regenerate_single_command, regenerate_thor_command: regenerate_thor_command })
+        end
+      end
+
+      def drawn_out_examples(with_desc: true)
+        case command.example
+        when nil
+        when Array
+          command.example.map do |example|
+            value = []
+            value << "# #{example[:arguments][:kwargs][:desc]}" if with_desc
+            value << "#{parent_basename_string} #{example[:input]}"
+            value.join("\n")
+          end
+        else
+          value = []
+          value << "# #{example[:arguments][:kwargs][:desc]}" if with_desc
+          value << "#{parent_basename_string} #{example[:input]}"
+          [value.join("\n")]
+        end
+      end
+
+      def method_options_erb
+        @method_options_erb ||= AGGREGATE_OPTIONS_TEMPLATE.result_with_hash({ method_options: method_options })
+      end
+
+      def basename_string
+        "#{parent_basename_string} #{command.usage}"
+      end
+
+      def parent_basename_string
+        parent_names = [basename]
+        temp_leaf = leaf
+        while parent = temp_leaf.parent
+          temp_leaf = parent
+          parent_names << parent.command.usage
+        end
+        parent_names.join(" ")
+      end
+
+      def parent_root
+        if parent
+          # Remove the last index of parent because that will be the Readme.md file
+          # We just want the directory of the parent file
+          parent.relative_readme_path[0..-2]
+        else
+          []
+        end
+      end
+
+      def relative_readme_path
+        if children?
+          # If children exist, this is a subcommand and needs to be a root ReadMe
+          [*parent_root, name, "Readme.md"]
+        else
+          [*parent_root, "#{name}.md"]
+        end
+      end
+
+      # this only returns children and its children
+      # Call this on top most parent to retreive family tree for subcommands
+      def flatten_children
+        return [] if child_commands.empty?
+
+        child_commands.map do |child|
+          [child, child.flatten_children]
+        end.flatten
+      end
+
+      def save_self!(root:, apply:)
+        absolute_path = "#{root}/#{relative_readme_path.join("/")}"
+        pathname = Pathname.new(absolute_path)
+        FileUtils.mkdir_p(pathname.dirname)
+        if File.exist?(absolute_path)
+          content = File.read(absolute_path)
+          diff = command_erb == content ? :same : :overwite
+        else
+          diff = :new
+        end
+
+        if apply
+          File.write(absolute_path, command_erb)
+        end
+
+        { path: absolute_path, diff: diff, apply: apply, self_for_root: self_for_root }
+      end
+
+      def description
+        command.long_description || command.description
+      end
+
+      def title
+        command.title || command.usage
+      end
+
+      def self_for_root
+        params_for_child(self)
+      end
+
+      private
+
+      def custom_headers
+        ThorEnhance.configuration.autogenerated_config.custom_headers.map do |header|
+          next unless command.respond_to?(header.to_sym)
+
+          header_value = command.public_send(header.to_sym)
+          next if header_value.nil?
+          case header_value
+          when Array
+            header_value.map { header_string(_1, header) }
+          else
+            header_string(header_value, header)
+          end
+
+        end.compact.flatten.join("\n\n")
+      end
+
+      def header_string(header_value, header)
+        header_name = header.to_s.gsub(/[_-]/, " ").titlecase
+        header_name += "?" if ThorEnhance.configuration.autogenerated_config.question_headers.include?(header)
+        header_tag = decipher_header_tag(header_value[:arguments][:kwargs][:tag])
+        header_input = header_value[:input]
+        "#{header_tag} #{header_name}\n\n#{header_input}"
+      end
+
+      def decipher_header_tag(input)
+        case input
+        when String
+          begin
+            input[0..1][-1].to_i.to_s == input[0..1][-1] ? "#" * input[0..1][-1].to_i : "##"
+          rescue
+            "##"
+          end
+        when Integer
+          "#" * input
+        else
+          "##"
+        end
+      end
+
+      def children_descriptors
+        child_commands.map { params_for_child(_1) }
+      end
+
+      def params_for_child(child)
+        {
+          title: child.title,
+          link: child.relative_readme_path[-1],
+          description: child.description,
+          basename_string: child.basename_string,
+          examples: child.drawn_out_examples(with_desc: false) || [],
+        }
+      end
+
+      def headers
+        (command.header || []).map { _1[:arguments][:kwargs] }
+      end
+
+      def children?
+        leaf.children?
+      end
+
+      def command
+        leaf.command
+      end
+
+      def options
+        command.options
+      end
+    end
+  end
+end