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,
  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


  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) 


114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/docscribe/cli/options.rb', line 114

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)



132
133
134
135
136
137
138
139
140
 
# File 'lib/docscribe/cli/options.rb', line 132

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



172
173
174
175
176
 
# File 'lib/docscribe/cli/options.rb', line 172

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



323
324
325
326
327
 
# File 'lib/docscribe/cli/options.rb', line 323

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



298
299
300
301
302
303
 
# File 'lib/docscribe/cli/options.rb', line 298

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



376
377
378
379
380
 
# File 'lib/docscribe/cli/options.rb', line 376

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



273
274
275
276
277
278
 
# File 'lib/docscribe/cli/options.rb', line 273

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



400
401
402
403
404
405
 
# File 'lib/docscribe/cli/options.rb', line 400

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



311
312
313
314
315
 
# File 'lib/docscribe/cli/options.rb', line 311

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



286
287
288
289
290
 
# File 'lib/docscribe/cli/options.rb', line 286

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



148
149
150
151
152
 
# File 'lib/docscribe/cli/options.rb', line 148

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



413
414
415
416
417
418
 
# File 'lib/docscribe/cli/options.rb', line 413

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



438
439
440
441
442
443
444
445
446
447
448
449
 
# File 'lib/docscribe/cli/options.rb', line 438

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



426
427
428
429
430
431
 
# File 'lib/docscribe/cli/options.rb', line 426

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



335
336
337
338
339
340
341
342
343
 
# File 'lib/docscribe/cli/options.rb', line 335

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_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



364
365
366
367
368
 
# File 'lib/docscribe/cli/options.rb', line 364

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



388
389
390
391
392
 
# File 'lib/docscribe/cli/options.rb', line 388

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



247
248
249
250
251
252
 
# File 'lib/docscribe/cli/options.rb', line 247

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



260
261
262
263
264
265
 
# File 'lib/docscribe/cli/options.rb', line 260

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



210
211
212
213
214
 
# File 'lib/docscribe/cli/options.rb', line 210

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



184
185
186
187
188
 
# File 'lib/docscribe/cli/options.rb', line 184

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



222
223
224
225
226
227
 
# File 'lib/docscribe/cli/options.rb', line 222

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



235
236
237
238
239
 
# File 'lib/docscribe/cli/options.rb', line 235

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



160
161
162
163
164
 
# File 'lib/docscribe/cli/options.rb', line 160

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



196
197
198
199
200
201
202
 
# File 'lib/docscribe/cli/options.rb', line 196

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



351
352
353
354
355
356
 
# File 'lib/docscribe/cli/options.rb', line 351

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) 


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

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



99
100
101
102
103
104
105
106
 
# File 'lib/docscribe/cli/options.rb', line 99

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)



457
458
459
460
461
462
463
464
465
466
467
468
 
# File 'lib/docscribe/cli/options.rb', line 457

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



480
481
482
483
484
485
486
 
# File 'lib/docscribe/cli/options.rb', line 480

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