Module: Docscribe::CLI::Run

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

Overview

Execute Docscribe from parsed CLI options.

This module handles:

  • config loading and CLI overrides
  • stdin mode
  • file expansion / filtering
  • inspect vs write behavior
  • process exit status

Constant Summary collapse

INITIAL_RUN_STATE = 
{
  changed: false,
  had_errors: false,
  checked_ok: 0,
  checked_fail: 0,
  corrected: 0,
  corrected_paths: [], #: Array[String]
  corrected_changes: {}, #: Hash[String, untyped]
  fail_paths: [], #: Array[String]
  fail_changes: {}, #: Hash[String, untyped]
  error_paths: [], #: Array[String]
  error_messages: {}, #: Hash[String, String]
  type_mismatch_paths: [], #: Array[String]
  type_mismatch_changes: {}, #: Hash[String, untyped]
  total: 0,
  processed: 0
}.freeze
PARALLEL_DEFAULT_THREADS = 
4
CLI_OVERRIDE_KEYS = 
%i[
  keep_descriptions no_boilerplate
  include exclude include_file exclude_file
  rbs rbs_collection sig_dirs
  sorbet rbi_dirs
  validate_types
].freeze

Class Method Summary collapse

Class Method Details

.all_fine?(state, checked_error, type_mismatch_count) ⇒ Boolean

Whether no failures, errors, or type mismatches occurred.

Parameters:

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

    shared processing state

  • checked_error (Integer) —

    number of files with errors

  • type_mismatch_count (Integer) —

    number of files with type mismatches

Returns:

  • (Boolean) 


1057
1058
1059
 
# File 'lib/docscribe/cli/run.rb', line 1057

def all_fine?(state, checked_error, type_mismatch_count)
  state[:checked_fail].zero? && checked_error.zero? && type_mismatch_count.zero?
end

.append_expanded_path(files, path) ⇒ void

This method returns an undefined value.

Append a file or recursively expand a directory into the files array.

Parameters:

  • files (Array<String>) —

    mutable file path accumulator

  • path (String) —

    file or directory path to expand



366
367
368
369
370
371
372
373
374
 
# File 'lib/docscribe/cli/run.rb', line 366

def append_expanded_path(files, path)
  if File.directory?(path)
    files.concat(Dir.glob(File.join(path, '**', '*.rb')))
  elsif File.file?(path)
    files << path
  else
    warn "Skipping missing path: #{path}"
  end
end

.build_config(options) ⇒ Docscribe::Config

Parameters:

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

Returns:



115
116
117
118
119
120
 
# File 'lib/docscribe/cli/run.rb', line 115

def build_config(options)
  conf = Docscribe::Config.load(options[:config])
  conf = Docscribe::CLI::ConfigBuilder.build(conf, options)
  conf.load_plugins!
  conf
end

.build_failure_line(state, type_mismatch_count, checked_error) ⇒ String

Build the human-readable failure summary line for check output.

Parameters:

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

    shared processing state

  • type_mismatch_count (Integer) —

    number of files with type mismatches

  • checked_error (Integer) —

    number of files with errors

Returns:

  • (String) 


1076
1077
1078
1079
1080
1081
1082
 
# File 'lib/docscribe/cli/run.rb', line 1076

def build_failure_line(state, type_mismatch_count, checked_error)
  parts = ["#{state[:checked_fail]} need updates"]
  parts << "#{type_mismatch_count} type mismatches" if type_mismatch_count.positive?
  parts << "#{checked_error} errors"
  parts << "#{state[:checked_ok]} ok"
  "Docscribe: FAILED (#{parts.join(', ')})"
end

.build_light_config(options) ⇒ Docscribe::Config

Parameters:

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

Returns:



124
125
126
127
 
# File 'lib/docscribe/cli/run.rb', line 124

def build_light_config(options)
  conf = Docscribe::Config.load(options[:config])
  Docscribe::CLI::ConfigBuilder.build(conf, options)
end

.change_line_suffix(change) ⇒ String

Format the line number suffix for a change reason string.

Parameters:

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

    structured change record

Returns:

  • (String) —

    " at line N" or empty



1154
1155
1156
 
# File 'lib/docscribe/cli/run.rb', line 1154

def change_line_suffix(change)
  change[:line] ? " at line #{change[:line]}" : ''
end

.change_method_suffix(change) ⇒ String

Format the method name suffix for a change reason string.

Parameters:

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

    structured change record

Returns:

  • (String) —

    " for method_name" or empty



1162
1163
1164
 
# File 'lib/docscribe/cli/run.rb', line 1162

def change_method_suffix(change)
  change[:method] ? " for #{change[:method]}" : ''
end

.core_rbs_provider_for(conf) ⇒ Docscribe::Types::RBS::Provider?

Return the core RBS provider from the config if available.

Parameters:

Returns:



164
165
166
 
# File 'lib/docscribe/cli/run.rb', line 164

def core_rbs_provider_for(conf)
  conf.respond_to?(:core_rbs_provider) ? conf.core_rbs_provider : nil
end

.direct_message_change?(change) ⇒ Boolean

Whether a change type uses its own :message field directly as the reason.

Parameters:

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

    structured change record

Returns:

  • (Boolean) 


1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
 
# File 'lib/docscribe/cli/run.rb', line 1170

def direct_message_change?(change)
  %i[
    missing_param
    missing_return
    missing_raise
    missing_visibility
    missing_module_function_note
    insert_full_doc_block
  ].include?(change[:type])
end

.dispatch_server_result(result, file_changes, path, **ctx) ⇒ void

This method returns an undefined value.

Dispatch the server result to check or write handler.

Parameters:

  • result (Hash<String, Object>) —

    server result with :changed and :changes keys

  • file_changes (Array<Docscribe::CLI::Formatters::change>) —

    change records

  • path (String) —

    file path

  • ctx (Docscribe::CLI::Run::run_ctx) —

    context hash with :display_path, :options, :state keys



249
250
251
252
253
254
255
256
257
258
 
# File 'lib/docscribe/cli/run.rb', line 249

def dispatch_server_result(result, file_changes, path, **ctx)
  if ctx[:options][:mode] == :check
    handle_via_server_check(path, file_changes: file_changes,
                                  display_path: ctx[:display_path],
                                  options: ctx[:options], state: ctx[:state])
  else
    write_server_result(result, file_changes, display_path: ctx[:display_path],
                                              options: ctx[:options], state: ctx[:state])
  end
end

.ensure_server_running!(config_path: nil) ⇒ void

This method returns an undefined value.

Ensure the server daemon is running, auto-starting if necessary.

Parameters:

  • config_path (String?) (defaults to: nil) 


189
190
191
 
# File 'lib/docscribe/cli/run.rb', line 189

def ensure_server_running!(config_path: nil)
  Docscribe::Server.ensure_running!(config_path: config_path)
end

.expand_paths(args) ⇒ Array<String>

Expand CLI path arguments into a sorted list of Ruby files.

Directories are expanded recursively to **/*.rb. If no arguments are provided, the current directory is used.

Parameters:

  • args (Array<String>) —

    file and/or directory arguments

Returns:

  • (Array<String>) —

    unique sorted Ruby file paths



350
351
352
353
354
355
356
357
358
359
 
# File 'lib/docscribe/cli/run.rb', line 350

def expand_paths(args)
  files = [] #: Array[String]
  args = ['.'] if args.empty?

  args.each do |path|
    append_expanded_path(files, path)
  end

  files.uniq.sort
end

.extract_cli_overrides(options) ⇒ Hash<String, Object>

Parameters:

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

Returns:

  • (Hash<String, Object>) 


540
541
542
543
544
545
546
547
548
549
550
 
# File 'lib/docscribe/cli/run.rb', line 540

def extract_cli_overrides(options)
  overrides = options.slice(*CLI_OVERRIDE_KEYS)
  acc = {} #: Hash[String, untyped]
  overrides.each do |k, v|
    next if v.nil? || v == false
    next if v.is_a?(Array) && v.empty?

    acc[k.to_s] = v
  end
  acc
end

.fetch_work(paths, mutex) ⇒ String?

Parameters:

  • paths (Array<String>)
  • mutex (Thread::Mutex)

Returns:

  • (String?) 


451
452
453
454
455
 
# File 'lib/docscribe/cli/run.rb', line 451

def fetch_work(paths, mutex)
  path = nil
  mutex.synchronize { path = paths.shift }
  path
end

.filtered_paths(argv, conf) ⇒ Array<String>

Expand CLI path arguments and filter through config file patterns.

Parameters:

  • argv (Array<String>) —

    CLI path arguments

  • conf (Docscribe::Config) —

    effective config

Returns:

  • (Array<String>) —

    filtered Ruby file paths



173
174
175
 
# File 'lib/docscribe/cli/run.rb', line 173

def filtered_paths(argv, conf)
  expand_paths(argv).select { |path| conf.process_file?(path) }
end

.format_change_reason(change) ⇒ String

Format a structured change record into human-readable CLI output.

Parameters:

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

    structured change produced by the inline rewriter

Returns:

  • (String) —

    human-readable explanation line



1140
1141
1142
1143
1144
1145
1146
1147
1148
 
# File 'lib/docscribe/cli/run.rb', line 1140

def format_change_reason(change)
  line = change_line_suffix(change)
  method = change_method_suffix(change)

  return "unsorted tags#{line}" if change[:type] == :unsorted_tags
  return "#{change[:message]}#{method}#{line}" if direct_message_change?(change)

  "#{change[:message] || change[:type].to_s.tr('_', ' ')}#{method}#{line}"
end

.handle_via_server_check(path, file_changes:, display_path:, options:, state:) ⇒ void

This method returns an undefined value.

Handle a check result from the server.

Parameters:

  • path (String) —

    file path

  • file_changes (Array<Docscribe::CLI::Formatters::change>) —

    change records from server

  • display_path (String) —

    path shown in CLI output

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

    CLI options

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

    shared processing state



287
288
289
290
291
292
293
294
295
 
# File 'lib/docscribe/cli/run.rb', line 287

def handle_via_server_check(path, file_changes:, display_path:, options:, state:)
  if file_changes.empty?
    state[:checked_ok] += 1
    return log_check_verdict('OK', display_path, options)
  end

  report_check_failure(display_path, file_changes, options)
  update_check_failure_state(path, file_changes, state)
end

.handle_worker_error(exception, path, state, error_mutex) ⇒ void

This method returns an undefined value.

Parameters:

  • exception (StandardError)
  • path (String)
  • state (Docscribe::CLI::Formatters::state)
  • error_mutex (Thread::Mutex) 


475
476
477
478
479
480
481
482
 
# File 'lib/docscribe/cli/run.rb', line 475

def handle_worker_error(exception, path, state, error_mutex)
  error_mutex.synchronize do
    state[:had_errors] = true
    state[:error_paths] << path
    state[:error_messages][path] = "#{exception.class}: #{exception.message}"
  end
  $stderr.print('E')
end

.merge_state(target, source, mutex) ⇒ void

This method returns an undefined value.

Merge a thread-local state into the shared state under mutex protection.

Parameters:

  • target (Docscribe::CLI::Formatters::state) —

    shared state to merge into

  • source (Docscribe::CLI::Formatters::state) —

    thread-local state to merge from

  • mutex (Thread::Mutex) —

    mutex protecting the target state



490
491
492
493
494
495
496
497
 
# File 'lib/docscribe/cli/run.rb', line 490

def merge_state(target, source, mutex)
  mutex.synchronize do
    merge_state_flags(target, source)
    merge_state_counts(target, source)
    merge_state_arrays(target, source)
    merge_state_hashes(target, source)
  end
end

.merge_state_arrays(target, source) ⇒ void

This method returns an undefined value.

Parameters:

  • target (Docscribe::CLI::Formatters::state)
  • source (Docscribe::CLI::Formatters::state) 


520
521
522
523
524
525
 
# File 'lib/docscribe/cli/run.rb', line 520

def merge_state_arrays(target, source)
  target[:corrected_paths].concat(source[:corrected_paths])
  target[:fail_paths].concat(source[:fail_paths])
  target[:error_paths].concat(source[:error_paths])
  target[:type_mismatch_paths].concat(source[:type_mismatch_paths])
end

.merge_state_counts(target, source) ⇒ void

This method returns an undefined value.

Parameters:

  • target (Docscribe::CLI::Formatters::state)
  • source (Docscribe::CLI::Formatters::state) 


510
511
512
513
514
515
 
# File 'lib/docscribe/cli/run.rb', line 510

def merge_state_counts(target, source)
  target[:checked_ok] += source[:checked_ok]
  target[:checked_fail] += source[:checked_fail]
  target[:corrected] += source[:corrected]
  target[:processed] += source[:processed]
end

.merge_state_flags(target, source) ⇒ void

This method returns an undefined value.

Parameters:

  • target (Docscribe::CLI::Formatters::state)
  • source (Docscribe::CLI::Formatters::state) 


502
503
504
505
 
# File 'lib/docscribe/cli/run.rb', line 502

def merge_state_flags(target, source)
  target[:changed] ||= source[:changed]
  target[:had_errors] ||= source[:had_errors]
end

.merge_state_hashes(target, source) ⇒ void

This method returns an undefined value.

Parameters:

  • target (Docscribe::CLI::Formatters::state)
  • source (Docscribe::CLI::Formatters::state) 


530
531
532
533
534
535
536
 
# File 'lib/docscribe/cli/run.rb', line 530

def merge_state_hashes(target, source)
  %i[corrected_changes fail_changes error_messages type_mismatch_changes].each do |key|
    t = target[key] #: Hash[String, untyped]
    s = source[key] #: Hash[String, untyped]
    s.each { |k, v| t[k] = v }
  end
end

.mismatch_only?(state, checked_error) ⇒ Boolean

Whether type mismatches exist but no failures or errors.

Parameters:

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

    shared processing state

  • checked_error (Integer) —

    number of files with errors

Returns:

  • (Boolean) 


1066
1067
1068
 
# File 'lib/docscribe/cli/run.rb', line 1066

def mismatch_only?(state, checked_error)
  state[:checked_fail].zero? && checked_error.zero?
end

.no_files_found ⇒ Integer

Warn and return exit code when no matching files were found.

Returns:

  • (Integer) —

    exit code 2



180
181
182
183
 
# File 'lib/docscribe/cli/run.rb', line 180

def no_files_found
  warn 'No files found. Pass files or directories (e.g. `docscribe lib`).'
  2
end

.parallel_worker(pool) ⇒ Thread

Parameters:

  • pool (Docscribe::CLI::Run::pool)

Returns:

  • (Thread) 


439
440
441
442
443
444
445
446
 
# File 'lib/docscribe/cli/run.rb', line 439

def parallel_worker(pool)
  Thread.new do
    loop do
      path = fetch_work(pool[:paths], pool[:mutex]) or break
      run_and_merge(path, pool)
    end
  end
end

.print_check_status_line(state) ⇒ void

This method returns an undefined value.

Print the check-mode status line.

Parameters:

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

    shared processing state



1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
 
# File 'lib/docscribe/cli/run.rb', line 1038

def print_check_status_line(state)
  checked_error = state[:error_paths].size
  type_mismatch_count = state[:type_mismatch_paths].size

  if all_fine?(state, checked_error, type_mismatch_count)
    puts "Docscribe: OK (#{state[:checked_ok]} files checked)"
  elsif mismatch_only?(state, checked_error)
    puts "Docscribe: OK (#{state[:checked_ok]} files checked, #{type_mismatch_count} with type mismatches)"
  else
    puts build_failure_line(state, type_mismatch_count, checked_error)
  end
end

.print_corrected_paths(state, options) ⇒ void

This method returns an undefined value.

Print corrected paths from write-mode summary (stdout).

Skips explanations when --verbose showed them inline per-file.

Parameters:

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

    shared processing state

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

    CLI options



1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
 
# File 'lib/docscribe/cli/run.rb', line 1124

def print_corrected_paths(state, options)
  state[:corrected_paths].each do |p|
    puts "Updated: #{p}"

    next if options[:verbose] || options[:quiet]

    Array(state[:corrected_changes][p]).each do |change|
      puts "  - #{format_change_reason(change)}"
    end
  end
end

.print_error_paths(state) ⇒ void

This method returns an undefined value.

Print error paths from check summary.

Parameters:

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

    shared processing state



1185
1186
1187
1188
1189
1190
1191
1192
1193
 
# File 'lib/docscribe/cli/run.rb', line 1185

def print_error_paths(state)
  return if state[:error_paths].empty?

  warn ''
  state[:error_paths].each do |p|
    warn "Error processing: #{p}"
    warn "  #{state[:error_messages][p]}" if state[:error_messages][p]
  end
end

.print_fail_paths(state, options) ⇒ void

This method returns an undefined value.

Print fail paths from check summary (stdout).

Skips explanations when --verbose showed them inline per-file.

Parameters:

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

    shared processing state

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

    CLI options



1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
 
# File 'lib/docscribe/cli/run.rb', line 1022

def print_fail_paths(state, options)
  state[:fail_paths].each do |p|
    puts "Would update: #{p}"

    next if options[:verbose] || options[:quiet]

    Array(state[:fail_changes][p]).each do |change|
      puts "  - #{format_change_reason(change)}"
    end
  end
end

.print_type_mismatch_paths(state, options) ⇒ void

This method returns an undefined value.

Print type mismatch paths from check summary.

Parameters:

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

    shared processing state

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

    CLI options



1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
 
# File 'lib/docscribe/cli/run.rb', line 1089

def print_type_mismatch_paths(state, options)
  return if options[:quiet]
  return unless options[:verbose] || options[:explain]

  state[:type_mismatch_paths].each do |p|
    warn "Type mismatches: #{p}"
    Array(state[:type_mismatch_changes][p]).each do |change|
      warn "  - #{format_change_reason(change)}"
    end
  end
end

.print_write_summary(state:, options:) ⇒ void

This method returns an undefined value.

Print the write-mode summary (files corrected, errors).

Parameters:

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

    shared processing state

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

    CLI options



1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
 
# File 'lib/docscribe/cli/run.rb', line 1106

def print_write_summary(state:, options:)
  puts
  puts "Docscribe: updated #{state[:corrected]} file(s)" if state[:corrected].positive?
  print_corrected_paths(state, options)

  return unless state[:had_errors]

  warn "Docscribe: #{state[:error_paths].size} file(s) had errors"
  print_error_paths(state)
end

.process_one_file_via_server(client, path, options:, pwd:, state:) ⇒ void

This method returns an undefined value.

Process a single file via the server client.

Parameters:

  • client (Docscribe::Server::Client) —

    server client

  • path (String) —

    file path

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

    CLI options

  • pwd (Pathname) —

    current working directory

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

    shared processing state



201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/docscribe/cli/run.rb', line 201

def process_one_file_via_server(client, path, options:, pwd:, state:)
  display_path = display_path_for(path, pwd: pwd)
  report_progress(state, options, display_path)
  response = send_server_request(client, path, options)
  return server_error(path, state, 'Server unreachable') unless response
  return server_error(path, state, response['error']['message']) if response['error']

  result = response['result']
  file_changes = (result['changes'] || []).map { |c| symbolize_change(c) }
  dispatch_server_result(result, file_changes, path,
                         display_path: display_path, options: options, state: state)
end

.report_check_failure(display_path, file_changes, options) ⇒ void

This method returns an undefined value.

Report a check failure with verbose or compact output.

Parameters:

  • display_path (String) —

    path shown in CLI output

  • file_changes (Array<Docscribe::CLI::Formatters::change>) —

    change records from server

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

    CLI options



303
304
305
306
307
308
309
310
 
# File 'lib/docscribe/cli/run.rb', line 303

def report_check_failure(display_path, file_changes, options)
  if options[:verbose]
    warn("FAIL #{display_path}")
    print_check_explanations(file_changes)
  else
    $stderr.print('F')
  end
end

.run(options:, argv:) ⇒ Integer

Run Docscribe for files or STDIN using the selected mode and strategy.

Modes:

  • :check => inspect what the selected strategy would change
  • :write => apply the selected strategy in place
  • :stdin => rewrite STDIN and print to STDOUT

Strategies:

  • :safe => merge/add/normalize non-destructively
  • :aggressive => rebuild existing doc blocks

Parameters:

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

    parsed CLI options

  • argv (Array<String>) —

    remaining path arguments

Returns:

  • (Integer) —

    process exit code



62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/docscribe/cli/run.rb', line 62

def run(options:, argv:)
  return run_via_server(options: options, argv: argv) if options[:server]

  require 'docscribe/inline_rewriter'
  conf = build_config(options)

  return run_stdin(options: options, conf: conf) if options[:mode] == :stdin

  paths = filtered_paths(argv, conf)
  return no_files_found unless paths.any?

  run_files(options: options, conf: conf, paths: paths)
end

.run_and_merge(path, pool) ⇒ void, Object

Parameters:

  • path (String)
  • pool (Docscribe::CLI::Run::pool)

Returns:

  • (void)
  • (Object) —

    if StandardError

Raises:

  • (StandardError) 


462
463
464
465
466
467
468
 
# File 'lib/docscribe/cli/run.rb', line 462

def run_and_merge(path, pool)
  local_state = initial_run_state
  process_one_file(path, options: pool[:options], conf: pool[:conf], pwd: pool[:pwd], state: local_state)
  merge_state(pool[:state], local_state, pool[:error_mutex])
rescue StandardError => e
  handle_worker_error(e, path, pool[:state], pool[:error_mutex])
end

.run_files(options:, conf:, paths:) ⇒ Integer

Process file paths in inspect or write mode.

In inspect mode:

  • prints progress/status
  • exits non-zero if any file would change or if any errors occurred

In write mode:

  • rewrites changed files in place
  • exits non-zero only if errors occurred

Parameters:

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

    parsed CLI options

  • conf (Docscribe::Config) —

    effective config

  • paths (Array<String>) —

    Ruby file paths to process

Returns:

  • (Integer) —

    process exit code



390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
 
# File 'lib/docscribe/cli/run.rb', line 390

def run_files(options:, conf:, paths:)
  return run_files_parallel(options: options, conf: conf, paths: paths) if options[:parallel] && paths.size > 1

  $stdout.sync = true

  state = initial_run_state
  state[:total] = paths.size
  pwd = Pathname.pwd

  paths.each do |path|
    process_one_file(path, options: options, conf: conf, pwd: pwd, state: state)
  end

  finalize_run(options, state)

  run_exit_code(options, state)
end

.run_files_parallel(options:, conf:, paths:) ⇒ Integer

Process files in parallel using a Thread pool.

Parameters:

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

    parsed CLI options

  • conf (Docscribe::Config) —

    effective config

  • paths (Array<String>) —

    Ruby file paths to process

Returns:

  • (Integer) —

    process exit code



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

def run_files_parallel(options:, conf:, paths:)
  $stdout.sync = true
  state = initial_run_state
  state[:total] = paths.size
  run_parallel_workers(options, conf, paths, state)
  finalize_run(options, state)
  run_exit_code(options, state)
end

.run_files_via_server(client, paths, options) ⇒ Integer

Run files through the server client with progress tracking.

Parameters:

  • client (Docscribe::Server::Client) —

    server client

  • paths (Array<String>) —

    file paths to process

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

    CLI options

Returns:

  • (Integer) —

    exit code



101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/docscribe/cli/run.rb', line 101

def run_files_via_server(client, paths, options)
  $stdout.sync = true
  state = initial_run_state
  state[:total] = paths.size
  pwd = Pathname.pwd
  paths.each do |path|
    process_one_file_via_server(client, path, options: options, pwd: pwd, state: state)
  end
  finalize_run(options, state)
  run_exit_code(options, state)
end

.run_parallel_workers(options, conf, paths, state) ⇒ void

This method returns an undefined value.

Parameters:

  • options (Docscribe::CLI::Formatters::opts)
  • conf (Docscribe::Config)
  • paths (Array<String>)
  • state (Docscribe::CLI::Formatters::state) 


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

def run_parallel_workers(options, conf, paths, state)
  pool = {
    paths: paths, state: state, options: options, conf: conf,
    pwd: Pathname.pwd, mutex: Mutex.new, error_mutex: Mutex.new
  }
  thread_count = [ENV.fetch('DOCSCRIBE_THREADS', PARALLEL_DEFAULT_THREADS).to_i, 1].max
  thread_count.times.map { parallel_worker(pool) }.each(&:join)
end

.run_stdin(options:, conf:) ⇒ Integer

Rewrite code from STDIN using the selected strategy and print the result.

Parameters:

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

    parsed CLI options

  • conf (Docscribe::Config) —

    effective config

Returns:

  • (Integer)
  • (Integer) —

    if StandardError

Raises:

  • (StandardError) 


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

def run_stdin(options:, conf:)
  puts stdin_rewrite_result(options, conf)[:output]
  0
rescue StandardError => e
  warn "Docscribe: Error processing stdin: #{e.class}: #{e.message}"
  1
end

.run_via_server(options:, argv:) ⇒ Integer

Parameters:

  • options (Docscribe::CLI::Formatters::opts)
  • argv (Array<String>)

Returns:

  • (Integer)
  • (Integer) —

    if RuntimeError

Raises:

  • (RuntimeError) 


81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/docscribe/cli/run.rb', line 81

def run_via_server(options:, argv:)
  require 'docscribe/server'
  conf = build_light_config(options)
  ensure_server_running!(config_path: conf.config_path)
  client = Docscribe::Server::Client.new(config_path: conf.config_path)
  paths = filtered_paths(argv, conf)
  return no_files_found unless paths.any?

  run_files_via_server(client, paths, options)
rescue RuntimeError => e
  warn e.message
  1
end

.send_server_request(client, path, options) ⇒ Hash<String, Object>?

Parameters:

Returns:

  • (Hash<String, Object>, nil) 


218
219
220
221
222
223
224
225
226
227
 
# File 'lib/docscribe/cli/run.rb', line 218

def send_server_request(client, path, options)
  method_name = options[:mode] == :write ? :fix : :check
  strategy = options[:strategy].to_s
  cli_overrides = extract_cli_overrides(options)
  if cli_overrides.empty?
    client.send(method_name, file: path, strategy: strategy)
  else
    client.send(method_name, file: path, strategy: strategy, cli_overrides: cli_overrides)
  end
end

.server_error(path, state, message) ⇒ void

This method returns an undefined value.

Record a server error in the shared state and print an indicator.

Parameters:

  • path (String) —

    file path

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

    shared processing state

  • message (String) —

    error message



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

def server_error(path, state, message)
  state[:had_errors] = true
  state[:error_paths] << path
  state[:error_messages][path] = message
  $stderr.print('E')
end

.stdin_rewrite_result(options, conf) ⇒ Docscribe::CLI::Run::rewrite_result

Rewrite STDIN input and return the result report.

Parameters:

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

    parsed CLI options

  • conf (Docscribe::Config) —

    effective config

Returns:

  • (Docscribe::CLI::Run::rewrite_result) —

    rewrite result with :output key



150
151
152
153
154
155
156
157
158
 
# File 'lib/docscribe/cli/run.rb', line 150

def stdin_rewrite_result(options, conf)
  Docscribe::InlineRewriter.rewrite_with_report(
    $stdin.read,
    strategy: options[:strategy],
    config: conf,
    core_rbs_provider: core_rbs_provider_for(conf),
    file: '(stdin)'
  )
end

.symbolize_change(change) ⇒ Docscribe::CLI::Formatters::change

Convert server response change (string keys) to formatter-compatible change (symbol keys).

Parameters:

  • change (Hash<String, Object>) —

    change record from server

Returns:

  • (Docscribe::CLI::Formatters::change) 


330
331
332
333
334
335
336
337
338
339
340
341
 
# File 'lib/docscribe/cli/run.rb', line 330

def symbolize_change(change) # steep:ignore
  hash = {
    type: change['type'].to_sym,
    file: change['file'],
    line: change['line'],
    method: change['method'],
    message: change['message'],
    source: change['source']
  }
  hash[:param] = change['param'] if change['param']
  hash.compact
end

.update_check_failure_state(path, file_changes, state) ⇒ void

This method returns an undefined value.

Update shared state after a check failure.

Parameters:

  • path (String) —

    file path

  • file_changes (Array<Docscribe::CLI::Formatters::change>) —

    change records from server

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

    shared processing state



318
319
320
321
322
323
 
# File 'lib/docscribe/cli/run.rb', line 318

def update_check_failure_state(path, file_changes, state)
  state[:checked_fail] += 1
  state[:changed] = true
  state[:fail_paths] << path
  state[:fail_changes][path] = file_changes
end

.write_server_result(result, file_changes, display_path:, options:, state:) ⇒ void

This method returns an undefined value.

Handle a server write-mode result.

Parameters:

  • result (Hash<String, Object>) —

    server result with :changed key

  • file_changes (Array<Docscribe::CLI::Formatters::change>) —

    change records

  • display_path (String) —

    path shown in CLI output

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

    CLI options

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

    shared processing state



268
269
270
271
272
273
274
275
276
277
 
# File 'lib/docscribe/cli/run.rb', line 268

def write_server_result(result, file_changes, display_path:, options:, state:)
  if result['changed']
    state[:corrected] += 1
    state[:corrected_paths] << display_path
    state[:corrected_changes][display_path] = file_changes
    log_check_verdict('CHANGED', display_path, options)
  else
    log_check_verdict('OK', display_path, options)
  end
end