yard-lint 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 43a01c4ffe524ad45bfac735365768a8afaacf812a894c511b7e8d42c475e646
+  data.tar.gz: a10ebddfaacdeb54db032121df28c73efc82fae79898fce5b080491e4087c26d
+SHA512:
+  metadata.gz: 00b26fb9a801b71dc13c0e1050f1ecd6db7ce7e777ecfdf1e4916bedbfb63af273186c7a1327a24f371b6e02c18bcd5c51ae8b6fa24e4f0c63f64370021a7418
+  data.tar.gz: d7665d29d69631b17d4bfc82e77a08494131490167d9e2124e3b2b625f82ce8c263111448e8a66e0f95d1e87ef976e643480adfbaf915c962251161db0d99f71

data/.coditsu/ci.yml

@@ -0,0 +1,3 @@
+repository_id: '65b8c66c-02f1-44a2-a078-4af9a0ced5cd'
+api_key: <%= ENV['CODITSU_API_KEY'] %>
+api_secret: <%= ENV['CODITSU_API_SECRET'] %>

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.2.0 (2025-11-07)
+
+- Initial release of YARD-Lint gem
+- Comprehensive YARD documentation validation
+- CLI tool (`yard-lint`) for running linter
+- Detects undocumented classes, modules, and methods
+- Validates parameter documentation
+- Validates tag type definitions
+- Enforces tag ordering conventions
+- Validates boolean method documentation
+- Detects YARD warnings (unknown tags, invalid directives, etc.)
+- JSON and text output formats
+- Configurable tag ordering and extra type definitions
+- Ruby API for programmatic usage
+- Result object with offense categorization
+- Three severity levels: error, warning, convention
+- YAML configuration file support (`.yard-lint.yml`)
+- Automatic configuration file discovery
+- File exclusion patterns with glob support
+- Configurable exit code based on severity level
+- Quiet mode (`--quiet`) for minimal output
+- Statistics summary (`--stats`)
+- @api tag validation with configurable allowed APIs
+- @abstract method validation
+- @option hash documentation validation
+- Zeitwerk for automatic code loading

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Maciej Mensfeld
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,454 @@
+# YARD-Lint
+
+A comprehensive linter for YARD documentation that helps you maintain clean, consistent, and complete documentation in your Ruby and Ruby on Rails projects.
+
+## Why Documentation Quality Matters More Than Ever
+
+Accurate documentation isn't just for human developers anymore. [Research shows](https://arxiv.org/html/2404.03114) that incorrect documentation reduces AI assistant success rates up to 50% (from 44.7% to 22.1%). [Enterprise studies](https://arxiv.org/html/2501.13282v1) with 400+ developers found well-documented code achieves 30%+ AI acceptance rates versus 14-20% for poorly documented code.
+
+**The problem:** Documentation drifts as code changes-parameters get renamed, return types change, but docs stay stale. This doesn't just confuse developers; it trains AI coding assistants to generate confidently wrong code.
+
+**The solution:** YARD-Lint automatically validates your YARD documentation stays synchronized with your code, ensuring both human developers and AI tools have accurate context.
+
+## Features
+
+YARD-Lint validates your YARD documentation for:
+
+- **Undocumented code**: Classes, modules, methods, and constants without documentation
+- **Missing parameter documentation**: Methods with undocumented parameters
+- **Invalid tag types**: Type definitions that aren't valid Ruby classes or allowed defaults
+- **Invalid tag ordering**: Tags that don't follow your specified order
+- **Boolean method documentation**: Question mark methods missing return type documentation
+- **API tag validation**: Enforce @api tags on public objects and validate API values
+- **Abstract method validation**: Ensure @abstract methods don't have real implementations
+- **Option hash documentation**: Validate that methods with options parameters have @option tags
+- **YARD warnings**: Unknown tags, invalid directives, duplicated parameter names, and more
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'yard-lint'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install yard-lint
+```
+
+## Usage
+
+### Command Line
+
+Basic usage:
+
+```bash
+yard-lint lib/
+```
+
+With options:
+
+```bash
+# Use a specific config file
+yard-lint --config config/yard-lint.yml lib/
+
+# Output as JSON
+yard-lint --format json lib/ > report.json
+```
+
+## Configuration
+
+YARD-Lint is configured via a `.yard-lint.yml` configuration file (similar to `.rubocop.yml`).
+
+### Configuration File
+
+Create a `.yard-lint.yml` file in your project root:
+
+```yaml
+# .yard-lint.yml
+# 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/**/*'
+
+  # Exit code behavior (error, warning, convention, never)
+  FailOnSeverity: warning
+
+# Individual validator configuration
+Documentation/UndocumentedObjects:
+  Description: 'Checks for classes, modules, and methods without documentation.'
+  Enabled: true
+  Severity: warning
+
+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
+
+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
+  ExtraTypes:
+    - CustomType
+    - MyType
+
+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/AbstractMethods:
+  Description: 'Ensures @abstract methods do not have real implementations.'
+  Enabled: true
+  Severity: warning
+```
+
+#### Key Features
+
+- **Per-validator control**: Enable/disable and configure each validator independently
+- **Custom severity**: Override severity levels per validator
+- **Per-validator exclusions**: Add validator-specific file exclusions (in addition to global ones)
+- **Per-validator YardOptions**: Override YARD options for specific validators if needed
+- **Inheritance support**: Use `inherit_from` and `inherit_gem` to share configurations
+- **Self-documenting**: Each validator can include a `Description` field
+
+#### Configuration Discovery
+
+YARD-Lint will automatically search for `.yard-lint.yml` in the current directory and parent directories.
+
+You can specify a different config file:
+
+```bash
+yard-lint --config path/to/config.yml lib/
+```
+
+#### Configuration Inheritance
+
+Share configurations across projects using inheritance (like RuboCop):
+
+```yaml
+# Inherit from local files
+inherit_from:
+  - .yard-lint_todo.yml
+  - ../.yard-lint.yml
+
+# Inherit from gems
+inherit_gem:
+  my-company-style: .yard-lint.yml
+
+# Your project-specific overrides
+Documentation/UndocumentedObjects:
+  Exclude:
+    - 'lib/legacy/**/*'
+```
+
+#### Per-Validator Exclusions
+
+You can exclude specific files from individual validators while still checking them with other validators. This is useful when you want different validators to apply to different parts of your codebase.
+
+**Example: Skip type checking in legacy code**
+
+```yaml
+# .yard-lint.yml
+AllValidators:
+  Exclude:
+    - 'vendor/**/*'
+
+# Exclude legacy files from type validation only
+Tags/InvalidTypes:
+  Exclude:
+    - 'lib/legacy/**/*'
+    - 'lib/deprecated/*.rb'
+
+# But still check for undocumented methods in those files
+Documentation/UndocumentedObjects:
+  Enabled: true
+```
+
+**Example: Different rules for different directories**
+
+```yaml
+# Strict documentation for public API
+Documentation/UndocumentedMethodArguments:
+  Enabled: true
+  Exclude:
+    - 'lib/internal/**/*'
+    - 'spec/**/*'
+
+# But enforce @api tags everywhere
+Tags/ApiTags:
+  Enabled: true
+  Exclude:
+    - 'spec/**/*'  # Only exclude specs
+```
+
+**Example: Override YARD options per validator**
+
+```yaml
+AllValidators:
+  # Default: only parse public methods
+  YardOptions: []
+
+# Check all methods (including private) for tag order
+Tags/Order:
+  YardOptions:
+    - --private
+    - --protected
+
+# But only require documentation for public methods
+Documentation/UndocumentedObjects:
+  YardOptions: []  # Only public methods
+```
+
+This allows you to enforce correct tag formatting on all methods while only requiring documentation on public methods.
+
+**How it works:**
+
+1. **Global exclusions** (defined in `AllValidators/Exclude`) apply to ALL validators
+2. **Per-validator exclusions** (defined in each validator's `Exclude`) apply ONLY to that validator
+3. Both types of exclusions work together - a file must pass both filters to be checked
+
+Supported glob patterns:
+- `**/*` - Recursive match (all files in subdirectories)
+- `*.rb` - Simple wildcard
+- `lib/foo/*.rb` - Directory with wildcard
+- `**/test_*.rb` - Recursive with prefix match
+
+### Available Validators
+
+| Validator | Description | Default | Configuration Options |
+|-----------|-------------|---------|----------------------|
+| **Documentation Validators** |
+| `Documentation/UndocumentedObjects` | Checks for classes, modules, and methods without documentation | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
+| `Documentation/UndocumentedMethodArguments` | Checks for method parameters without `@param` tags | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
+| `Documentation/UndocumentedBooleanMethods` | Checks that question mark methods document their boolean return | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
+| **Tags Validators** |
+| `Tags/Order` | Enforces consistent ordering of YARD tags | Enabled (convention) | `Enabled`, `Severity`, `Exclude`, `EnforcedOrder` |
+| `Tags/InvalidTypes` | Validates type definitions in `@param`, `@return`, `@option` tags | Enabled (warning) | `Enabled`, `Severity`, `Exclude`, `ValidatedTags`, `ExtraTypes` |
+| `Tags/ApiTags` | Enforces `@api` tags on public objects | Disabled (opt-in) | `Enabled`, `Severity`, `Exclude`, `AllowedApis` |
+| `Tags/OptionTags` | Requires `@option` tags for methods with options parameters | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
+| **Warnings Validators** |
+| `Warnings/UnknownTag` | Detects unknown YARD tags | Enabled (error) | `Enabled`, `Severity`, `Exclude` |
+| `Warnings/UnknownDirective` | Detects unknown YARD directives | Enabled (error) | `Enabled`, `Severity`, `Exclude` |
+| `Warnings/InvalidTagFormat` | Detects malformed tag syntax | Enabled (error) | `Enabled`, `Severity`, `Exclude` |
+| `Warnings/InvalidDirectiveFormat` | Detects malformed directive syntax | Enabled (error) | `Enabled`, `Severity`, `Exclude` |
+| `Warnings/DuplicatedParameterName` | Detects duplicate `@param` tags | Enabled (error) | `Enabled`, `Severity`, `Exclude` |
+| `Warnings/UnknownParameterName` | Detects `@param` tags for non-existent parameters | Enabled (error) | `Enabled`, `Severity`, `Exclude` |
+| **Semantic Validators** |
+| `Semantic/AbstractMethods` | Ensures `@abstract` methods don't have real implementations | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
+
+### Global Configuration
+
+| Option | Description | Default | Type |
+|--------|-------------|---------|------|
+| `AllValidators/YardOptions` | YARD command-line options applied to all validators (e.g., `--private`, `--protected`). Can be overridden per-validator. | `[]` | Array of strings |
+| `AllValidators/Exclude` | File patterns to exclude from all validators. Per-validator exclusions are additive. | `['\.git', 'vendor/**/*', 'node_modules/**/*']` | Array of glob patterns |
+| `AllValidators/FailOnSeverity` | Exit with error code for this severity level and above | `warning` | `error`, `warning`, `convention`, or `never` |
+| `<Validator>/YardOptions` | Override YARD options for a specific validator | Inherits from `AllValidators/YardOptions` | Array of strings |
+| `<Validator>/Exclude` | Additional file patterns to exclude for this validator only | `[]` | Array of glob patterns |
+
+## Severity Levels
+
+| Severity | Description | Examples |
+|----------|-------------|----------|
+| **error** | Critical issues that prevent proper documentation parsing | Unknown tags, invalid formats, malformed syntax, duplicate parameters |
+| **warning** | Missing or incorrect documentation | Undocumented methods, missing `@param` tags, invalid type definitions, semantic issues |
+| **convention** | Style and consistency issues | Tag ordering, formatting preferences |
+
+## Integration with CI
+
+### GitHub Actions
+
+```yaml
+- name: Run YARD Lint
+  run: bundle exec yard-lint lib/
+```
+
+## CLI Options
+
+YARD-Lint supports the following command-line options:
+
+```bash
+yard-lint [options] PATH
+
+Options:
+  -c, --config FILE       Path to config file (default: .yard-lint.yml)
+  -f, --format FORMAT     Output format (text, json)
+  -q, --quiet             Quiet mode (only show summary)
+      --stats             Show statistics summary
+      --[no-]progress     Show progress indicator (default: auto-detect TTY)
+  -v, --version           Show version
+  -h, --help              Show this help
+```
+
+All configuration (tag order, exclude patterns, severity levels, validator settings) should be defined in `.yard-lint.yml`.
+
+## Examples
+
+### Check a directory
+
+```bash
+yard-lint lib/
+```
+
+### Check a single file
+
+```bash
+yard-lint lib/my_class.rb
+```
+
+### Use custom config file
+
+```bash
+yard-lint --config config/yard-lint.yml lib/
+```
+
+### Configure fail-on-severity
+
+Add to `.yard-lint.yml`:
+```yaml
+AllValidators:
+  FailOnSeverity: error  # Only fail on errors, not warnings
+```
+
+### Enable @api tag validation
+
+Add to `.yard-lint.yml`:
+```yaml
+Tags/ApiTags:
+  Enabled: true
+  AllowedApis:
+    - public
+    - private
+```
+
+This will enforce that all public classes, modules, and methods have an `@api` tag:
+
+```ruby
+# Good
+# @api public
+class MyClass
+  # @api public
+  def public_method
+  end
+
+  # @api private
+  def internal_helper
+  end
+end
+
+# Bad - missing @api tags
+class AnotherClass
+  def some_method
+  end
+end
+```
+
+### @option tag validation (enabled by default)
+
+This validator ensures that methods with options parameters document them. It's **enabled by default**. To disable it, add to `.yard-lint.yml`:
+
+```yaml
+Tags/OptionTags:
+  Enabled: false
+```
+
+Examples:
+
+```ruby
+# Good
+# @param name [String] the name
+# @param options [Hash] configuration options
+# @option options [Boolean] :enabled Whether to enable the feature
+# @option options [Integer] :timeout Timeout in seconds
+def configure(name, options = {})
+end
+
+# Bad - missing @option tags
+# @param name [String] the name
+# @param options [Hash] configuration options
+def configure(name, options = {})
+end
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "yard/lint"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/bin/yard-lint

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'optparse'
+require 'yard-lint'
+
+options = {}
+config_file = nil
+
+OptionParser.new do |opts|
+  opts.banner = 'Usage: yard-lint [options] PATH'
+
+  opts.on('-c', '--config FILE', 'Path to config file (default: .yard-lint.yml)') do |file|
+    config_file = file
+  end
+
+  opts.on('-f', '--format FORMAT', 'Output format (text, json)') do |format|
+    options[:format] = format
+  end
+
+  opts.on('-q', '--quiet', 'Quiet mode (only show summary)') do
+    options[:quiet] = true
+  end
+
+  opts.on('--stats', 'Show statistics summary') do
+    options[:stats] = true
+  end
+
+  opts.on('--[no-]progress', 'Show progress indicator (default: auto)') do |value|
+    options[:progress] = value
+  end
+
+  opts.on('-v', '--version', 'Show version') do
+    puts "yard-lint #{Yard::Lint::VERSION}"
+    exit
+  end
+
+  opts.on('-h', '--help', 'Show this help') do
+    puts opts
+    exit
+  end
+end.parse!
+
+# Get path argument
+path = ARGV[0]
+
+unless path
+  puts 'Error: PATH argument is required'
+  puts 'Usage: yard-lint [options] PATH'
+  exit 1
+end
+
+# Run the linter with config_file (it will be loaded internally)
+result = Yard::Lint.run(
+  path: path,
+  config_file: config_file,
+  progress: options[:progress]
+)
+
+# Format and display results
+case options[:format]
+when 'json'
+  require 'json'
+  puts JSON.pretty_generate({
+    offense_count: result.count,
+    offenses: result.offenses
+  })
+  exit result.exit_code
+when 'text', nil
+  if result.clean?
+    puts 'No offenses found'
+    exit 0
+  else
+    # Show statistics if requested or in quiet mode
+    if options[:stats] || options[:quiet]
+      stats = result.statistics
+      puts "\n#{result.count} offense(s) detected"
+      puts "  Errors:      #{stats[:error]}"
+      puts "  Warnings:    #{stats[:warning]}"
+      puts "  Conventions: #{stats[:convention]}"
+      puts
+    end
+
+    # Show individual offenses unless in quiet mode
+    unless options[:quiet]
+      puts "Found #{result.count} offense(s):\n\n"
+
+      result.offenses.each do |offense|
+        severity_symbol = case offense[:severity]
+                          when 'error' then 'E'
+                          when 'warning' then 'W'
+                          when 'convention' then 'C'
+                          else '?'
+                          end
+
+        puts "[#{severity_symbol}] #{offense[:location]}:#{offense[:location_line]}"
+        puts "    #{offense[:name]}: #{offense[:message]}"
+        puts
+      end
+    end
+
+    exit result.exit_code
+  end
+else
+  puts "Error: Unknown format '#{options[:format]}'"
+  exit 1
+end