thor_enhance 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6298d393beb8a380215c08bc6fa78c97cfd29b3d804159f97b361628b5dd4707
-  data.tar.gz: 15533218c1806a98998f3b66781a9543a22c231f60126c7b98b6a58bc5cf9cd6
+  metadata.gz: 8bd2c2b70158e1ab7a387dddfefde9c88c27c1809278ee05608dfca0f7de6484
+  data.tar.gz: eb3ed82f1b26e2239130ff9383971c7167975ac685815e08d48de42cf7eea74c
 SHA512:
-  metadata.gz: a85cdd00c9939a3f0165fdb41950c9578b56d806cd42cfff90a7058e384fcf33d46ca9f2f79eea35524f305a791a57ee1167e38818d7587fe0b5115112945c84
-  data.tar.gz: 38e8c731b8696c6abb82df29fdaabe2468e742ac69b222ac06796b989d0b6de119dfd56af82c6d2cf833522d06c2fdd0802cbb1f2fffce28b6c37c2ce62cb5d3
+  metadata.gz: 52f31daa639f2db023690b1c5b67ae261f0de382a1e03c9ad0a4801162e2ddef4127a942d8b57ad9a2dd72392a17953e63ad9ebfa913bf3e6a70d753bc668617
+  data.tar.gz: b504a6e6087671967755adf851386e0ad499d568a9f66ae561b2aee44b77a2b84c882ace9656136a10f2ed91ce77101023ee8e1ee9b2136d79f02dc428c1e63b

data/Gemfile

@@ -9,4 +9,5 @@ gem "pry"
 gem "pry-byebug"
 gem "rspec", "~> 3.0"
 gem "rspec_junit_formatter"
-gem "simplecov", "~> 0.17.0", require: false
+gem "simplecov", require: false
+gem "ice_age"

data/Gemfile.lock

@@ -1,18 +1,39 @@
 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)
-    json (2.6.3)
+    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)
@@ -34,23 +55,30 @@ GEM
     rspec-support (3.12.1)
     rspec_junit_formatter (0.6.0)
       rspec-core (>= 2, < 4, != 2.12.0)
-    simplecov (0.17.1)
+    ruby2_keywords (0.0.5)
+    simplecov (0.22.0)
       docile (~> 1.1)
-      json (>= 1.8, < 3)
-      simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.2)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    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
+  ice_age
   pry
   pry-byebug
   rspec (~> 3.0)
   rspec_junit_formatter
-  simplecov (~> 0.17.0)
+  simplecov
   thor_enhance!
 
 BUNDLED WITH
-   2.4.22
+   2.5.1

data/README.md

@@ -31,10 +31,12 @@ Command option injection is very powerful. This allows add low level documentati
 
 [Command option documentation](docs/command.md)
 
-### [Future Plans] Automatic ReadMe Generation
+### 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.
+ThorEnhance can automatically generate your code bases Readme for you.
+
+[Autogenerate Readme](docs/autogenerate/Readme.md)
 
 
 ### Initialization

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/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

data/lib/thor_enhance/autogenerate/configuration.rb

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

data/lib/thor_enhance/autogenerate/option.rb

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

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

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