docscribe 1.4.1 → 1.5.0

data/lib/docscribe/cli/generate.rb

@@ -14,91 +14,92 @@ module Docscribe
     module Generate
       PLUGIN_TYPES = %w[tag collector].freeze
 
+      NEXT_STEPS_TEMPLATE = <<~TEXT
+        Next steps:
+          1. Open %<path>s and implement the plugin logic.
+             %<hint>s
+
+        2. Register the plugin in your docscribe_plugins.rb:
+
+               require_relative '%<require_path>s'
+               Docscribe::Plugin::Registry.register(%<base_name>s.new)
+
+        3. Add the file to docscribe.yml:
+
+               plugins:
+                 require:
+                   - ./docscribe_plugins
+      TEXT
+
       class << self
         # Run the `generate` subcommand.
         #
-        # @param [Array<String>] argv
-        # @raise [OptionParser::InvalidOption]
+        # @param [Array<String>] argv command line arguments
         # @return [Integer] exit code
         def run(argv)
-          opts = {
-            output: nil,
-            stdout: false
-          }
-
-          parser = OptionParser.new do |o|
-            o.banner = <<~TEXT
-              Usage: docscribe generate <type> <PluginName> [options]
-
-              Types:
-                tag         Generate a TagPlugin skeleton
-                collector   Generate a CollectorPlugin skeleton
-
-              Options:
-            TEXT
-
-            o.on('--output DIR', 'Directory to write the plugin file (default: .)') { |v| opts[:output] = v }
-            o.on('--stdout', 'Print the generated plugin to STDOUT instead of writing a file') { opts[:stdout] = true }
-            o.on('-h', '--help', 'Show this help') do
-              puts o
-              return 0
-            end
-          end
+          opts, parser = parse_generate_options(argv)
+          return 0 if opts[:help]
+
+          plugin_type, class_name = extract_generate_args(argv)
+          result = validate_generate_args(plugin_type, class_name, parser)
+          return result if result
+
+          content = render(plugin_type, class_name)
+          dispatch_output(content, plugin_type, class_name, opts)
+        end
+
+        private
+
+        # Parse options for the generate subcommand.
+        #
+        # @private
+        # @param [Array<String>] argv command line arguments
+        # @raise [OptionParser::InvalidOption]
+        # @return [(Hash<Symbol, Object>, OptionParser)]
+        def parse_generate_options(argv)
+          opts = { output: nil, stdout: false, help: false }
+          parser = build_option_parser(opts)
 
           begin
             parser.parse!(argv)
           rescue OptionParser::InvalidOption => e
             warn e.message
             warn parser
-            return 1
-          end
-
-          plugin_type = argv.shift
-          class_name  = argv.shift
-
-          unless plugin_type && class_name
-            warn 'Error: both <type> and <PluginName> are required.'
-            warn parser
-            return 1
-          end
-
-          unless PLUGIN_TYPES.include?(plugin_type)
-            warn "Error: unknown type #{plugin_type.inspect}. Must be one of: #{PLUGIN_TYPES.join(', ')}."
-            return 1
           end
 
-          unless valid_constant?(class_name)
-            warn "Error: #{class_name.inspect} is not a valid Ruby constant name."
-            return 1
-          end
-
-          content = render(plugin_type, class_name)
-
-          if opts[:stdout]
-            puts content
-            return 0
-          end
-
-          write_plugin(content, plugin_type: plugin_type, class_name: class_name, output_dir: opts[:output] || '.')
+          [opts, parser]
         end
 
-        private
+        # Extract plugin_type and class_name from remaining argv.
+        #
+        # @private
+        # @param [Array<String>] argv command line arguments
+        # @return [(String?, String?)]
+        def extract_generate_args(argv)
+          [argv.shift, argv.shift]
+        end
 
-        # Check whether a string is a valid Ruby constant name.
+        # Validate generate arguments and return exit code on failure.
         #
         # @private
-        # @param [String] str
-        # @return [Boolean]
-        def valid_constant?(str)
-          !!(str =~ /\A[A-Z][A-Za-z0-9]*(?:::[A-Z][A-Za-z0-9]*)*\z/)
+        # @param [String?] plugin_type 'tag' or 'collector'
+        # @param [String?] class_name CamelCase plugin class name
+        # @param [OptionParser] parser option parser instance
+        # @return [Integer, nil] exit code or nil if valid
+        def validate_generate_args(plugin_type, class_name, parser)
+          return 1 unless args_provided?(plugin_type, class_name, parser)
+          return 1 unless known_type?(plugin_type)
+          return 1 unless valid_name?(class_name)
+
+          nil
         end
 
         # Render plugin boilerplate for the given type and class name.
         #
         # @private
-        # @param [String] plugin_type 'tag' or 'collector'
-        # @param [String] class_name  CamelCase plugin class name
-        # @return [String]
+        # @param [String?] plugin_type 'tag' or 'collector'
+        # @param [String?] class_name CamelCase plugin class name
+        # @return [String?]
         def render(plugin_type, class_name)
           case plugin_type
           when 'tag'       then tag_template(class_name)
@@ -106,70 +107,10 @@ module Docscribe
           end
         end
 
-        # Write the generated content to a file.
-        #
-        # @private
-        # @param [String] content
-        # @param [String] plugin_type
-        # @param [String] class_name
-        # @param [String] output_dir
-        # @return [Integer] exit code
-        def write_plugin(content, plugin_type:, class_name:, output_dir:)
-          filename = "#{underscore(class_name)}.rb"
-          path     = File.join(output_dir, filename)
-
-          if File.exist?(path)
-            warn "Error: #{path} already exists. Remove it first or use --stdout."
-            return 1
-          end
-
-          require 'fileutils'
-          FileUtils.mkdir_p(output_dir)
-          File.write(path, content)
-          puts "Created: #{path}"
-          puts
-          puts next_steps(plugin_type, path)
-          0
-        end
-
-        # Print registration instructions after file creation.
-        #
-        # @private
-        # @param [String] plugin_type
-        # @param [String] path
-        # @return [String]
-        def next_steps(plugin_type, path)
-          base_name = File.basename(path, '.rb').split('_').map(&:capitalize).join
-
-          implement_hint = case plugin_type
-                           when 'tag'
-                             'Implement the #call method to return Array<Docscribe::Plugin::Tag>.'
-                           when 'collector'
-                             'Implement the #collect method to return Array<{anchor_node:, doc:}>.'
-                           end
-
-          <<~TEXT
-            Next steps:
-              1. Open #{path} and implement the plugin logic.
-                 #{implement_hint}
-
-              2. Register the plugin in your docscribe_plugins.rb:
-
-                   require_relative '#{path.delete_suffix('.rb')}'
-                   Docscribe::Plugin::Registry.register(#{base_name}.new)
-
-              3. Add the file to docscribe.yml:
-
-                   plugins:
-                     require:
-                       - ./docscribe_plugins
-          TEXT
-        end
-
         # Template for a TagPlugin.
         #
         # @private
-        # @param [String] class_name
+        # @param [String?] class_name CamelCase plugin class name
         # @return [String]
         def tag_template(class_name)
           <<~RUBY
@@ -227,7 +168,7 @@ module Docscribe
         # Template for a CollectorPlugin.
         #
         # @private
-        # @param [String] class_name
+        # @param [String?] class_name CamelCase plugin class name
         # @return [String]
         def collector_template(class_name)
           <<~RUBY
@@ -292,10 +233,166 @@ module Docscribe
           RUBY
         end
 
+        # Write generated plugin to a file or print to STDOUT based on options.
+        #
+        # @private
+        # @param [String?] content generated plugin source code
+        # @param [String?] plugin_type 'tag' or 'collector'
+        # @param [String?] class_name CamelCase plugin class name
+        # @param [Hash<Symbol, Object>] opts parsed options hash
+        # @return [Integer] exit code
+        def dispatch_output(content, plugin_type, class_name, opts)
+          if opts[:stdout]
+            puts content
+            return 0
+          end
+
+          write_plugin(content, plugin_type: plugin_type, class_name: class_name, output_dir: opts[:output] || '.')
+        end
+
+        # Write the generated content to a file.
+        #
+        # @private
+        # @param [String?] content file content to write
+        # @param [String?] plugin_type 'tag' or 'collector'
+        # @param [String?] class_name CamelCase plugin class name
+        # @param [String?] output_dir output directory path
+        # @return [Integer] exit code
+        def write_plugin(content, plugin_type:, class_name:, output_dir:)
+          path = plugin_path(class_name, output_dir)
+
+          return 1 if file_exists?(path)
+
+          write_to_file(output_dir, path, content)
+          print_created(plugin_type, path)
+          0
+        end
+
+        # Build the OptionParser for the generate subcommand.
+        #
+        # @private
+        # @param [Hash<Symbol, Object>] opts mutable parsed options hash
+        # @return [OptionParser]
+        def build_option_parser(opts)
+          OptionParser.new do |opt|
+            opt.banner = parser_banner
+            register_output_option(opt, opts)
+            register_stdout_option(opt, opts)
+            register_help_option(opt, opts)
+          end
+        end
+
+        # Return the usage banner for the generate subcommand parser.
+        #
+        # @private
+        # @return [String]
+        def parser_banner
+          <<~TEXT
+            Usage: docscribe generate <type> <PluginName> [options]
+
+            Types:
+              tag         Generate a TagPlugin skeleton
+              collector   Generate a CollectorPlugin skeleton
+
+            Options:
+          TEXT
+        end
+
+        # Register the --output option on the OptionParser.
+        #
+        # @private
+        # @param [OptionParser] opt option parser instance
+        # @param [Hash<Symbol, Object>] opts mutable parsed options hash
+        # @return [void]
+        def register_output_option(opt, opts)
+          opt.on('--output DIR', 'Directory to write the plugin file (default: .)') { |v| opts[:output] = v }
+        end
+
+        # Register the --stdout option on the OptionParser.
+        #
+        # @private
+        # @param [OptionParser] opt option parser instance
+        # @param [Hash<Symbol, Object>] opts mutable parsed options hash
+        # @return [void]
+        def register_stdout_option(opt, opts)
+          opt.on('--stdout', 'Print the generated plugin to STDOUT instead of writing a file') { opts[:stdout] = true }
+        end
+
+        # Register the -h/--help option on the OptionParser.
+        #
+        # @private
+        # @param [OptionParser] opt option parser instance
+        # @param [Hash<Symbol, Object>] opts mutable parsed options hash
+        # @return [void]
+        def register_help_option(opt, opts)
+          opt.on('-h', '--help', 'Show this help') do
+            puts opt
+            opts[:help] = true
+          end
+        end
+
+        # Validate that both plugin_type and class_name arguments were provided.
+        #
+        # @private
+        # @param [String?] plugin_type plugin type argument
+        # @param [String?] class_name plugin class name argument
+        # @param [OptionParser] parser option parser instance
+        # @return [Boolean]
+        def args_provided?(plugin_type, class_name, parser)
+          return true if plugin_type && class_name
+
+          warn 'Error: both <type> and <PluginName> are required.'
+          warn parser
+          false
+        end
+
+        # Validate that the plugin type is one of the recognized types.
+        #
+        # @private
+        # @param [String?] plugin_type plugin type to validate
+        # @return [Boolean]
+        def known_type?(plugin_type)
+          return true if PLUGIN_TYPES.include?(plugin_type)
+
+          warn "Error: unknown type #{plugin_type.inspect}. Must be one of: #{PLUGIN_TYPES.join(', ')}."
+          false
+        end
+
+        # Validate that the class name is a valid Ruby constant name.
+        #
+        # @private
+        # @param [String?] class_name class name to validate
+        # @return [Boolean]
+        def valid_name?(class_name)
+          return true if valid_constant?(class_name)
+
+          warn "Error: #{class_name.inspect} is not a valid Ruby constant name."
+          false
+        end
+
+        # Check whether a string is a valid Ruby constant name.
+        #
+        # @private
+        # @param [String?] str string constant to validate
+        # @return [Boolean]
+        def valid_constant?(str)
+          !!(str =~ /\A[A-Z][A-Za-z0-9]*(?:::[A-Z][A-Za-z0-9]*)*\z/)
+        end
+
+        # Build the file path for the generated plugin.
+        #
+        # @private
+        # @param [String?] class_name CamelCase plugin class name
+        # @param [String?] output_dir output directory
+        # @return [String] full file path
+        def plugin_path(class_name, output_dir)
+          File.join(output_dir || '.', "#{underscore(class_name || '')}.rb")
+        end
+
         # Convert CamelCase to snake_case for file naming.
         #
         # @private
-        # @param [String] str
+        # @param [String] str CamelCase string to convert
         # @return [String]
         def underscore(str)
           str
@@ -303,6 +400,80 @@ module Docscribe
             .gsub(/([a-z\d])([A-Z])/, '\1_\2')
             .downcase
         end
+
+        # Check whether the target plugin file already exists and warn if so.
+        #
+        # @private
+        # @param [String] path file path to check
+        # @return [Boolean]
+        def file_exists?(path)
+          return false unless File.exist?(path)
+
+          warn "Error: #{path} already exists. Remove it first or use --stdout."
+          true
+        end
+
+        # Create the output directory and write the plugin file.
+        #
+        # @private
+        # @param [String?] output_dir output directory path
+        # @param [String] path full plugin file path
+        # @param [String?] content file content to write
+        # @return [void]
+        def write_to_file(output_dir, path, content)
+          require 'fileutils'
+          FileUtils.mkdir_p(output_dir || '.')
+          File.write(path, content)
+        end
+
+        # Print the creation message and next steps after generating a plugin.
+        #
+        # @private
+        # @param [String?] plugin_type 'tag' or 'collector'
+        # @param [String] path file path of the created plugin
+        # @return [void]
+        def print_created(plugin_type, path)
+          puts "Created: #{path}"
+          puts
+          puts next_steps(plugin_type, path)
+        end
+
+        # Print registration instructions after file creation.
+        #
+        # @private
+        # @param [String?] plugin_type 'tag' or 'collector'
+        # @param [String] path file path
+        # @return [String]
+        def next_steps(plugin_type, path)
+          format(NEXT_STEPS_TEMPLATE,
+                 path: path,
+                 hint: generate_implement_hint(plugin_type),
+                 require_path: path.delete_suffix('.rb'),
+                 base_name: plugin_base_name(path))
+        end
+
+        # Derive a CamelCase base name from a snake_case file path.
+        #
+        # @private
+        # @param [String] path file path
+        # @return [String] CamelCase class name
+        def plugin_base_name(path)
+          File.basename(path, '.rb').split('_').map(&:capitalize).join
+        end
+
+        # Generate an implementation hint string for the given plugin type.
+        #
+        # @private
+        # @param [String?] plugin_type 'tag' or 'collector'
+        # @return [String, nil] hint text
+        def generate_implement_hint(plugin_type)
+          case plugin_type
+          when 'tag'
+            'Implement the #call method to return Array<Docscribe::Plugin::Tag>.'
+          when 'collector'
+            'Implement the #collect method to return Array<{anchor_node:, doc:}>.'
+          end
+        end
       end
     end
   end

data/lib/docscribe/cli/init.rb

@@ -5,7 +5,16 @@ require 'docscribe/config'
 
 module Docscribe
   module CLI
+    # Generate starter Docscribe configuration.
     module Init
+      BANNER = <<~TEXT
+        Usage: docscribe init [options]
+
+        Generate a starter docscribe.yml configuration file.
+
+        Options:
+      TEXT
+
       class << self
         # Create or print a starter Docscribe configuration file.
         #
@@ -18,30 +27,65 @@ module Docscribe
         # @param [Array<String>] argv command-line arguments for `docscribe init`
         # @return [Integer] process exit code
         def run(argv)
-          opts = {
-            config: 'docscribe.yml',
-            force: false,
-            stdout: false
-          }
+          opts = parse_init_options(argv)
+          return 0 if opts[:help]
+
+          yaml = Docscribe::Config.default_yaml
 
+          if opts[:stdout]
+            puts yaml
+            return 0
+          end
+
+          write_init_config(opts, yaml)
+        end
+
+        private
+
+        # Parse CLI options for `docscribe init`.
+        #
+        # @private
+        # @param [Array<String>] argv command-line arguments for `docscribe init`
+        # @return [Hash<Symbol, Object>] parsed options
+        def parse_init_options(argv)
+          opts = default_init_options
+          build_init_parser(opts).parse!(argv)
+          opts
+        end
+
+        # Return the default options hash for the init command.
+        #
+        # @private
+        # @return [Hash<Symbol, String, Boolean>]
+        def default_init_options
+          { config: 'docscribe.yml', force: false, stdout: false, help: false }
+        end
+
+        # Build and return an OptionParser for the init command.
+        #
+        # @private
+        # @param [Hash<Symbol, Object>] opts options hash that the parser populates
+        # @return [OptionParser]
+        def build_init_parser(opts)
           OptionParser.new do |o|
-            o.banner = 'Usage: docscribe init [options]'
+            o.banner = BANNER
             o.on('--config PATH', 'Where to write the config (default: docscribe.yml)') { |v| opts[:config] = v }
             o.on('-f', '--force', 'Overwrite if the file already exists') { opts[:force] = true }
             o.on('--stdout', 'Print config template to STDOUT instead of writing a file') { opts[:stdout] = true }
             o.on('-h', '--help', 'Show this help') do
+              opts[:help] = true
               puts o
-              return 0
             end
-          end.parse!(argv)
-
-          yaml = Docscribe::Config.default_yaml
-
-          if opts[:stdout]
-            puts yaml
-            return 0
           end
+        end
 
+        # Write the config template to a file.
+        #
+        # @private
+        # @param [Hash<Symbol, Object>] opts parsed options
+        # @param [String] yaml config template content
+        # @return [Integer] exit code
+        def write_init_config(opts, yaml)
           path = opts[:config]
           if File.exist?(path) && !opts[:force]
             warn "Config already exists: #{path} (use --force to overwrite)"