Class: Yard::Lint::Config

Inherits:
Object
  • Object
show all
Defined in:
lib/yard/lint/config.rb

Overview

Configuration object for YARD Lint

Constant Summary collapse

DEFAULT_CONFIG_FILE =

Default YAML config file name

'.yard-lint.yml'
VALID_SEVERITIES =

Valid severity levels for fail_on_severity

%w[error warning convention never].freeze
METADATA_KEYS =

Metadata keys to skip when merging validator configs

%w[Description StyleGuide VersionAdded VersionChanged].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(raw_config = {}) {|_self| ... } ⇒ Config

Returns a new instance of Config.

Parameters:

  • raw_config (Hash) (defaults to: {}) —

    raw configuration hash (new hierarchical format)

Yields:

  • (_self)

Yield Parameters:



21
22
23
24
25
26
27
28
29
30
31
 
# File 'lib/yard/lint/config.rb', line 21

def initialize(raw_config = {})
  @raw_config = raw_config

  # Validate configuration structure and values
  ConfigValidator.validate!(@raw_config) unless raw_config.empty?

  @validators = build_validators_config
  @only_validators = []

  yield self if block_given?
end

Instance Attribute Details

#only_validators ⇒ Object

Returns the value of attribute only_validators.



9
10
11
 
# File 'lib/yard/lint/config.rb', line 9

def only_validators
  @only_validators
end

#raw_config ⇒ Object (readonly)

Returns the value of attribute raw_config.



8
9
10
 
# File 'lib/yard/lint/config.rb', line 8

def raw_config
  @raw_config
end

#validators ⇒ Object (readonly)

Returns the value of attribute validators.



8
9
10
 
# File 'lib/yard/lint/config.rb', line 8

def validators
  @validators
end

Class Method Details

.find_config_file(start_path) ⇒ String?

Find config file by searching upwards from start_path

Parameters:

  • start_path (String) —

    directory to start searching from

Returns:

  • (String, nil) —

    path to config file if found



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/yard/lint/config.rb', line 60

def find_config_file(start_path)
  current = File.expand_path(start_path)
  root = File.expand_path('/')

  loop do
    config_path = File.join(current, DEFAULT_CONFIG_FILE)
    return config_path if File.exist?(config_path)

    break if current == root

    current = File.dirname(current)
  end

  nil
end

.from_file(path) ⇒ Yard::Lint::Config

Load configuration from a YAML file

Parameters:

  • path (String) —

    path to YAML config file

Returns:

Raises:



38
39
40
41
42
43
44
45
46
47
 
# File 'lib/yard/lint/config.rb', line 38

def from_file(path)
  unless File.exist?(path)
    raise Errors::ConfigFileNotFoundError, "Config file not found: #{path}"
  end

  # Load with inheritance support
  merged_yaml = ConfigLoader.load(path)

  new(merged_yaml)
end

.load(start_path: Dir.pwd) ⇒ Yard::Lint::Config?

Search for and load config file from current directory upwards

Parameters:

  • start_path (String) (defaults to: Dir.pwd) —

    directory to start searching from (default: current dir)

Returns:



52
53
54
55
 
# File 'lib/yard/lint/config.rb', line 52

def load(start_path: Dir.pwd)
  config_path = find_config_file(start_path)
  config_path ? from_file(config_path) : nil
end

Instance Method Details

#[](key) ⇒ Object?

Allow hash-like access for convenience

Parameters:

  • key (Symbol, String) —

    attribute name to access

Returns:

  • (Object, nil) —

    attribute value or nil if not found



241
242
243
 
# File 'lib/yard/lint/config.rb', line 241

def [](key)
  respond_to?(key) ? send(key) : nil
end

#all_validators ⇒ Hash

Get AllValidators section

Returns:

  • (Hash) —

    AllValidators configuration



271
272
273
 
# File 'lib/yard/lint/config.rb', line 271

def all_validators
  @raw_config['AllValidators'] || {}
end

#build_default_validator_config(validator_name) ⇒ Hash

Build default configuration for a validator

Parameters:

  • validator_name (String) —

    full validator name

Returns:

  • (Hash) —

    default configuration



299
300
301
302
303
304
305
306
307
 
# File 'lib/yard/lint/config.rb', line 299

def build_default_validator_config(validator_name)
  # Get defaults from validator config
  validator_cfg = ConfigLoader.validator_config(validator_name)
  defaults = validator_cfg&.defaults || {}
  base = ConfigLoader::DEFAULT_VALIDATOR_CONFIG.dup

  # Merge validator-specific defaults with base config
  base.merge(defaults)
end

#build_validators_config ⇒ Hash

Build validators configuration from raw config

Returns:

  • (Hash) —

    validators configuration



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
 
# File 'lib/yard/lint/config.rb', line 277

def build_validators_config
  config = {}

  # Start with defaults for all validators
  ConfigLoader::ALL_VALIDATORS.each do |validator_name|
    config[validator_name] = build_default_validator_config(validator_name)
  end

  # Apply validator-specific overrides
  @raw_config.each do |key, value|
    next unless key.include?('/') # Validator-specific config
    next unless ConfigLoader::ALL_VALIDATORS.include?(key)

    config[key] = merge_validator_config(config[key], value) if value.is_a?(Hash)
  end

  config
end

#default_exclusions ⇒ Array<String>

Default exclusion patterns for typical Ruby/Rails projects

Returns:

  • (Array<String>) —

    default exclusion patterns



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/yard/lint/config.rb', line 100

def default_exclusions
  [
    # Version control
    '\.git',
    # Dependencies
    'vendor/**/*',
    'node_modules/**/*',
    # Test directories
    'spec/**/*',
    'test/**/*',
    'features/**/*',
    # Temporary and cache directories
    'tmp/**/*',
    'log/**/*',
    'coverage/**/*',
    '.bundle/**/*',
    # Rails-specific
    'db/schema.rb',
    'db/migrate/**/*',
    'public/assets/**/*',
    'public/packs/**/*',
    'public/system/**/*',
    # Build artifacts
    'pkg/**/*',
    'doc/**/*',
    '.yardoc/**/*',
    # Configuration that doesn't need docs
    'config/initializers/**/*',
    'config/environments/**/*'
  ]
end

#diff_mode_default_base_ref ⇒ String?

Diff mode default base ref (main or master)

Returns:

  • (String, nil) —

    default base ref for diff mode



140
141
142
143
 
# File 'lib/yard/lint/config.rb', line 140

def diff_mode_default_base_ref
  diff_config = all_validators['DiffMode'] || {}
  diff_config['DefaultBaseRef']
end

#exclude ⇒ Array<String>

Global file exclusion patterns

Returns:

  • (Array<String>) —

    exclusion patterns



94
95
96
 
# File 'lib/yard/lint/config.rb', line 94

def exclude
  all_validators['Exclude'] || default_exclusions
end

#exclude=(value) ⇒ Object

Set global exclude patterns

Parameters:

  • value (Array<String>) —

    exclusion patterns



219
220
221
222
 
# File 'lib/yard/lint/config.rb', line 219

def exclude=(value)
  @raw_config['AllValidators'] ||= {}
  @raw_config['AllValidators']['Exclude'] = value
end

#fail_on_severity ⇒ String

Minimum severity level to fail on

Returns:

  • (String) —

    severity level (error, warning, convention, never)



134
135
136
 
# File 'lib/yard/lint/config.rb', line 134

def fail_on_severity
  all_validators['FailOnSeverity'] || 'warning'
end

#fail_on_severity=(value) ⇒ Object

Set fail on severity level

Parameters:

  • value (String) —

    severity level



226
227
228
229
 
# File 'lib/yard/lint/config.rb', line 226

def fail_on_severity=(value)
  @raw_config['AllValidators'] ||= {}
  @raw_config['AllValidators']['FailOnSeverity'] = value
end

#get_validator_config_with_default(validator_name, key) ⇒ Object?

Generic helper to get validator configuration with default fallback

Parameters:

  • validator_name (String) —

    full validator name

  • key (String) —

    configuration key

Returns:

  • (Object, nil) —

    configuration value or default



259
260
261
262
263
264
265
266
267
 
# File 'lib/yard/lint/config.rb', line 259

def get_validator_config_with_default(validator_name, key)
  value = validator_config(validator_name, key)
  # A nil? check (not ||) so that explicitly configured false values
  # are honored instead of falling back to a truthy default
  return value unless value.nil?

  validator_cfg = ConfigLoader.validator_config(validator_name)
  validator_cfg&.defaults&.dig(key)
end

#merge_validator_config(base, override) ⇒ Hash

Merge validator configuration

Parameters:

  • base (Hash) —

    base configuration

  • override (Hash) —

    overriding configuration

Returns:

  • (Hash) —

    merged configuration



313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
 
# File 'lib/yard/lint/config.rb', line 313

def merge_validator_config(base, override)
  result = base.dup

  override.each do |key, value|
    # Skip metadata keys
    next if METADATA_KEYS.include?(key)

    result[key] = if value.is_a?(Array) && result[key].is_a?(Array)
                    value # Array replacement
                  elsif value.is_a?(Hash) && result[key].is_a?(Hash)
                    result[key].merge(value)
                  else
                    value
                  end
  end

  result
end

#min_coverage ⇒ Float?

Minimum documentation coverage percentage required

Returns:

  • (Float, nil) —

    minimum coverage percentage (0-100) or nil if not set



147
148
149
 
# File 'lib/yard/lint/config.rb', line 147

def min_coverage
  all_validators['MinCoverage']
end

#min_coverage=(value) ⇒ Object

Set minimum coverage percentage

Parameters:

  • value (Float) —

    minimum coverage percentage (0-100)



233
234
235
236
 
# File 'lib/yard/lint/config.rb', line 233

def min_coverage=(value)
  @raw_config['AllValidators'] ||= {}
  @raw_config['AllValidators']['MinCoverage'] = value
end

#options ⇒ Array<String>

YARD command-line options

Returns:

  • (Array<String>) —

    YARD options



79
80
81
 
# File 'lib/yard/lint/config.rb', line 79

def options
  all_validators['YardOptions'] || []
end

#options=(value) ⇒ Object

Set YARD options

Parameters:

  • value (Array<String>) —

    YARD options



212
213
214
215
 
# File 'lib/yard/lint/config.rb', line 212

def options=(value)
  @raw_config['AllValidators'] ||= {}
  @raw_config['AllValidators']['YardOptions'] = value
end

#set_validator_config(validator_name, key, value) ⇒ Object

Generic helper to set validator configuration

Parameters:

  • validator_name (String) —

    full validator name (e.g., ‘Tags/Order’)

  • key (String) —

    configuration key

  • value (Object) —

    configuration value



249
250
251
252
253
 
# File 'lib/yard/lint/config.rb', line 249

def set_validator_config(validator_name, key, value)
  @raw_config[validator_name] ||= {}
  @raw_config[validator_name][key] = value
  @validators = build_validators_config
end

#validator_all_excludes(validator_name) ⇒ Array<String>

Combined global and per-validator exclusions Returns all exclusion patterns that apply to this validator

Parameters:

  • validator_name (String) —

    full validator name

Returns:

  • (Array<String>) —

    combined exclusion patterns (global + per-validator)



196
197
198
 
# File 'lib/yard/lint/config.rb', line 196

def validator_all_excludes(validator_name)
  exclude + validator_exclude(validator_name)
end

#validator_config(validator_name, key) ⇒ Object?

Get validator-specific configuration value

Parameters:

  • validator_name (String) —

    full validator name

  • key (String) —

    configuration key

Returns:

  • (Object, nil) —

    configuration value



204
205
206
 
# File 'lib/yard/lint/config.rb', line 204

def validator_config(validator_name, key)
  validators.dig(validator_name, key)
end

#validator_enabled?(validator_name) ⇒ Boolean

Check if a validator is enabled

Parameters:

  • validator_name (String) —

    full validator name (e.g., ‘Tags/Order’)

Returns:

  • (Boolean) —

    true if validator is enabled



154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/yard/lint/config.rb', line 154

def validator_enabled?(validator_name)
  # If --only is specified, it takes full control
  return only_validators.include?(validator_name) if only_validators.any?

  # An explicit per-validator Enabled in the user's config wins.
  raw_validator = @raw_config[validator_name]
  if raw_validator.is_a?(Hash) && raw_validator.key?('Enabled')
    return raw_validator['Enabled'] != false
  end

  # Otherwise honor a category-level Enabled (e.g. `Documentation:
  # { Enabled: false }`), which previously validated but was ignored.
  category = validator_name.split('/').first
  raw_category = @raw_config[category]
  if raw_category.is_a?(Hash) && raw_category.key?('Enabled')
    return raw_category['Enabled'] != false
  end

  validator_config = validators[validator_name] || {}
  validator_config['Enabled'] != false # Default to true
end

#validator_exclude(validator_name) ⇒ Array<String>

Get validator-specific exclude patterns

Parameters:

  • validator_name (String) —

    full validator name

Returns:

  • (Array<String>) —

    exclusion patterns for this validator



187
188
189
190
 
# File 'lib/yard/lint/config.rb', line 187

def validator_exclude(validator_name)
  validator_config = validators[validator_name] || {}
  validator_config['Exclude'] || []
end

#validator_severity(validator_name) ⇒ String

Get validator severity

Parameters:

  • validator_name (String) —

    full validator name

Returns:

  • (String) —

    severity level for this validator



179
180
181
182
 
# File 'lib/yard/lint/config.rb', line 179

def validator_severity(validator_name)
  validator_config = validators[validator_name] || {}
  validator_config['Severity'] || 'warning'
end

#validator_yard_options(validator_name) ⇒ Array<String>

Get YARD options for a specific validator Falls back to global options if validator doesn’t specify its own

Parameters:

  • validator_name (String) —

    full validator name

Returns:

  • (Array<String>) —

    YARD options for this validator



87
88
89
90
 
# File 'lib/yard/lint/config.rb', line 87

def validator_yard_options(validator_name)
  validator_config = validators[validator_name] || {}
  validator_config['YardOptions'] || options
end