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:



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

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.



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

def only_validators
  @only_validators
end

#raw_config ⇒ Object (readonly)

Returns the value of attribute raw_config.



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

def raw_config
  @raw_config
end

#validators ⇒ Object (readonly)

Returns the value of attribute validators.



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

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



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

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:



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

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:



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

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



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

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

#all_validators ⇒ Hash

Get AllValidators section

Returns:

  • (Hash) —

    AllValidators configuration



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

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



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

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



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

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



99
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
 
# File 'lib/yard/lint/config.rb', line 99

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



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

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



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

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

#exclude=(value) ⇒ Object

Set global exclude patterns

Parameters:

  • value (Array<String>) —

    exclusion patterns



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

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)



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

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

#fail_on_severity=(value) ⇒ Object

Set fail on severity level

Parameters:

  • value (String) —

    severity level



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

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



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

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



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

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



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

def min_coverage
  all_validators['MinCoverage']
end

#min_coverage=(value) ⇒ Object

Set minimum coverage percentage

Parameters:

  • value (Float) —

    minimum coverage percentage (0-100)



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

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



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

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

#options=(value) ⇒ Object

Set YARD options

Parameters:

  • value (Array<String>) —

    YARD options



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

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



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

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)



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

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



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

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



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

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



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

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



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

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



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

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