docscribe 1.4.2 → 1.5.0

data/lib/docscribe/cli/formatters/text.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module CLI
+    module Formatters
+      # Text output formatter preserving the original CLI output format.
+      class Text
+        # Format and print check summary.
+        #
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @param [Docscribe::CLI::Formatters::opts] options runtime options hash
+        # @return [void]
+        def format_check_summary(state:, options:)
+          puts
+          format_fail_paths(state, options)
+          format_check_status_line(state)
+          format_type_mismatch_paths(state, options)
+          format_error_paths(state)
+        end
+
+        # Format and print write summary.
+        #
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @param [Docscribe::CLI::Formatters::opts] options runtime options hash
+        # @return [void]
+        def format_write_summary(state:, options:)
+          puts
+          puts "Docscribe: updated #{state[:corrected]} file(s)" if state[:corrected].positive?
+          format_corrected_paths(state, options)
+
+          return unless state[:had_errors]
+
+          warn "Docscribe: #{state[:error_paths].size} file(s) had errors"
+          format_error_paths(state)
+        end
+
+        # Print files needing updates.
+        #
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @param [Docscribe::CLI::Formatters::opts] options runtime options hash
+        # @return [void]
+        def format_fail_paths(state, options)
+          state[:fail_paths].each do |p|
+            puts "Would update: #{p}"
+
+            next if options[:verbose] || options[:quiet]
+
+            Array(state[:fail_changes][p]).each do |change|
+              puts "  - #{format_change_reason(change)}"
+            end
+          end
+        end
+
+        # Print check status line.
+        #
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @return [void]
+        def format_check_status_line(state)
+          checked_error = state[:error_paths].size
+          type_mismatch_count = state[:type_mismatch_paths].size
+
+          if all_fine?(state, checked_error, type_mismatch_count)
+            puts "Docscribe: OK (#{state[:checked_ok]} files checked)"
+          elsif mismatch_only?(state, checked_error)
+            puts "Docscribe: OK (#{state[:checked_ok]} files checked, #{type_mismatch_count} with type mismatches)"
+          else
+            puts failure_line(state, type_mismatch_count, checked_error)
+          end
+        end
+
+        # Print type mismatch warnings.
+        #
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @param [Docscribe::CLI::Formatters::opts] options runtime options hash
+        # @return [void]
+        def format_type_mismatch_paths(state, options)
+          return if options[:quiet]
+          return unless options[:verbose] || options[:explain]
+
+          state[:type_mismatch_paths].each do |p|
+            warn "Type mismatches: #{p}"
+            Array(state[:type_mismatch_changes][p]).each do |change|
+              warn "  - #{format_change_reason(change)}"
+            end
+          end
+        end
+
+        # Print updated file paths.
+        #
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @param [Docscribe::CLI::Formatters::opts] options runtime options hash
+        # @return [void]
+        def format_corrected_paths(state, options)
+          state[:corrected_paths].each do |p|
+            puts "Updated: #{p}"
+
+            next if options[:verbose] || options[:quiet]
+
+            Array(state[:corrected_changes][p]).each do |change|
+              puts "  - #{format_change_reason(change)}"
+            end
+          end
+        end
+
+        # Print error file messages.
+        #
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @return [void]
+        def format_error_paths(state)
+          return if state[:error_paths].empty?
+
+          warn ''
+          state[:error_paths].each do |p|
+            warn "Error processing: #{p}"
+            warn "  #{state[:error_messages][p]}" if state[:error_messages][p]
+          end
+        end
+
+        private
+
+        # Check if all files passed.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @param [Integer] checked_error count of error files
+        # @param [Integer] type_mismatch_count count of type mismatches
+        # @return [Boolean]
+        def all_fine?(state, checked_error, type_mismatch_count)
+          state[:checked_fail].zero? && checked_error.zero? && type_mismatch_count.zero?
+        end
+
+        # Check only type mismatches.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @param [Integer] checked_error count of error files
+        # @return [Boolean]
+        def mismatch_only?(state, checked_error)
+          state[:checked_fail].zero? && checked_error.zero?
+        end
+
+        # Build failure status line.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::state] state formatter state hash
+        # @param [Integer] type_mismatch_count count of type mismatches
+        # @param [Integer] checked_error count of error files
+        # @return [String]
+        def failure_line(state, type_mismatch_count, checked_error)
+          parts = ["#{state[:checked_fail]} need updates"]
+          parts << "#{type_mismatch_count} type mismatches" if type_mismatch_count.positive?
+          parts << "#{checked_error} errors"
+          parts << "#{state[:checked_ok]} ok"
+          "Docscribe: FAILED (#{parts.join(', ')})"
+        end
+
+        # Format change reason string.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::change] change change info hash
+        # @return [String]
+        def format_change_reason(change)
+          line = change_line_suffix(change)
+          method = change_method_suffix(change)
+
+          return "unsorted tags#{line}" if change[:type] == :unsorted_tags
+          return "#{change[:message]}#{method}#{line}" if direct_message_change?(change)
+
+          "#{change[:message] || change[:type].to_s.tr('_', ' ')}#{method}#{line}"
+        end
+
+        # Build change line suffix.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::change] change change info hash
+        # @return [String]
+        def change_line_suffix(change)
+          change[:line] ? " at line #{change[:line]}" : ''
+        end
+
+        # Build change method suffix.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::change] change change info hash
+        # @return [String]
+        def change_method_suffix(change)
+          change[:method] ? " for #{change[:method]}" : ''
+        end
+
+        # Check direct message type.
+        #
+        # @private
+        # @param [Docscribe::CLI::Formatters::change] change change info hash
+        # @return [Boolean]
+        def direct_message_change?(change)
+          %i[
+            missing_param
+            missing_return
+            missing_raise
+            missing_visibility
+            missing_module_function_note
+            insert_full_doc_block
+          ].include?(change[:type])
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/cli/formatters.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module CLI
+    # Factory for output formatters.
+    module Formatters
+      # Select formatter by format type.
+      #
+      # @param [Docscribe::CLI::Formatters::format] format output format symbol
+      # @raise [ArgumentError]
+      # @return [Docscribe::CLI::Formatters::Text, Docscribe::CLI::Formatters::Json, Docscribe::CLI::Formatters::Sarif]
+      def self.for(format)
+        case format
+        when :text then Text.new
+        when :json then Json.new
+        when :sarif then Sarif.new
+        else raise ArgumentError, "Unknown format: #{format}"
+        end
+      end
+    end
+  end
+end
+
+require_relative 'formatters/text'
+require_relative 'formatters/json'
+require_relative 'formatters/sarif'

data/lib/docscribe/cli/generate.rb

@@ -34,8 +34,7 @@ module Docscribe
       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, parser = parse_generate_options(argv)
@@ -54,9 +53,9 @@ module Docscribe
         # Parse options for the generate subcommand.
         #
         # @private
-        # @param [Array<String>] argv
+        # @param [Array<String>] argv command line arguments
         # @raise [OptionParser::InvalidOption]
-        # @return [Array(Hash, OptionParser)]
+        # @return [(Hash<Symbol, Object>, OptionParser)]
         def parse_generate_options(argv)
           opts = { output: nil, stdout: false, help: false }
           parser = build_option_parser(opts)
@@ -74,8 +73,8 @@ module Docscribe
         # Extract plugin_type and class_name from remaining argv.
         #
         # @private
-        # @param [Array<String>] argv
-        # @return [Array(String, String)]
+        # @param [Array<String>] argv command line arguments
+        # @return [(String?, String?)]
         def extract_generate_args(argv)
           [argv.shift, argv.shift]
         end
@@ -83,9 +82,9 @@ module Docscribe
         # Validate generate arguments and return exit code on failure.
         #
         # @private
-        # @param [String, nil] plugin_type
-        # @param [String, nil] class_name
-        # @param [OptionParser] parser
+        # @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)
@@ -98,9 +97,9 @@ module Docscribe
         # 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)
@@ -111,7 +110,7 @@ module Docscribe
         # 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
@@ -169,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
@@ -237,10 +236,10 @@ module Docscribe
         # 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] opts parsed options hash
+        # @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]
@@ -254,10 +253,10 @@ module Docscribe
         # Write the generated content to a file.
         #
         # @private
-        # @param [String] content
-        # @param [String] plugin_type
-        # @param [String] class_name
-        # @param [String] output_dir
+        # @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)
@@ -272,7 +271,7 @@ module Docscribe
         # Build the OptionParser for the generate subcommand.
         #
         # @private
-        # @param [Hash] opts mutable parsed options hash
+        # @param [Hash<Symbol, Object>] opts mutable parsed options hash
         # @return [OptionParser]
         def build_option_parser(opts)
           OptionParser.new do |opt|
@@ -302,8 +301,8 @@ module Docscribe
         # Register the --output option on the OptionParser.
         #
         # @private
-        # @param [OptionParser] opt
-        # @param [Hash] opts mutable parsed options hash
+        # @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 }
@@ -312,8 +311,8 @@ module Docscribe
         # Register the --stdout option on the OptionParser.
         #
         # @private
-        # @param [OptionParser] opt
-        # @param [Hash] opts mutable parsed options hash
+        # @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 }
@@ -322,11 +321,12 @@ module Docscribe
         # Register the -h/--help option on the OptionParser.
         #
         # @private
-        # @param [OptionParser] opt
-        # @param [Hash] opts mutable parsed options hash
+        # @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
@@ -334,9 +334,9 @@ module Docscribe
         # Validate that both plugin_type and class_name arguments were provided.
         #
         # @private
-        # @param [String, nil] plugin_type plugin type argument
-        # @param [String, nil] class_name plugin class name argument
-        # @param [OptionParser] parser
+        # @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
@@ -349,7 +349,7 @@ module Docscribe
         # Validate that the plugin type is one of the recognized types.
         #
         # @private
-        # @param [String] plugin_type plugin type to validate
+        # @param [String?] plugin_type plugin type to validate
         # @return [Boolean]
         def known_type?(plugin_type)
           return true if PLUGIN_TYPES.include?(plugin_type)
@@ -361,7 +361,7 @@ module Docscribe
         # Validate that the class name is a valid Ruby constant name.
         #
         # @private
-        # @param [String] class_name class name to validate
+        # @param [String?] class_name class name to validate
         # @return [Boolean]
         def valid_name?(class_name)
           return true if valid_constant?(class_name)
@@ -373,7 +373,7 @@ module Docscribe
         # Check whether a string is a valid Ruby constant name.
         #
         # @private
-        # @param [String] str
+        # @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/)
@@ -382,8 +382,8 @@ module Docscribe
         # Build the file path for the generated plugin.
         #
         # @private
-        # @param [String] class_name CamelCase plugin class name
-        # @param [String] output_dir output directory
+        # @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")
@@ -392,7 +392,7 @@ module Docscribe
         # 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
@@ -416,9 +416,9 @@ module Docscribe
         # Create the output directory and write the plugin file.
         #
         # @private
-        # @param [String] output_dir output directory path
+        # @param [String?] output_dir output directory path
         # @param [String] path full plugin file path
-        # @param [String] content file content to write
+        # @param [String?] content file content to write
         # @return [void]
         def write_to_file(output_dir, path, content)
           require 'fileutils'
@@ -429,7 +429,7 @@ module Docscribe
         # Print the creation message and next steps after generating a plugin.
         #
         # @private
-        # @param [String] plugin_type 'tag' or 'collector'
+        # @param [String?] plugin_type 'tag' or 'collector'
         # @param [String] path file path of the created plugin
         # @return [void]
         def print_created(plugin_type, path)
@@ -441,8 +441,8 @@ module Docscribe
         # Print registration instructions after file creation.
         #
         # @private
-        # @param [String] plugin_type
-        # @param [String] path
+        # @param [String?] plugin_type 'tag' or 'collector'
+        # @param [String] path file path
         # @return [String]
         def next_steps(plugin_type, path)
           format(NEXT_STEPS_TEMPLATE,
@@ -464,8 +464,8 @@ module Docscribe
         # Generate an implementation hint string for the given plugin type.
         #
         # @private
-        # @param [String] plugin_type 'tag' or 'collector'
-        # @return [String] hint text
+        # @param [String?] plugin_type 'tag' or 'collector'
+        # @return [String, nil] hint text
         def generate_implement_hint(plugin_type)
           case plugin_type
           when 'tag'

data/lib/docscribe/cli/init.rb

@@ -7,6 +7,14 @@ 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.
         #
@@ -37,8 +45,8 @@ module Docscribe
         # Parse CLI options for `docscribe init`.
         #
         # @private
-        # @param [Array<String>] argv
-        # @return [Hash] parsed options
+        # @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)
@@ -48,7 +56,7 @@ module Docscribe
         # Return the default options hash for the init command.
         #
         # @private
-        # @return [Hash]
+        # @return [Hash<Symbol, String, Boolean>]
         def default_init_options
           { config: 'docscribe.yml', force: false, stdout: false, help: false }
         end
@@ -56,11 +64,11 @@ module Docscribe
         # Build and return an OptionParser for the init command.
         #
         # @private
-        # @param [Hash] opts options hash that the parser populates
+        # @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 }
@@ -74,7 +82,7 @@ module Docscribe
         # Write the config template to a file.
         #
         # @private
-        # @param [Hash] opts parsed options
+        # @param [Hash<Symbol, Object>] opts parsed options
         # @param [String] yaml config template content
         # @return [Integer] exit code
         def write_init_config(opts, yaml)