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
}.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)

  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) 


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

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)



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

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



169
170
171
172
173
 
# File 'lib/docscribe/cli/options.rb', line 169

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



308
309
310
311
312
 
# File 'lib/docscribe/cli/options.rb', line 308

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



283
284
285
286
287
288
 
# File 'lib/docscribe/cli/options.rb', line 283

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



361
362
363
364
365
 
# File 'lib/docscribe/cli/options.rb', line 361

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



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

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



385
386
387
388
389
390
 
# File 'lib/docscribe/cli/options.rb', line 385

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



296
297
298
299
300
 
# File 'lib/docscribe/cli/options.rb', line 296

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



271
272
273
274
275
 
# File 'lib/docscribe/cli/options.rb', line 271

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



146
147
148
149
 
# File 'lib/docscribe/cli/options.rb', line 146

def define_input_options(opts, options)
  define_stdin_option(opts, options)
  define_config_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



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

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



423
424
425
426
427
428
429
430
431
432
433
434
 
# File 'lib/docscribe/cli/options.rb', line 423

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



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

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



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

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



349
350
351
352
353
 
# File 'lib/docscribe/cli/options.rb', line 349

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



373
374
375
376
377
 
# File 'lib/docscribe/cli/options.rb', line 373

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



232
233
234
235
236
237
 
# File 'lib/docscribe/cli/options.rb', line 232

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



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

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



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

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



207
208
209
210
211
212
 
# File 'lib/docscribe/cli/options.rb', line 207

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



220
221
222
223
224
 
# File 'lib/docscribe/cli/options.rb', line 220

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



157
158
159
160
161
 
# File 'lib/docscribe/cli/options.rb', line 157

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



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

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



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

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) 


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

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



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

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)



442
443
444
445
446
447
448
449
450
451
452
453
 
# File 'lib/docscribe/cli/options.rb', line 442

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



465
466
467
468
469
470
471
 
# File 'lib/docscribe/cli/options.rb', line 465

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