Module: Docscribe::CLI::Options

Defined in:
lib/docscribe/cli/options.rb

Overview

CLI option parsing and defaults.

Constant Summary collapse

DEFAULT = 
{
  stdin: false,
  mode: :check,       # :check, :write, :stdin
  strategy: :safe,    # :safe, :aggressive
  verbose: false,
  explain: false,
  quiet: false,
  format: :text,
  config: nil,
  include: [], #: Array[String]
  exclude: [], #: Array[String]
  include_file: [], #: Array[String]
  exclude_file: [], #: Array[String]
  rbs: false,
  sig_dirs: [], #: Array[String]
  sorbet: false,
  rbi_dirs: [], #: Array[String]
  rbs_collection: false,
  keep_descriptions: false,
  no_boilerplate: false,
  progress: false,
  parallel: false,
  server: false
}.freeze
<<~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)
          --server                   Use background server for faster repeated runs

  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

  Performance:
          --parallel                 Process files in parallel (default: sequential)

  Other:
      -v, --version                  Print version and exit
      -h, --help                     Show this help
TEXT

Class Method Summary collapse

Class Method Details

.build_option_parser(options, autocorrect) ⇒ OptionParser

Note:

module_function: defines #build_option_parser (visibility: private)

Build the OptionParser instance and register all CLI option groups.

Parameters:

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash

  • autocorrect (Hash<Symbol, Symbol, nil>) —

    mutable container for autocorrect mode

Returns:

  • (OptionParser) 


117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/docscribe/cli/options.rb', line 117

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(opts, autocorrect) ⇒ void

Note:

module_function: defines #define_autocorrect_options (visibility: private)

This method returns an undefined value.

Define autocorrect options

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • autocorrect (Hash<Symbol, Symbol, nil>) —

    mutable container for autocorrect mode (:safe, :aggressive, nil)



135
136
137
138
139
140
141
142
143
 
# File 'lib/docscribe/cli/options.rb', line 135

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_config_option(opts, options) ⇒ void

Note:

module_function: defines #define_config_option (visibility: private)

This method returns an undefined value.

Define config option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



175
176
177
178
179
 
# File 'lib/docscribe/cli/options.rb', line 175

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_exclude_file_option(opts, options) ⇒ void

Note:

module_function: defines #define_exclude_file_option (visibility: private)

This method returns an undefined value.

Define exclude file option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



326
327
328
329
330
 
# File 'lib/docscribe/cli/options.rb', line 326

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_exclude_option(opts, options) ⇒ void

Note:

module_function: defines #define_exclude_option (visibility: private)

This method returns an undefined value.

Define exclude option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



301
302
303
304
305
306
 
# File 'lib/docscribe/cli/options.rb', line 301

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_explain_option(opts, options) ⇒ void

Note:

module_function: defines #define_explain_option (visibility: private)

This method returns an undefined value.

Define explain option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



392
393
394
395
396
 
# File 'lib/docscribe/cli/options.rb', line 392

def define_explain_option(opts, options)
  opts.on('-e', '--explain', 'Show detailed reasons for changes') do
    options[:explain] = true
  end
end

.define_filter_options(opts, options) ⇒ void

Note:

module_function: defines #define_filter_options (visibility: private)

This method returns an undefined value.

Define filter options

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



276
277
278
279
280
281
 
# File 'lib/docscribe/cli/options.rb', line 276

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_format_option(opts, options) ⇒ void

Note:

module_function: defines #define_format_option (visibility: private)

This method returns an undefined value.

Define format option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



416
417
418
419
420
421
 
# File 'lib/docscribe/cli/options.rb', line 416

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_include_file_option(opts, options) ⇒ void

Note:

module_function: defines #define_include_file_option (visibility: private)

This method returns an undefined value.

Define include file option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



314
315
316
317
318
 
# File 'lib/docscribe/cli/options.rb', line 314

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_include_option(opts, options) ⇒ void

Note:

module_function: defines #define_include_option (visibility: private)

This method returns an undefined value.

Define include option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



289
290
291
292
293
 
# File 'lib/docscribe/cli/options.rb', line 289

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_input_options(opts, options) ⇒ void

Note:

module_function: defines #define_input_options (visibility: private)

This method returns an undefined value.

Define input options

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



151
152
153
154
155
 
# File 'lib/docscribe/cli/options.rb', line 151

def define_input_options(opts, options)
  define_stdin_option(opts, options)
  define_config_option(opts, options)
  define_server_option(opts, options)
end

.define_keep_descriptions_option(opts, options) ⇒ void

Note:

module_function: defines #define_keep_descriptions_option (visibility: private)

This method returns an undefined value.

Define keep descriptions option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



429
430
431
432
433
434
 
# File 'lib/docscribe/cli/options.rb', line 429

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_misc_options(opts) ⇒ void

Note:

module_function: defines #define_misc_options (visibility: private)

This method returns an undefined value.

Define misc options

Parameters:

  • opts (OptionParser) —

    the option parser to configure



454
455
456
457
458
459
460
461
462
463
464
465
 
# File 'lib/docscribe/cli/options.rb', line 454

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

.define_no_boilerplate_option(opts, options) ⇒ void

Note:

module_function: defines #define_no_boilerplate_option (visibility: private)

This method returns an undefined value.

Define no boilerplate option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



442
443
444
445
446
447
 
# File 'lib/docscribe/cli/options.rb', line 442

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_output_options(opts, options) ⇒ void

Note:

module_function: defines #define_output_options (visibility: private)

This method returns an undefined value.

Define output options

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



338
339
340
341
342
343
344
345
346
347
 
# File 'lib/docscribe/cli/options.rb', line 338

def define_output_options(opts, options)
  define_verbose_option(opts, options)
  define_progress_option(opts, options)
  define_parallel_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_parallel_option(opts, options) ⇒ void

Note:

module_function: defines #define_parallel_option (visibility: private)

This method returns an undefined value.

Define parallel option

Parameters:

  • opts (Hash<Symbol, Object>) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



380
381
382
383
384
 
# File 'lib/docscribe/cli/options.rb', line 380

def define_parallel_option(opts, options)
  opts.on('--parallel', 'Process files in parallel (default: sequential)') do
    options[:parallel] = true
  end
end

.define_progress_option(opts, options) ⇒ void

Note:

module_function: defines #define_progress_option (visibility: private)

This method returns an undefined value.

Define progress option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



368
369
370
371
372
 
# File 'lib/docscribe/cli/options.rb', line 368

def define_progress_option(opts, options)
  opts.on('--progress', 'Show progress [N/total] per file') do
    options[:progress] = true
  end
end

.define_quiet_option(opts, options) ⇒ void

Note:

module_function: defines #define_quiet_option (visibility: private)

This method returns an undefined value.

Define quiet option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



404
405
406
407
408
 
# File 'lib/docscribe/cli/options.rb', line 404

def define_quiet_option(opts, options)
  opts.on('-q', '--quiet', 'Only show status, no details') do
    options[:quiet] = true
  end
end

.define_rbi_dir_option(opts, options) ⇒ void

Note:

module_function: defines #define_rbi_dir_option (visibility: private)

This method returns an undefined value.

Define rbi dir option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



250
251
252
253
254
255
 
# File 'lib/docscribe/cli/options.rb', line 250

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(opts, options) ⇒ void

Note:

module_function: defines #define_rbs_collection_option (visibility: private)

This method returns an undefined value.

Define rbs collection option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



263
264
265
266
267
268
 
# File 'lib/docscribe/cli/options.rb', line 263

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_rbs_option(opts, options) ⇒ void

Note:

module_function: defines #define_rbs_option (visibility: private)

This method returns an undefined value.

Define rbs option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



213
214
215
216
217
 
# File 'lib/docscribe/cli/options.rb', line 213

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_server_option(opts, options) ⇒ void

Note:

module_function: defines #define_server_option (visibility: private)

This method returns an undefined value.

Define server option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



187
188
189
190
191
 
# File 'lib/docscribe/cli/options.rb', line 187

def define_server_option(opts, options)
  opts.on('--server', 'Use background server for faster repeated runs') do
    options[:server] = true
  end
end

.define_sig_dir_option(opts, options) ⇒ void

Note:

module_function: defines #define_sig_dir_option (visibility: private)

This method returns an undefined value.

Define sig dir option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



225
226
227
228
229
230
 
# File 'lib/docscribe/cli/options.rb', line 225

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(opts, options) ⇒ void

Note:

module_function: defines #define_sorbet_option (visibility: private)

This method returns an undefined value.

Define sorbet option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



238
239
240
241
242
 
# File 'lib/docscribe/cli/options.rb', line 238

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_stdin_option(opts, options) ⇒ void

Note:

module_function: defines #define_stdin_option (visibility: private)

This method returns an undefined value.

Define stdin option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



163
164
165
166
167
 
# File 'lib/docscribe/cli/options.rb', line 163

def define_stdin_option(opts, options)
  opts.on('--stdin', 'Read code from STDIN and print rewritten output') do
    options[:stdin] = true
  end
end

.define_type_options(opts, options) ⇒ void

Note:

module_function: defines #define_type_options (visibility: private)

This method returns an undefined value.

Define type options

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



199
200
201
202
203
204
205
 
# File 'lib/docscribe/cli/options.rb', line 199

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_verbose_option(opts, options) ⇒ void

Note:

module_function: defines #define_verbose_option (visibility: private)

This method returns an undefined value.

Define verbose option

Parameters:

  • opts (OptionParser) —

    the option parser to configure

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash



355
356
357
358
359
360
 
# File 'lib/docscribe/cli/options.rb', line 355

def define_verbose_option(opts, options)
  opts.on('--verbose', 'Print per-file actions') do
    options[:verbose] = true
    options[:progress] = true
  end
end

.looks_like_file_pattern?(pat) ⇒ Boolean

Note:

module_function: defines #looks_like_file_pattern? (visibility: private)

Heuristically decide whether a pattern looks like a file path or file glob.

Regex syntax (/.../) is intentionally treated as a method-id pattern, not a file pattern.

Parameters:

  • pat (String) —

    pattern passed via CLI

Returns:

  • (Boolean) 


512
513
514
515
516
517
 
# File 'lib/docscribe/cli/options.rb', line 512

def looks_like_file_pattern?(pat)
  return false if pat.start_with?('/') && pat.end_with?('/') && pat.length >= 2
  return false if pat.match?(%r{\A\*/})

  pat.include?('/') || pat.include?('**') || pat.end_with?('.rb')
end

.parse!(argv) ⇒ Docscribe::CLI::Formatters::opts

Note:

module_function: defines #parse! (visibility: private)

Parse CLI arguments into normalized Docscribe runtime options.

CLI behavior model:

  • default: inspect mode using the safe strategy
  • -a / --autocorrect: write mode using the safe strategy
  • -A / --autocorrect-all: write mode using the aggressive strategy
  • --stdin: stdin mode using the selected strategy (safe by default)

Filtering, config, verbosity, and external type options are applied orthogonally.

Parameters:

  • argv (Array<String>) —

    raw CLI arguments

Returns:

  • (Docscribe::CLI::Formatters::opts) —

    normalized runtime options



102
103
104
105
106
107
108
109
 
# File 'lib/docscribe/cli/options.rb', line 102

def parse!(argv)
  options = Marshal.load(Marshal.dump(DEFAULT))
  autocorrect = { mode: nil }

  build_option_parser(options, autocorrect).parse!(argv)
  resolve_mode_and_strategy!(options, autocorrect[:mode])
  options
end

.resolve_mode_and_strategy!(options, autocorrect_mode) ⇒ void

Note:

module_function: defines #resolve_mode_and_strategy! (visibility: private)

This method returns an undefined value.

Set the runtime mode and strategy after all options have been parsed.

Parameters:

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash

  • autocorrect_mode (Symbol, nil) —

    autocorrect mode selected (:safe, :aggressive, or nil)



473
474
475
476
477
478
479
480
481
482
483
484
 
# File 'lib/docscribe/cli/options.rb', line 473

def resolve_mode_and_strategy!(options, autocorrect_mode)
  if options[:stdin]
    options[:mode] = :stdin
    options[:strategy] = autocorrect_mode || :safe
  elsif autocorrect_mode
    options[:mode] = :write
    options[:strategy] = autocorrect_mode
  else
    options[:mode] = :check
    options[:strategy] = :safe
  end
end

.route_include_exclude(options, kind, value) ⇒ void

Note:

module_function: defines #route_include_exclude (visibility: private)

This method returns an undefined value.

Route an include/exclude pattern into method filters or file filters.

Regex-looking patterns (/…/) are treated as method-id filters. File-like patterns are routed into *_file.

Parameters:

  • options (Hash<Symbol, Object>) —

    mutable parsed options hash

  • kind (Symbol) —

    either :include or :exclude

  • value (String) —

    raw pattern from the CLI



496
497
498
499
500
501
502
 
# File 'lib/docscribe/cli/options.rb', line 496

def route_include_exclude(options, kind, value)
  if looks_like_file_pattern?(value)
    options[:"#{kind}_file"] << value
  else
    options[kind] << value
  end
end