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



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

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



67
68
69
70
 
# File 'lib/docscribe/cli/config_builder.rb', line 67

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



89
90
91
92
93
 
# File 'lib/docscribe/cli/config_builder.rb', line 89

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



189
190
191
192
193
194
195
196
 
# File 'lib/docscribe/cli/config_builder.rb', line 189

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



144
145
146
147
148
149
150
151
152
153
 
# File 'lib/docscribe/cli/config_builder.rb', line 144

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



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

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



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

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

.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
 
# File 'lib/docscribe/cli/config_builder.rb', line 24

def build(base, options)
  return base 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)
  conf = Docscribe::Config.new(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) 


54
55
56
57
58
59
 
# File 'lib/docscribe/cli/config_builder.rb', line 54

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) 


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

def needs_override?(options)
  filter_overrides?(options) ||
    rbs_overrides?(options) ||
    sorbet_overrides?(options) ||
    output_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) 


174
175
176
 
# File 'lib/docscribe/cli/config_builder.rb', line 174

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) 


77
78
79
80
81
 
# File 'lib/docscribe/cli/config_builder.rb', line 77

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) 


134
135
136
137
 
# File 'lib/docscribe/cli/config_builder.rb', line 134

def sorbet_overrides?(options)
  options[:sorbet] ||
    options[:rbi_dirs].any?
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



207
208
209
210
211
212
213
214
215
 
# File 'lib/docscribe/cli/config_builder.rb', line 207

def warn_missing_rbs_collection(conf, options)
  return if options[: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