manyfold/.yard-lint.yml

# YARD-Lint Configuration
# See https://github.com/mensfeld/yard-lint for documentation

# Global settings for all validators
AllValidators:
  # YARD command-line options (applied to all validators by default)
  YardOptions:
    # - --private
    # - --protected

  # Global file exclusion patterns
  Exclude:
    - '\.git'
    - 'vendor/**/*'
    - 'node_modules/**/*'
    - 'spec/**/*'
    - 'test/**/*'
    - 'config/db/**/*'

  # Exit code behavior (error, warning, convention, never)
  FailOnSeverity: warning

  # Minimum documentation coverage percentage (0-100)
  # Fails if coverage is below this threshold
  # MinCoverage: 80.0

  # Diff mode settings
  DiffMode:
    # Default base ref for --diff (auto-detects main/master if not specified)
    DefaultBaseRef: ~

# Documentation validators
Documentation/UndocumentedObjects:
  Description: 'Checks for classes, modules, and methods without documentation.'
  Enabled: true
  Severity: warning
  ExcludedMethods:
    - 'initialize/0'  # Exclude parameter-less initialize
    - '/^_/'          # Exclude private methods (by convention)

Documentation/UndocumentedMethodArguments:
  Description: 'Checks for method parameters without @param tags.'
  Enabled: true
  Severity: warning

Documentation/UndocumentedBooleanMethods:
  Description: 'Checks that question mark methods document their boolean return.'
  Enabled: true
  Severity: warning

Documentation/UndocumentedOptions:
  Description: 'Detects methods with options hash parameters but no @option tags.'
  Enabled: true
  Severity: warning

Documentation/MarkdownSyntax:
  Description: 'Detects common markdown syntax errors in documentation.'
  Enabled: true
  Severity: warning

# Tags validators
Tags/Order:
  Description: 'Enforces consistent ordering of YARD tags.'
  Enabled: true
  Severity: convention
  EnforcedOrder:
    - param
    - option
    - return
    - raise
    - example

Tags/InvalidTypes:
  Description: 'Validates type definitions in @param, @return, @option tags.'
  Enabled: true
  Severity: warning
  ValidatedTags:
    - param
    - option
    - return

Tags/TypeSyntax:
  Description: 'Validates YARD type syntax using YARD parser.'
  Enabled: true
  Severity: warning
  ValidatedTags:
    - param
    - option
    - return
    - yieldreturn

Tags/MeaninglessTag:
  Description: 'Detects @param/@option tags on classes, modules, or constants.'
  Enabled: true
  Severity: warning
  CheckedTags:
    - param
    - option
  InvalidObjectTypes:
    - class
    - module
    - constant

Tags/CollectionType:
  Description: 'Validates Hash collection syntax consistency.'
  Enabled: true
  Severity: convention
  EnforcedStyle: long  # 'long' for Hash{K => V} (YARD standard), 'short' for {K => V}
  ValidatedTags:
    - param
    - option
    - return
    - yieldreturn

Tags/TagTypePosition:
  Description: 'Validates type annotation position in tags.'
  Enabled: true
  Severity: convention
  CheckedTags:
    - param
    - option
  # EnforcedStyle: 'type_after_name' (YARD standard: @param name [Type])
  #                or 'type_first' (@param [Type] name)
  EnforcedStyle: type_after_name

Tags/ApiTags:
  Description: 'Enforces @api tags on public objects.'
  Enabled: false  # Opt-in validator
  Severity: warning
  AllowedApis:
    - public
    - private
    - internal

Tags/OptionTags:
  Description: 'Requires @option tags for methods with options parameters.'
  Enabled: true
  Severity: warning

# Warnings validators - catches YARD parser errors
Warnings/UnknownTag:
  Description: 'Detects unknown YARD tags.'
  Enabled: true
  Severity: error

Warnings/UnknownDirective:
  Description: 'Detects unknown YARD directives.'
  Enabled: true
  Severity: error

Warnings/InvalidTagFormat:
  Description: 'Detects malformed tag syntax.'
  Enabled: true
  Severity: error

Warnings/InvalidDirectiveFormat:
  Description: 'Detects malformed directive syntax.'
  Enabled: true
  Severity: error

Warnings/DuplicatedParameterName:
  Description: 'Detects duplicate @param tags.'
  Enabled: true
  Severity: error

Warnings/UnknownParameterName:
  Description: 'Detects @param tags for non-existent parameters.'
  Enabled: true
  Severity: error

# Semantic validators
Semantic/AbstractMethods:
  Description: 'Ensures @abstract methods do not have real implementations.'
  Enabled: true
  Severity: warning