Module: Docscribe::CLI::ConfigBuilder

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

Overview

Build and override effective config from CLI flags.

Class Method Summary collapse

Class Method Details

.apply_file_filters(raw, options) ⇒ void

Note:

module_function: defines #apply_file_filters (visibility: private)

This method returns an undefined value.

Merge CLI file include/exclude patterns into the raw config hash.

Parameters:

  • raw (Hash<String, Object>) —

    raw config hash

  • options (Hash<Symbol, Object>) —

    parsed CLI options



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

def apply_file_filters(raw, options)
  files = raw['filter']['files']
  if files.nil?
    files = {} #: Hash[String, untyped]
    raw['filter']['files'] = files
  end

  files['include'] = Array(files['include']) + options[:include_file]
  files['exclude'] = Array(files['exclude']) + options[:exclude_file]
  files
end

.apply_filter_overrides(raw, options) ⇒ void

Note:

module_function: defines #apply_filter_overrides (visibility: private)

This method returns an undefined value.

Apply method and file filter overrides to the raw config.

Parameters:

  • raw (Hash<String, Object>) —

    raw config hash

  • options (Hash<Symbol, Object>) —

    parsed CLI options



82
83
84
85
 
# File 'lib/docscribe/cli/config_builder.rb', line 82

def apply_filter_overrides(raw, options)
  apply_method_filters(raw, options)
  apply_file_filters(raw, options)
end

.apply_method_filters(raw, options) ⇒ void

Note:

module_function: defines #apply_method_filters (visibility: private)

This method returns an undefined value.

Merge CLI method include/exclude patterns into the raw config hash.

Parameters:

  • raw (Hash<String, Object>) —

    raw config hash

  • options (Hash<Symbol, Object>) —

    parsed CLI options



104
105
106
107
108
 
# File 'lib/docscribe/cli/config_builder.rb', line 104

def apply_method_filters(raw, options)
  raw['filter'] ||= {}
  raw['filter']['include'] = Array(raw['filter']['include']) + options[:include]
  raw['filter']['exclude'] = Array(raw['filter']['exclude']) + options[:exclude]
end

.apply_output_overrides(raw, options) ⇒ void

Note:

module_function: defines #apply_output_overrides (visibility: private)

This method returns an undefined value.

Apply output-related CLI overrides to the raw config.

Currently handles:

  • keep_descriptions -> raw
  • no_boilerplate -> raw['include_default_message'] and raw['include_param_documentation'] = false

Parameters:

  • raw (Hash<String, Object>) —

    raw config hash

  • options (Hash<Symbol, Object>) —

    parsed CLI options



204
205
206
207
208
209
210
211
 
# File 'lib/docscribe/cli/config_builder.rb', line 204

def apply_output_overrides(raw, options)
  return unless options[:keep_descriptions] || options[:no_boilerplate]

  raw['keep_descriptions'] = true if options[:keep_descriptions]
  raw['emit'] ||= {}
  raw['emit']['include_default_message'] = false if options[:no_boilerplate]
  raw['emit']['include_param_documentation'] = false if options[:no_boilerplate]
end

.apply_rbs_collection(raw) ⇒ void

Note:

module_function: defines #apply_rbs_collection (visibility: private)

This method returns an undefined value.

Resolve and apply the RBS collection path into the raw config hash.

Parameters:

  • raw (Hash<String, Object>) —

    raw config hash



159
160
161
162
163
164
165
166
167
168
 
# File 'lib/docscribe/cli/config_builder.rb', line 159

def apply_rbs_collection(raw)
  require 'docscribe/types/rbs/collection_loader'
  collection_path = Docscribe::Types::RBS::CollectionLoader.resolve
  if collection_path
    raw['rbs']['collection_dirs'] = Array(raw['rbs']['collection_dirs']) + [collection_path]
  else
    warn 'Docscribe: rbs_collection.lock.yaml not found. ' \
         'Run `bundle exec rbs collection install` first.'
  end
end

.apply_rbs_overrides(raw, options) ⇒ void

Note:

module_function: defines #apply_rbs_overrides (visibility: private)

This method returns an undefined value.

Apply RBS-related CLI overrides to the raw config.

Parameters:

  • raw (Hash<String, Object>) —

    raw config hash

  • options (Hash<Symbol, Object>) —

    parsed CLI options



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

def apply_rbs_overrides(raw, options)
  raw['rbs'] ||= {}
  raw['rbs']['enabled'] = true
  raw['rbs']['sig_dirs'] = Array(raw['rbs']['sig_dirs']) + options[:sig_dirs] if options[:sig_dirs].any?

  return unless options[:rbs_collection]

  apply_rbs_collection(raw)
end

.apply_sorbet_overrides(raw, options) ⇒ void

Note:

module_function: defines #apply_sorbet_overrides (visibility: private)

This method returns an undefined value.

Apply Sorbet-related CLI overrides to the raw config.

Parameters:

  • raw (Hash<String, Object>) —

    raw config hash

  • options (Hash<Symbol, Object>) —

    parsed CLI options



176
177
178
179
180
181
182
 
# File 'lib/docscribe/cli/config_builder.rb', line 176

def apply_sorbet_overrides(raw, options)
  raw['sorbet'] ||= {}
  raw['sorbet']['enabled'] = true
  return unless options[:rbi_dirs].any?

  raw['sorbet']['rbi_dirs'] = Array(raw['sorbet']['rbi_dirs']) + options[:rbi_dirs]
end

.apply_validation_overrides(raw, options) ⇒ void

Note:

module_function: defines #apply_validation_overrides (visibility: private)

This method returns an undefined value.

Apply validation-related CLI overrides to the raw config.

Parameters:

  • raw (Hash<String, Object>) —

    raw config hash

  • options (Hash<Symbol, Object>) —

    parsed CLI options



228
229
230
 
# File 'lib/docscribe/cli/config_builder.rb', line 228

def apply_validation_overrides(raw, options)
  raw['validate_types'] = options[:validate_types]
end

.build(base, options) ⇒ Docscribe::Config

Note:

module_function: defines #build (visibility: private)

Build an effective config by applying CLI overrides on top of a base config.

CLI overrides currently affect:

  • method/file include and exclude filters
  • RBS enablement and additional signature directories
  • Sorbet enablement and RBI directories

If no relevant CLI override is present, the original config is returned unchanged.

Parameters:

  • base (Docscribe::Config) —

    base config loaded from YAML/defaults

  • options (Hash<Symbol, Object>) —

    parsed CLI options

Returns:



24
25
26
27
28
29
30
31
32
33
34
35
36
 
# File 'lib/docscribe/cli/config_builder.rb', line 24

def build(base, options)
  return warn_and_return_base(base, options) unless needs_override?(options)

  raw = Marshal.load(Marshal.dump(base.raw))
  apply_filter_overrides(raw, options)
  apply_rbs_overrides(raw, options) if rbs_overrides?(options)
  apply_sorbet_overrides(raw, options) if sorbet_overrides?(options)
  apply_output_overrides(raw, options)
  apply_validation_overrides(raw, options) if validation_overrides?(options)
  conf = Docscribe::Config.new(config_path: base.config_path, **raw)
  warn_missing_rbs_collection(conf, options)
  conf
end

.filter_overrides?(options) ⇒ Boolean

Note:

module_function: defines #filter_overrides? (visibility: private)

Whether any method or file filter CLI options were provided.

Parameters:

  • options (Hash<Symbol, Object>) —

    parsed CLI options

Returns:

  • (Boolean) 


69
70
71
72
73
74
 
# File 'lib/docscribe/cli/config_builder.rb', line 69

def filter_overrides?(options)
  options[:include].any? ||
    options[:exclude].any?      ||
    options[:include_file].any? ||
    options[:exclude_file].any?
end

.needs_override?(options) ⇒ Boolean

Note:

module_function: defines #needs_override? (visibility: private)

Whether any CLI override is present.

Parameters:

  • options (Hash<Symbol, Object>) —

    parsed CLI options

Returns:

  • (Boolean) 


43
44
45
46
47
48
49
 
# File 'lib/docscribe/cli/config_builder.rb', line 43

def needs_override?(options)
  filter_overrides?(options) ||
    rbs_overrides?(options) ||
    sorbet_overrides?(options) ||
    output_overrides?(options) ||
    validation_overrides?(options)
end

.output_overrides?(options) ⇒ Boolean

Note:

module_function: defines #output_overrides? (visibility: private)

Whether any output-related CLI options were provided.

Parameters:

  • options (Hash<Symbol, Object>) —

    parsed CLI options

Returns:

  • (Boolean) 


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

def output_overrides?(options)
  !!options[:keep_descriptions] || !!options[:no_boilerplate]
end

.rbs_overrides?(options) ⇒ Boolean

Note:

module_function: defines #rbs_overrides? (visibility: private)

Whether any RBS-related CLI options were provided.

Parameters:

  • options (Hash<Symbol, Object>) —

    parsed CLI options

Returns:

  • (Boolean) 


92
93
94
95
96
 
# File 'lib/docscribe/cli/config_builder.rb', line 92

def rbs_overrides?(options)
  options[:rbs] ||
    options[:rbs_collection] ||
    options[:sig_dirs].any?
end

.sorbet_overrides?(options) ⇒ Boolean

Note:

module_function: defines #sorbet_overrides? (visibility: private)

Whether any Sorbet-related CLI options were provided.

Parameters:

  • options (Hash<Symbol, Object>) —

    parsed CLI options

Returns:

  • (Boolean) 


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

def sorbet_overrides?(options)
  options[:sorbet] ||
    options[:rbi_dirs].any?
end

.validation_overrides?(options) ⇒ Boolean

Note:

module_function: defines #validation_overrides? (visibility: private)

Whether any validation-related CLI options were provided.

Parameters:

  • options (Hash<Symbol, Object>) —

    parsed CLI options

Returns:

  • (Boolean) 


218
219
220
 
# File 'lib/docscribe/cli/config_builder.rb', line 218

def validation_overrides?(options)
  !options[:validate_types].nil?
end

.warn_and_return_base(base, options) ⇒ Docscribe::Config

Note:

module_function: defines #warn_and_return_base (visibility: private)

Warn about a missing collection opt-in and return the base config unchanged.

Used when no CLI override is present so the nudge still fires on plain runs.

Parameters:

  • base (Docscribe::Config) —

    base config loaded from YAML/defaults

  • options (Hash<Symbol, Object>) —

    parsed CLI options

Returns:



59
60
61
62
 
# File 'lib/docscribe/cli/config_builder.rb', line 59

def warn_and_return_base(base, options)
  warn_missing_rbs_collection(base, options)
  base
end

.warn_missing_rbs_collection(conf, options) ⇒ void

Note:

module_function: defines #warn_missing_rbs_collection (visibility: private)

This method returns an undefined value.

Warn when rbs_collection.lock.yaml exists but --rbs-collection was not passed.

The warning can be suppressed by setting rbs.warn_missing_collection: false in the project's docscribe.yml.

Parameters:

  • conf (Docscribe::Config) —

    effective config

  • options (Hash<Symbol, Object>) —

    parsed CLI options



241
242
243
244
245
246
247
248
249
250
 
# File 'lib/docscribe/cli/config_builder.rb', line 241

def warn_missing_rbs_collection(conf, options)
  return if options[:rbs_collection]
  return if conf.raw.dig('rbs', 'collection')
  return unless conf.rbs_warn_missing_collection?
  return unless File.exist?('rbs_collection.lock.yaml')

  warn 'Docscribe: rbs_collection.lock.yaml found but --rbs-collection not set. ' \
       'Pass --rbs-collection or set `rbs.collection: true` in docscribe.yml to enable RBS collection. ' \
       'Set `rbs.warn_missing_collection: false` to suppress this warning.'
end