docscribe 1.4.1 → 1.5.0

data/lib/docscribe/cli/options.rb

@@ -4,6 +4,7 @@ require 'optparse'
 
 module Docscribe
   module CLI
+    # CLI option parsing and defaults.
     module Options
       DEFAULT = {
         stdin: false,
@@ -11,20 +12,74 @@ module Docscribe
         strategy: :safe,    # :safe, :aggressive
         verbose: false,
         explain: false,
+        quiet: false,
+        format: :text,
         config: nil,
-        include: [],
-        exclude: [],
-        include_file: [],
-        exclude_file: [],
+        include: [], #: Array[String]
+        exclude: [], #: Array[String]
+        include_file: [], #: Array[String]
+        exclude_file: [], #: Array[String]
         rbs: false,
-        sig_dirs: [],
+        sig_dirs: [], #: Array[String]
         sorbet: false,
-        rbi_dirs: [],
-        rbs_collection: false
+        rbi_dirs: [], #: Array[String]
+        rbs_collection: false,
+        keep_descriptions: false,
+        no_boilerplate: false,
+        progress: false
       }.freeze
 
       module_function
 
+      BANNER = <<~TEXT
+        Usage: docscribe [options] [files...]
+               docscribe init [options]
+               docscribe generate <type> <name> [options]
+               docscribe sigs [options] [files...]
+               docscribe rbs [options] [files...]
+               docscribe update_types [directory]
+               docscribe check_for_comments [paths...]
+
+        Default behavior:
+          Inspect files and report what safe doc updates would be applied.
+
+        Autocorrect:
+            -a, --autocorrect              Apply safe doc updates in place
+                                           (insert missing docs, merge existing doc-like blocks,
+                                           normalize tag order)
+            -A, --autocorrect-all          Apply aggressive doc updates in place
+                                           (rebuild existing doc blocks)
+
+        Input / config:
+                --stdin                    Read code from STDIN and print rewritten output
+            -C, --config PATH              Path to config YAML (default: docscribe.yml)
+
+        Type information:
+                --rbs                      Use RBS signatures for @param/@return when available
+                --sig-dir DIR              Add an RBS signature directory (repeatable). Implies `--rbs`.
+                --sorbet                   Use Sorbet signatures from inline sigs / RBI files when available
+                --rbi-dir DIR              Add a Sorbet RBI directory (repeatable). Implies --sorbet.
+                --rbs-collection           Auto-discover RBS collection from rbs_collection.lock.yaml. Implies --rbs.
+
+        Filtering:
+                --include PATTERN          Include PATTERN (method id or file path; glob or /regex/)
+                --exclude PATTERN          Exclude PATTERN (method id or file path; glob or /regex/)
+                --include-file PATTERN     Only process files matching PATTERN (glob or /regex/)
+                --exclude-file PATTERN     Skip files matching PATTERN (glob or /regex/)
+
+        Output:
+                --verbose                  Print per-file actions
+                --progress                 Show progress [N/total] per file
+            -e, --explain                  Show detailed reasons for changes (default)
+            -q, --quiet                    Only show status, no details
+                --format FORMAT            Output format: text (default), json, or sarif
+
+
+        Other:
+            -v, --version                  Print version and exit
+            -h, --help                     Show this help
+      TEXT
+
       # Parse CLI arguments into normalized Docscribe runtime options.
       #
       # CLI behavior model:
@@ -36,131 +91,355 @@ module Docscribe
       # Filtering, config, verbosity, and external type options are applied
       # orthogonally.
       #
-      # @note module_function: when included, also defines #parse! (instance visibility: private)
+      # @note module_function: defines #parse! (visibility: private)
       # @param [Array<String>] argv raw CLI arguments
-      # @return [Hash] normalized runtime options
+      # @return [Docscribe::CLI::Formatters::opts] normalized runtime options
       def parse!(argv)
         options = Marshal.load(Marshal.dump(DEFAULT))
-        autocorrect_mode = nil
-
-        parser = OptionParser.new do |opts|
-          opts.banner = <<~TEXT
-            Usage: docscribe [options] [files...]
-
-            Default behavior:
-              Inspect files and report what safe doc updates would be applied.
-
-            Autocorrect:
-                -a, --autocorrect              Apply safe doc updates in place
-                                               (insert missing docs, merge existing doc-like blocks,
-                                               normalize tag order)
-                -A, --autocorrect-all          Apply aggressive doc updates in place
-                                               (rebuild existing doc blocks)
-
-            Input / config:
-                    --stdin                    Read code from STDIN and print rewritten output
-                -C, --config PATH              Path to config YAML (default: docscribe.yml)
-
-            Type information:
-                    --rbs                      Use RBS signatures for @param/@return when available
-                    --sig-dir DIR              Add an RBS signature directory (repeatable). Implies `--rbs`.
-                    --sorbet                   Use Sorbet signatures from inline sigs / RBI files when available
-                    --rbi-dir DIR              Add a Sorbet RBI directory (repeatable). Implies --sorbet.
-                    --rbs-collection           Auto-discover RBS collection from rbs_collection.lock.yaml. Implies --rbs.
-
-            Filtering:
-                    --include PATTERN          Include PATTERN (method id or file path; glob or /regex/)
-                    --exclude PATTERN          Exclude PATTERN (method id or file path; glob or /regex/)
-                    --include-file PATTERN     Only process files matching PATTERN (glob or /regex/)
-                    --exclude-file PATTERN     Skip files matching PATTERN (glob or /regex/)
-
-            Output:
-                    --verbose                  Print per-file actions
-                -e, --explain                  Show detailed reasons for changes
-
-            Other:
-                -v, --version                  Print version and exit
-                -h, --help                     Show this help
-          TEXT
-
-          opts.on('-a', '--autocorrect', 'Apply safe doc updates in place') do
-            autocorrect_mode = :safe
-          end
-
-          opts.on('-A', '--autocorrect-all', 'Apply aggressive doc updates in place') do
-            autocorrect_mode = :aggressive
-          end
-
-          opts.on('--stdin', 'Read code from STDIN and print rewritten output') do
-            options[:stdin] = true
-          end
-
-          opts.on('-C', '--config PATH', 'Path to config YAML (default: docscribe.yml)') do |v|
-            options[:config] = v
-          end
-
-          opts.on('--rbs', 'Use RBS signatures for @param/@return when available (falls back to inference)') do
-            options[:rbs] = true
-          end
-
-          opts.on('--sig-dir DIR', 'Add an RBS signature directory (repeatable). Implies --rbs.') do |v|
-            options[:rbs] = true
-            options[:sig_dirs] << v
-          end
-
-          opts.on('--sorbet', 'Use Sorbet signatures from inline sigs / RBI files when available') do
-            options[:sorbet] = true
-          end
-
-          opts.on('--rbi-dir DIR', 'Add a Sorbet RBI directory (repeatable). Implies --sorbet.') do |v|
-            options[:sorbet] = true
-            options[:rbi_dirs] << v
-          end
-
-          opts.on('--rbs-collection', 'Auto-discover RBS collection from rbs_collection.lock.yaml. Implies --rbs.') do
-            options[:rbs] = true
-            options[:rbs_collection] = true
-          end
-
-          opts.on('--include PATTERN', 'Include PATTERN (method id or file path; glob or /regex/)') do |v|
-            route_include_exclude(options, :include, v)
-          end
-
-          opts.on('--exclude PATTERN',
-                  'Exclude PATTERN (method id or file path; glob or /regex/). Exclude wins.') do |v|
-            route_include_exclude(options, :exclude, v)
-          end
-
-          opts.on('--include-file PATTERN', 'Only process files matching PATTERN (glob or /regex/)') do |v|
-            options[:include_file] << v
-          end
-
-          opts.on('--exclude-file PATTERN', 'Skip files matching PATTERN (glob or /regex/). Exclude wins.') do |v|
-            options[:exclude_file] << v
-          end
-
-          opts.on('--verbose', 'Print per-file actions') do
-            options[:verbose] = true
-          end
-
-          opts.on('-e', '--explain', 'Show detailed reasons for changes') do
-            options[:explain] = true
-          end
-
-          opts.on('-v', '--version', 'Print version and exit') do
-            require 'docscribe/version'
-            puts Docscribe::VERSION
-            exit 0
-          end
-
-          opts.on('-h', '--help', 'Show this help') do
-            puts opts
-            exit 0
-          end
-        end
-
-        parser.parse!(argv)
+        autocorrect = { mode: nil }
+
+        build_option_parser(options, autocorrect).parse!(argv)
+        resolve_mode_and_strategy!(options, autocorrect[:mode])
+        options
+      end
+
+      # Build the OptionParser instance and register all CLI option groups.
+      #
+      # @note module_function: defines #build_option_parser (visibility: private)
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @param [Hash<Symbol, Symbol, nil>] autocorrect mutable container for autocorrect mode
+      # @return [OptionParser]
+      def build_option_parser(options, autocorrect)
+        OptionParser.new do |opts|
+          opts.banner = BANNER
+          define_autocorrect_options(opts, autocorrect)
+          define_input_options(opts, options)
+          define_type_options(opts, options)
+          define_filter_options(opts, options)
+          define_output_options(opts, options)
+          define_misc_options(opts)
+        end
+      end
+
+      # Define autocorrect options
+      #
+      # @note module_function: defines #define_autocorrect_options (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Symbol, nil>] autocorrect mutable container for autocorrect mode (:safe, :aggressive, nil)
+      # @return [void]
+      def define_autocorrect_options(opts, autocorrect)
+        opts.on('-a', '--autocorrect', 'Apply safe doc updates in place') do
+          autocorrect[:mode] = :safe
+        end
+
+        opts.on('-A', '--autocorrect-all', 'Apply aggressive doc updates in place') do
+          autocorrect[:mode] = :aggressive
+        end
+      end
+
+      # Define input options
+      #
+      # @note module_function: defines #define_input_options (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_input_options(opts, options)
+        define_stdin_option(opts, options)
+        define_config_option(opts, options)
+      end
+
+      # Define stdin option
+      #
+      # @note module_function: defines #define_stdin_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_stdin_option(opts, options)
+        opts.on('--stdin', 'Read code from STDIN and print rewritten output') do
+          options[:stdin] = true
+        end
+      end
+
+      # Define config option
+      #
+      # @note module_function: defines #define_config_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_config_option(opts, options)
+        opts.on('-C', '--config PATH', 'Path to config YAML (default: docscribe.yml)') do |v|
+          options[:config] = v
+        end
+      end
+
+      # Define type options
+      #
+      # @note module_function: defines #define_type_options (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_type_options(opts, options)
+        define_rbs_option(opts, options)
+        define_sig_dir_option(opts, options)
+        define_sorbet_option(opts, options)
+        define_rbi_dir_option(opts, options)
+        define_rbs_collection_option(opts, options)
+      end
+
+      # Define rbs option
+      #
+      # @note module_function: defines #define_rbs_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_rbs_option(opts, options)
+        opts.on('--rbs', 'Use RBS signatures for @param/@return when available (falls back to inference)') do
+          options[:rbs] = true
+        end
+      end
+
+      # Define sig dir option
+      #
+      # @note module_function: defines #define_sig_dir_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_sig_dir_option(opts, options)
+        opts.on('--sig-dir DIR', 'Add an RBS signature directory (repeatable). Implies --rbs.') do |v|
+          options[:rbs] = true
+          options[:sig_dirs] << v
+        end
+      end
+
+      # Define sorbet option
+      #
+      # @note module_function: defines #define_sorbet_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_sorbet_option(opts, options)
+        opts.on('--sorbet', 'Use Sorbet signatures from inline sigs / RBI files when available') do
+          options[:sorbet] = true
+        end
+      end
+
+      # Define rbi dir option
+      #
+      # @note module_function: defines #define_rbi_dir_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_rbi_dir_option(opts, options)
+        opts.on('--rbi-dir DIR', 'Add a Sorbet RBI directory (repeatable). Implies --sorbet.') do |v|
+          options[:sorbet] = true
+          options[:rbi_dirs] << v
+        end
+      end
+
+      # Define rbs collection option
+      #
+      # @note module_function: defines #define_rbs_collection_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_rbs_collection_option(opts, options)
+        opts.on('--rbs-collection', 'Auto-discover RBS collection from rbs_collection.lock.yaml. Implies --rbs.') do
+          options[:rbs] = true
+          options[:rbs_collection] = true
+        end
+      end
+
+      # Define filter options
+      #
+      # @note module_function: defines #define_filter_options (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_filter_options(opts, options)
+        define_include_option(opts, options)
+        define_exclude_option(opts, options)
+        define_include_file_option(opts, options)
+        define_exclude_file_option(opts, options)
+      end
+
+      # Define include option
+      #
+      # @note module_function: defines #define_include_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_include_option(opts, options)
+        opts.on('--include PATTERN', 'Include PATTERN (method id or file path; glob or /regex/)') do |v|
+          route_include_exclude(options, :include, v)
+        end
+      end
+
+      # Define exclude option
+      #
+      # @note module_function: defines #define_exclude_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_exclude_option(opts, options)
+        opts.on('--exclude PATTERN',
+                'Exclude PATTERN (method id or file path; glob or /regex/). Exclude wins.') do |v|
+          route_include_exclude(options, :exclude, v)
+        end
+      end
+
+      # Define include file option
+      #
+      # @note module_function: defines #define_include_file_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_include_file_option(opts, options)
+        opts.on('--include-file PATTERN', 'Only process files matching PATTERN (glob or /regex/)') do |v|
+          options[:include_file] << v
+        end
+      end
+
+      # Define exclude file option
+      #
+      # @note module_function: defines #define_exclude_file_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_exclude_file_option(opts, options)
+        opts.on('--exclude-file PATTERN', 'Skip files matching PATTERN (glob or /regex/). Exclude wins.') do |v|
+          options[:exclude_file] << v
+        end
+      end
+
+      # Define output options
+      #
+      # @note module_function: defines #define_output_options (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_output_options(opts, options)
+        define_verbose_option(opts, options)
+        define_progress_option(opts, options)
+        define_explain_option(opts, options)
+        define_quiet_option(opts, options)
+        define_format_option(opts, options)
+        define_keep_descriptions_option(opts, options)
+        define_no_boilerplate_option(opts, options)
+      end
+
+      # Define verbose option
+      #
+      # @note module_function: defines #define_verbose_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_verbose_option(opts, options)
+        opts.on('--verbose', 'Print per-file actions') do
+          options[:verbose] = true
+          options[:progress] = true
+        end
+      end
+
+      # Define progress option
+      #
+      # @note module_function: defines #define_progress_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_progress_option(opts, options)
+        opts.on('--progress', 'Show progress [N/total] per file') do
+          options[:progress] = true
+        end
+      end
+
+      # Define explain option
+      #
+      # @note module_function: defines #define_explain_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_explain_option(opts, options)
+        opts.on('-e', '--explain', 'Show detailed reasons for changes') do
+          options[:explain] = true
+        end
+      end
+
+      # Define quiet option
+      #
+      # @note module_function: defines #define_quiet_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_quiet_option(opts, options)
+        opts.on('-q', '--quiet', 'Only show status, no details') do
+          options[:quiet] = true
+        end
+      end
+
+      # Define format option
+      #
+      # @note module_function: defines #define_format_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_format_option(opts, options)
+        opts.on('--format FORMAT', %i[text json sarif], # steep:ignore
+                'Output format: text (default), json, or sarif') do |v|
+          options[:format] = v
+        end
+      end
+
+      # Define keep descriptions option
+      #
+      # @note module_function: defines #define_keep_descriptions_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_keep_descriptions_option(opts, options)
+        opts.on('-k', '--keep-descriptions',
+                'Preserve existing @param/@return descriptions in aggressive mode') do
+          options[:keep_descriptions] = true
+        end
+      end
 
+      # Define no boilerplate option
+      #
+      # @note module_function: defines #define_no_boilerplate_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_no_boilerplate_option(opts, options)
+        opts.on('-B', '--no-boilerplate',
+                "Don't insert template text when generating documentation") do
+          options[:no_boilerplate] = true
+        end
+      end
+
+      # Define misc options
+      #
+      # @note module_function: defines #define_misc_options (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @return [void]
+      def define_misc_options(opts)
+        opts.on('-v', '--version', 'Print version and exit') do
+          require 'docscribe/version'
+          puts Docscribe::VERSION
+          exit 0
+        end
+
+        opts.on('-h', '--help', 'Show this help') do
+          puts opts
+          exit 0
+        end
+      end
+
+      # Set the runtime mode and strategy after all options have been parsed.
+      #
+      # @note module_function: defines #resolve_mode_and_strategy! (visibility: private)
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @param [Symbol, nil] autocorrect_mode autocorrect mode selected (:safe, :aggressive, or nil)
+      # @return [void]
+      def resolve_mode_and_strategy!(options, autocorrect_mode)
         if options[:stdin]
           options[:mode] = :stdin
           options[:strategy] = autocorrect_mode || :safe
@@ -171,8 +450,6 @@ module Docscribe
           options[:mode] = :check
           options[:strategy] = :safe
         end
-
-        options
       end
 
       # Route an include/exclude pattern into method filters or file filters.
@@ -180,8 +457,8 @@ module Docscribe
       # Regex-looking patterns (`/…/`) are treated as method-id filters.
       # File-like patterns are routed into `*_file`.
       #
-      # @note module_function: when included, also defines #route_include_exclude (instance visibility: private)
-      # @param [Hash] options mutable parsed options hash
+      # @note module_function: defines #route_include_exclude (visibility: private)
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
       # @param [Symbol] kind either :include or :exclude
       # @param [String] value raw pattern from the CLI
       # @return [void]
@@ -198,7 +475,7 @@ module Docscribe
       # Regex syntax (`/.../`) is intentionally treated as a method-id pattern,
       # not a file pattern.
       #
-      # @note module_function: when included, also defines #looks_like_file_pattern? (instance visibility: private)
+      # @note module_function: defines #looks_like_file_pattern? (visibility: private)
       # @param [String] pat pattern passed via CLI
       # @return [Boolean]
       def looks_like_file_pattern?(pat)