thor_enhance 0.4.0 → 0.5.1

data/lib/thor_enhance/autogenerate/command.rb

@@ -0,0 +1,334 @@
+# 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))
+
+      CLASS_OPTIONS_ERB = "#{File.dirname(__FILE__)}/templates/class_options.rb.erb"
+      CLASS_OPTIONS_TEMPLATE = ERB.new(File.read(CLASS_OPTIONS_ERB))
+
+      FOOTER_ERB = "#{File.dirname(__FILE__)}/templates/footer.rb.erb"
+      FOOTER_TEMPLATE = ERB.new(File.read(FOOTER_ERB))
+
+      attr_reader :root, :leaf, :name, :basename, :child_commands, :parent
+
+      def initialize(leaf:, name:, basename:, root: , parent: nil)
+        @leaf = leaf
+        @name = name
+        @basename = basename
+        @child_commands = []
+        @parent = parent
+        @root = root
+        initialize_children!
+      end
+
+      def initialize_children!
+        return unless children?
+
+        @child_commands = leaf.children.map do |name, child_leaf|
+          self.class.new(root: root, 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 = _options.group_by { _1.readme_type }
+          unless _options.empty?
+            _options.delete(ThorEnhance.configuration.autogenerated_config.readme_skip_key)
+          end
+
+          _options
+        end
+      end
+
+      def command_erb
+        @command_erb ||= begin
+          params = {
+            all_bases: all_bases,
+            basename_string: basename_string,
+            children_descriptors: children_descriptors,
+            class_options_erb: class_options_erb,
+            command: command,
+            command_source: command_source,
+            custom_headers: custom_headers,
+            default_command: default_command,
+            default_command_string: default_command_string,
+            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,
+            preferred_basename_string: preferred_basename_string,
+            title: title,
+          }
+          COMMAND_TEMPLATE.result_with_hash(params)
+        end
+      end
+
+      def command_source
+        # if children exists, it is a subcommand
+        # source location for a command does not accurately find the correct source
+        # Return nil and skip output
+        return nil if children?
+
+        file, line = leaf.base.instance_method(name).source_location
+        # This value returns the length of the root up to generated_readme
+        # This allows us to understand how many directories to remove from the local `source_location`
+        remove_length = root.split("/")[0..-2].length
+
+        # this will return the relative location of the command source line
+        relative_source = file.split("/")[remove_length..-1]
+        relative_link = "/#{relative_source.join("/")}#L#{line}"
+        "Source code for this command can be found at: [#{leaf.base.name}##{name}](#{relative_link})"
+      end
+
+      def footer_erb
+        @footer_erb ||=  begin
+          regenerate_thor_command = "#{basename} thor_enhance_autogenerate --apply"
+          FOOTER_TEMPLATE.result_with_hash({ 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 class_options_erb
+        @class_options_erb ||= begin
+          if class_options.empty?
+            nil
+          else
+            CLASS_OPTIONS_TEMPLATE.result_with_hash({ method_options_text_array: class_options.map(&:template_text) })
+          end
+        end
+      end
+
+      def class_options
+        leaf.base.class_options.map do |name, class_option|
+          class_option.hide ? nil : Option.new(name: name, option: class_option)
+        end.compact
+      end
+
+      def basename_string
+         "#{parent_basename_string} #{command.usage}"
+      end
+
+      def default_command_string
+        parent_basename_string if name == default_command
+      end
+
+      def all_bases
+        [default_command_string, basename_string].compact
+      end
+
+      def preferred_basename_string
+        default_command_string || basename_string
+      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&.dig(:input) || command.usage
+      end
+
+      def self_for_root
+        params_for_child(self)
+      end
+
+      def default_command
+        if children?
+          leaf.base.subcommand_classes[name].default_task
+        else
+          leaf.base.default_task
+        end
+      rescue
+        nil
+      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
+        default = child_commands.map { params_for_child(_1) }.select { _1[:default_command] }
+        not_default = child_commands.map { params_for_child(_1) }.select { !_1[:default_command] }
+        default + not_default
+      end
+
+      def params_for_child(child)
+        relative_link = find_iterations_back(child)
+        link = child.relative_readme_path[relative_link..-1].join("/")
+        {
+          all_bases: child.all_bases,
+          basename_string: child.basename_string,
+          default_command: child.name == default_command,
+          default_command_string: default_command_string,
+          description: child.description,
+          examples: child.drawn_out_examples(with_desc: false) || [],
+          link: link,
+          preferred_basename_string: child.preferred_basename_string,
+          title: child.title,
+        }
+      end
+
+      def find_iterations_back(child)
+        # if parent is not present, then start from 0th position
+        return 0 if child.parent.nil?
+        # When there is no children, just take the last
+        return -1 unless child.leaf.children?
+
+        # when parent exists, find out how many parents there are
+        # Return how many parents there are
+        iterations = -1
+        temp_child = child
+        while temp = temp_child.parent
+          iterations -= 1
+          temp_child = temp_child.parent
+        end
+
+        iterations
+      end
+
+      def headers
+        (command.header || []).map { _1[:arguments][:kwargs] }
+      end
+
+      def children?
+        leaf.children?
+      end
+
+      def command
+        leaf.command
+      end
+
+      def options
+        command.options.reject { |name, option| option.hide}
+      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.to_sym
+        @readme_skip_key = skip_key
+        @readme_enums = enums.map(&:to_sym) << empty_group.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,11 @@
+<% 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}\n" }.join("\n") %>
+```
+
+</details>
+<% end %>

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

@@ -0,0 +1,7 @@
+<details>
+  <summary> <h3> Class Options </h3> </summary>
+
+```bash
+<%= method_options_text_array.join("\n\n") %>
+```
+</details>

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

@@ -0,0 +1,54 @@
+# <%= title.to_s.titlecase %>
+
+<%= command_source %>
+
+## Description
+<%= command.long_description || command.description %>
+
+```bash
+# Base command for `<%= command.usage %>`
+<%= all_bases.join(" <options> \n") %> <options>
+```
+
+<%= custom_headers %>
+
+<% headers.each do |header| %>
+## <%= header[:name] %>
+<%= header[:desc]%>
+<% end %>
+<% if drawn_out_examples %>
+---
+
+## Examples
+<% drawn_out_examples.each do |ex|%>
+```bash
+<%= ex %>
+```
+<% end %>
+<% end %>
+<% if !method_options_erb.strip.empty? %>
+---
+
+<% if children_descriptors.empty? %>
+## Method Options
+
+<%= method_options_erb %>
+<% end %>
+<% else %>
+<% children_descriptors.each do |child| %>
+### [<%= child[:title]%>](<%= child[:link] %>)
+
+<%= "**Default Command** <br>" if child[:default_command] %>
+<%= child[:description] %>
+
+```bash
+<%= child[:all_bases].join(" <options> \n") %> <options>
+<%= child[:examples].map { _1 }.join("\n") %>
+```
+<% end %>
+<% end %>
+
+<%= class_options_erb %>
+---
+
+<%= footer_erb %>

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

@@ -0,0 +1,2 @@
+> AutoGenerateted by [ThorEnhance](https://github.com/matt-taylor/thor_enhance) <br>
+> Regenerate readme files with: <%= regenerate_thor_command %>

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

@@ -0,0 +1,14 @@
+# What: <%= option.description %>
+# Type: <%= option.type %>
+# Required: <%= option.required %>
+# <%= "**Allowed inputs:** #{option.enum}" if option.enum %>
+# <%= name.to_s.titlecase %>
+<%= invocations.map { "`#{_1}`"}.join(" | ") %>
+
+**What:** <%= option.description %><br>
+**Invocation:** <br>
+**Type:** <%= option.type %><br>
+**Default:** <%= option.default || "none" %><br>
+**Required:** <%= option.required %><br>
+<%= "**Allowed inputs:** #{option.enum}" if option.enum %>
+

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

@@ -0,0 +1,9 @@
+## [<%= root_child[:title]%>](<%= root_child[:link] %>)
+<%= root_child[:description] %>
+
+```bash
+# Help Command
+<%= root_child[:basename_string]%> <options>
+
+<%= root_child[:examples].map { _1 }.join("\n") %>
+```

data/lib/thor_enhance/autogenerate/validate.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ThorEnhance
+  module Autogenerate
+    module Validate
+      module_function
+
+      def validate(options:, root: nil)
+        root_result = validate_root(options: options, root: root)
+        return root_result if root_result[:status] != :pass
+
+        trunk = root_result[:trunk]
+        constant = root_result[:constant]
+
+        subcommand_result = validate_subcommand(options: options, trunk: trunk)
+        return subcommand_result if subcommand_result[:status] != :pass
+
+        trunk = subcommand_result[:trunk]
+        command_result = validate_command(options: options, trunk: trunk, constant: constant)
+        return command_result if command_result[:status] != :pass
+        command = command_result[:command]
+        { command: command, trunk: trunk, constant: constant, status: :pass }
+      end
+
+      def validate_root(options:, root:)
+        begin
+          constant = root || Object.const_get(options.root.to_s)
+        rescue NameError => e
+          msg_array = [
+            "Unable to load provided --root|-r option `#{options.root}`",
+            "Please check the spelling and ensure the klass has loaded"
+          ]
+          return { error: e, msg_array: msg_array, status: :fail }
+        end
+
+        begin
+          trunk = ThorEnhance::Tree.tree(base: constant)
+        rescue TreeFailure => e
+          msg_array = [
+            "--root|-r option is not a Thor klass.",
+            "Please ensure that the provided klass is a child of Thor"
+          ]
+          return { error: e, msg_array: msg_array, status: :fail }
+        end
+
+        { trunk: trunk, constant: constant, status: :pass }
+      end
+
+      def validate_command(options:, trunk:, constant:)
+        # Return early when command is not present in the options object
+        command = options.command
+        return { status: :pass, trunk: trunk, command: nil } if command.nil?
+
+        # Return early when command is found in the tree trunk
+        command = trunk.children[options.command] rescue trunk[options.command]
+        return { status: :pass, trunk: trunk, command: command } if command
+
+        # Command option was available but command was not found in the trunk
+        msg_array = ["Failed to find --command|-c `#{options.command}`"]
+        msg_array << "Provided root command `#{constant}`"
+        msg_array << "With Provided subcommand `#{options.subcommand}`" if options.subcommand
+        msg_array << "does not have command `#{options.command}` as a child" if options.subcommand
+
+        { msg_array: msg_array, status: :fail }
+      end
+
+      def validate_subcommand(options:, trunk:)
+        subcommands = options.subcommand
+        return { trunk: trunk, status: :pass } if subcommands.nil?
+
+        subcommands = subcommands.dup
+        subcommand = subcommands.shift
+        temp_trunk = trunk[subcommand]
+        while subcommand != nil
+          if temp_trunk.nil? || !temp_trunk.children?
+            msg_array = [
+              "Order is important with --subcommands|-s options",
+              "Provided with: #{options.subcommand}",
+              "Subcommand `#{subcommand}` does not have any child commands",
+              "Every provided subcommand must have children",
+              "If the subcommand `#{subcommand}` is meant to be a command",
+              "Pass `#{subcommand}` in as `--command|-c #{subcommand}` instead",
+            ]
+            return { msg_array: msg_array, status: :fail }
+          end
+          subcommand = subcommands.shift
+          # Will always be in the child hash at this point if subcommand exists
+          temp_trunk = temp_trunk.children[subcommand] if subcommand
+        end
+
+        { trunk: temp_trunk, subcommands: options.subcommand, status: :pass }
+      end
+    end
+  end
+end