docscribe 1.4.2 → 1.5.0

data/lib/docscribe/cli/options.rb

@@ -12,6 +12,8 @@ module Docscribe
         strategy: :safe,    # :safe, :aggressive
         verbose: false,
         explain: false,
+        quiet: false,
+        format: :text,
         config: nil,
         include: [], #: Array[String]
         exclude: [], #: Array[String]
@@ -21,13 +23,22 @@ module Docscribe
         sig_dirs: [], #: Array[String]
         sorbet: false,
         rbi_dirs: [], #: Array[String]
-        rbs_collection: false
+        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.
@@ -58,7 +69,11 @@ module Docscribe
 
         Output:
                 --verbose                  Print per-file actions
-            -e, --explain                  Show detailed reasons for changes
+                --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
@@ -76,9 +91,9 @@ 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 }
@@ -90,9 +105,9 @@ module Docscribe
 
       # Build the OptionParser instance and register all CLI option groups.
       #
-      # @note module_function: when included, also defines #build_option_parser (instance visibility: private)
-      # @param [Hash] options mutable parsed options hash
-      # @param [Hash{Symbol => Symbol,nil}] autocorrect mutable container for autocorrect mode
+      # @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|
@@ -106,10 +121,11 @@ module Docscribe
         end
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash{Symbol => Symbol,nil}] autocorrect mutable container for autocorrect mode (:safe, :aggressive, nil)
+      # 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
@@ -121,20 +137,22 @@ module Docscribe
         end
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options mutable parsed options hash
+      # 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
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options mutable parsed options hash
+      # 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
@@ -142,10 +160,11 @@ module Docscribe
         end
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options mutable parsed options hash
+      # 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|
@@ -153,10 +172,11 @@ module Docscribe
         end
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options mutable parsed options hash
+      # 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)
@@ -166,10 +186,11 @@ module Docscribe
         define_rbs_collection_option(opts, options)
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options
+      # 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
@@ -177,10 +198,11 @@ module Docscribe
         end
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options
+      # 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|
@@ -189,10 +211,11 @@ module Docscribe
         end
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options
+      # 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
@@ -200,10 +223,11 @@ module Docscribe
         end
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options
+      # 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|
@@ -212,10 +236,11 @@ module Docscribe
         end
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options
+      # 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
@@ -224,10 +249,11 @@ module Docscribe
         end
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options mutable parsed options hash
+      # 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)
@@ -236,10 +262,11 @@ module Docscribe
         define_exclude_file_option(opts, options)
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options mutable parsed options hash
+      # 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|
@@ -247,10 +274,11 @@ module Docscribe
         end
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options mutable parsed options hash
+      # 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',
@@ -259,10 +287,11 @@ module Docscribe
         end
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options mutable parsed options hash
+      # 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|
@@ -270,10 +299,11 @@ module Docscribe
         end
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options mutable parsed options hash
+      # 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|
@@ -281,31 +311,52 @@ module Docscribe
         end
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options mutable parsed options hash
+      # 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
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options mutable parsed options hash
+      # 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
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
-      # @param [Hash] options mutable parsed options hash
+      # 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
@@ -313,9 +364,61 @@ module Docscribe
         end
       end
 
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [OptionParser] opts
+      # 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
@@ -332,9 +435,8 @@ module Docscribe
 
       # Set the runtime mode and strategy after all options have been parsed.
       #
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [Hash] options mutable parsed options hash
+      # @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)
@@ -355,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]
@@ -373,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)