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

Class Method Summary collapse

Class Method Details

.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



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

def expand_paths(args)
  files = []
  args = ['.'] if args.empty?

  args.each do |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

  files.uniq.sort
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 (Hash) —

    parsed CLI options

  • argv (Array<String>) —

    remaining path arguments

Returns:

  • (Integer) —

    process exit code



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/docscribe/cli/run.rb', line 34

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

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

  paths = expand_paths(argv)
  paths = paths.select { |p| conf.process_file?(p) }

  if paths.empty?
    warn 'No files found. Pass files or directories (e.g. `docscribe lib`).'
    return 1
  end

  run_files(options: options, conf: conf, paths: paths)
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 (Hash) —

    parsed CLI options

  • conf (Docscribe::Config) —

    effective config

  • paths (Array<String>) —

    Ruby file paths to process

Returns:

  • (Integer) —

    process exit code



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/docscribe/cli/run.rb', line 113

def run_files(options:, conf:, paths:)
  $stdout.sync = true

  state = initial_run_state
  pwd = Pathname.pwd

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

  if options[:mode] == :check
    print_check_summary(state: state, options: options)
  elsif options[:mode] == :write
    print_write_summary(state: state)
  end

  return 1 if state[:had_errors]
  return 1 if options[:mode] == :check && state[:changed]

  0
end

.run_stdin(options:, conf:) ⇒ Integer

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

Parameters:

  • options (Hash) —

    parsed CLI options

  • conf (Docscribe::Config) —

    effective config

Returns:

  • (Integer) —

    process exit code

Raises:

  • (StandardError) 


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

def run_stdin(options:, conf:)
  code = $stdin.read
  result = Docscribe::InlineRewriter.rewrite_with_report(
    code,
    strategy: options[:strategy],
    config: conf,
    core_rbs_provider: conf.respond_to?(:core_rbs_provider) ? conf.core_rbs_provider : nil,
    file: '(stdin)'
  )
  puts result[:output]
  0
rescue StandardError => e
  warn "Docscribe: Error processing stdin: #{e.class}: #{e.message}"
  1
end