yard-lint 1.2.2 → 1.3.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce486b9b4338392c9c03ff8392f0f8bacbb7e303e1b594222ee7092ec2b916a7
-  data.tar.gz: 22defb3b4fc8f1ea0481bd16f3a0690930ce570678d3f625ae2500bd359fb8c0
+  metadata.gz: eb5e9ce0ee619596a8e5d35f7d46a9494ac6e0682215ad0f0bf48a3a87ee8f04
+  data.tar.gz: 5eff9bd848c484de1c752d60577f9d3ce2910a8d4f61825b02d1552a9209c598
 SHA512:
-  metadata.gz: 134751b6c3b73c9749d0b3ec156c67333caa3b610fdd74ddd86b581c4456c05e8485a7f9ab2adffefbbfe90d706b7a0919a78d2439f9219405c0c82e9dc5dd2d
-  data.tar.gz: 3e9fd559c1583cea798fdbe014e0e6c1a5bfb5243faf9cab8aad30ffeefce7771728fe679645eca2e35621675df3f8d2ec29f21f59d747be08ec275b765ecea2
+  metadata.gz: 1e435ab938578b0c84ce189def96cfe2c0ab3e0d5881ab3a7d8e1c89b4e082fa21b0388175685ccce08df1a95bcacca8d5c61a703f0aaf81f9950b6bd95119a8
+  data.tar.gz: 1de8b9658868b6bda3504151486ffa25fc86ee379d3fd41e19b05b5bf93024bd6f244bfaf79e97d45b08e4a3862db890dda9a4f8d8d9576e616021c945a43bf9

data/CHANGELOG.md

@@ -1,5 +1,178 @@
 # YARD-Lint Changelog
 
+## 1.3.0 (Unreleased)
+- **[Fix]** Expand `Tags/Order` default `EnforcedOrder` to include all standard YARD tags
+  - Previous config only included: `param`, `option`, `return`, `raise`, `example`
+  - Now includes full order: `param`, `option`, `yield`, `yieldparam`, `yieldreturn`, `return`, `raise`, `see`, `example`, `note`, `todo`
+  - Tags not in the list were silently ignored, so `@note`, `@todo`, `@see`, and `@yield*` ordering was not validated
+  - Updated both `default_config.yml` and `strict_config.yml`
+- **[Enhancement]** Add `IMPORTANT:` pattern detection to `Tags/InformalNotation` validator
+  - Detects `IMPORTANT:` and `Important:` informal notation and suggests using `@note` tag
+  - YARD does not have a dedicated `@important` tag; `@note` is the standard tag for emphasized notes
+- **[Feature]** Add `Tags/TagGroupSeparator` validator to enforce blank line separators between different YARD tag groups (#29)
+  - Enforces visual separation between semantically different tag groups (e.g., `@param` tags should be separated from `@return` tags by a blank line)
+  - Configurable tag groups: param (param, option), return (return), error (raise, throws), example (example), meta (see, note, todo, deprecated, since, version, api), yield (yield, yieldparam, yieldreturn)
+  - Optional `RequireAfterDescription` setting to require blank line between description and first tag
+  - Unknown tags are treated as their own group (require separator from known groups)
+  - Disabled by default (opt-in validator) with 'convention' severity
+- **[Feature]** Add `Tags/InformalNotation` validator to detect informal notation patterns in documentation (#33)
+  - Detects patterns like `Note:`, `TODO:`, `See:`, `Warning:`, `Deprecated:` and suggests proper YARD tags
+  - Suggests appropriate replacements: `@note`, `@todo`, `@see`, `@deprecated`, `@author`, `@version`, etc.
+  - Skips patterns inside fenced code blocks to avoid false positives
+  - Case-insensitive matching by default (configurable via `CaseSensitive`)
+  - Start-of-line matching by default (configurable via `RequireStartOfLine`)
+  - Fully configurable pattern mappings via `Patterns` option
+  - Enabled by default with 'warning' severity
+- **[Feature]** Add `Tags/NonAsciiType` validator to detect non-ASCII characters in YARD type specifications (#39)
+  - Ruby type names must be valid Ruby identifiers (ASCII only)
+  - Detects characters like `…` (U+2026), `→` (U+2192), `—` (U+2014) in type specs
+  - Common cause: copy-paste from word processors with smart typography
+  - Reports specific character and Unicode code point in error message
+  - Example: `@param flags [Symbol, …]` → reports `'…' (U+2026)`
+  - Enabled by default with 'warning' severity
+  - Configurable `ValidatedTags` (default: param, option, return, yieldreturn, yieldparam)
+- **[Fix]** Fix `Encoding::CompatibilityError` crash when YARD encounters non-ASCII characters in type specifications
+  - TypeSyntax validator now handles encoding issues gracefully
+  - Sanitizes YARD error messages that may contain invalid UTF-8 sequences
+- **[Fix]** Fix relative exclusion patterns not matching files discovered with absolute paths
+  - Patterns like `vendor/**/*` were not being applied when running `yard-lint /path/to/project` or `yard-lint .`
+  - Root cause: `expand_path` converted files to absolute paths before filtering, but compared against relative patterns
+  - Now matches patterns against both relative and absolute paths (similar to RuboCop's `PathUtil#match_path?`)
+  - Extracted `discover_ruby_files` method for better separation of concerns
+  - Added `determine_base_dir`, `excluded_file?`, `relative_path_from`, and `match_path?` helper methods
+  - Comprehensive integration tests in `spec/integrations/global_exclusions_spec.rb`
+- **[Enhancement]** Make PATH argument optional, defaulting to current directory (like RuboCop)
+  - Running `yard-lint` without arguments now lints the current directory
+  - Maintains backward compatibility with explicit path arguments
+  - Updated help text and examples to show default behavior
+- **[Fix]** Respect per-validator `YardOptions` when filtering by visibility (#41)
+  - Executor was ignoring `YardOptions` defined on individual validators
+  - Specifying `YardOptions` on a specific validator now correctly overrides `AllValidators` defaults
+  - Enables use cases like validating tag order on private methods, but skipping documentation requirement
+  - Example: Set `--private` in `AllValidators.YardOptions`, then override with empty `YardOptions: []` on `Documentation/UndocumentedObjects` to skip private methods or constants
+- **[Feature]** Add in-process YARD execution for ~10x faster performance
+  - Parses files once and shares the YARD registry across all validators
+  - Eliminates subprocess spawning overhead (previously spawned 17+ processes per run)
+  - Maintains identical detection results and output format
+  - All 17 validators migrated to in-process execution
+  - Warning validators (UnknownTag, UnknownParameterName, etc.) capture YARD warnings during parsing
+  - Respects `--private`/`--protected` YardOptions for visibility filtering
+  - Fixed `void` typo in allowed types (was `vold`)
+  - Properly handles symbol types (`:all`, `:public`) in type validation
+- **[Change]** Remove shell mode execution (was deprecated fallback)
+  - In-process execution is now the only mode
+  - Shell mode fallback code and `YARD_LINT_SHELL_MODE` environment variable removed
+  - Simplifies codebase by removing ~1000 lines of shell-related code
+- **[Feature]** Add `Documentation/EmptyCommentLine` validator to detect unnecessary empty comment lines in YARD documentation blocks
+  - Detects empty `#` lines at the start of documentation blocks (leading)
+  - Detects empty `#` lines at the end of documentation blocks (trailing)
+  - Correctly allows empty lines between sections (e.g., between description and @param tags)
+  - Configurable `EnabledPatterns` to check leading, trailing, or both
+  - Reads source files directly to detect comment block boundaries
+  - Enabled by default with 'convention' severity
+  - Comprehensive test coverage with 45 unit and integration tests
+- **[Feature]** Add "did you mean" suggestions for UnknownParameterName validator
+  - Suggests correct parameter names when documentation mismatches are detected
+  - Uses Ruby's `did_you_mean` gem as primary suggestion engine
+  - Falls back to Levenshtein distance algorithm when DidYouMean doesn't find matches
+  - Parses Ruby source files directly to extract actual method parameters
+  - Handles all parameter types: regular, keyword, splat, block, with defaults
+  - Example: `@param user_nme [String] typo` → suggests "did you mean 'user_name'?"
+  - Only suggests when parameter names are similar enough (distance threshold)
+  - Comprehensive test coverage with 19 unit tests and 12 integration tests
+  - Inspired by yard-junk's helpful error messages
+- **[Feature]** Add "did you mean" suggestions for UnknownTag validator
+  - Suggests correct YARD tag names when typos are detected
+  - Dynamically loads valid tags and directives from YARD::Tags::Library for automatic compatibility with any YARD version
+  - Checks against all 22 standard YARD meta-data tags and 8 directives (in YARD 0.9.x)
+  - Uses Ruby's `did_you_mean` gem as primary suggestion engine
+  - Falls back to Levenshtein distance algorithm when DidYouMean doesn't find matches
+  - Example: `@returns [String]` → suggests "did you mean '@return'?"
+  - Example: `@raises [Error]` → suggests "did you mean '@raise'?"
+  - Example: `@params value` → suggests "did you mean '@param'?"
+  - Only suggests when tag names are similar enough (within 50% edit distance)
+  - Comprehensive test coverage with 35 unit tests and 12 integration tests covering common typos
+  - Completes the "did you mean" feature set alongside UnknownParameterName validator
+  - Inspired by yard-junk's helpful suggestion system
+- **[Fix]** Replace hard-coded `#!/bin/bash` with `#!/bin/sh` for BSD/macOS compatibility (#34)
+  - Scripts now use POSIX-compliant shell instead of Bash
+  - Fixes `Errno::ENOENT` errors on *BSD systems where `/bin/bash` doesn't exist
+  - Affects all validators that use temporary shell scripts: InvalidTypes, RedundantParamDescription, EmptyCommentLine, TypeSyntax, CollectionType, MeaninglessTag, TagTypePosition
+- **[Fix]** Fix Runner bug where offense messages were lost during per-validator exclusion filtering
+  - `filter_result_offenses` was creating new Result objects with stripped offense data
+  - Enhanced messages (like "did you mean" suggestions) were being discarded
+  - Now modifies existing Result object's offenses array to preserve all data
+  - Fixes issue affecting all validators with custom message builders
+- **[Change]** Update `.yard-lint.yml` to set `FailOnSeverity` to `convention` level
+  - Previously set to `error`, now fails on any severity including convention
+  - Ensures stricter enforcement of documentation style conventions
+- **[CI]** Add macOS testing to CI workflow
+  - Tests Ruby 3.4 on macOS to validate BSD/POSIX compatibility
+- **[CI]** Add parallel_tests gem to run specs in parallel for faster CI execution
+- **[Feature]** Add `ArticleParamPhrase` pattern to `Tags/RedundantParamDescription` validator (#32)
+  - Detects filler phrases like "The action being performed" or "A callback to invoke"
+  - Matches pattern: `<Article> <param_name> <connector> [<low_value_verb>...]`
+  - Configurable `LowValueConnectors` list (default: being, to, that, which, for)
+  - Configurable `LowValueVerbs` list (default: perform, process, use, handle, act, pass, invoke, call, execute, run)
+  - Enabled by default via `EnabledPatterns.ArticleParamPhrase`
+  - Pattern-specific error message explaining the filler phrase adds no value
+  - Comprehensive test coverage with fixtures and integration tests
+- **[Feature]** Add `--only` CLI option to run specific validators
+  - Run single validator: `yard-lint --only Tags/TypeSyntax`
+  - Run multiple validators: `yard-lint --only Tags/Order,Tags/TypeSyntax`
+  - Overrides `Enabled: false` in config for specified validators
+  - Provides "did you mean" suggestions for typos using Ruby's `did_you_mean` gem
+  - Lists all available validators when unknown validator is specified
+  - Requires exact validator names (case-sensitive, full path like `Tags/Order`)
+- **[Feature]** Add `Documentation/BlankLineBeforeDefinition` validator to detect blank lines between YARD documentation and definitions (#30)
+  - Detects single blank line violations where YARD still associates docs but violates conventions
+  - Detects orphaned documentation (2+ blank lines) where YARD completely ignores the documentation
+  - Works with methods, classes, and modules
+  - Configurable `EnabledPatterns` to check only single blank lines, only orphaned docs, or both
+  - Separate `Severity` and `OrphanedSeverity` configuration options for different violation types
+  - Respects `--private` and `--protected` YardOptions for visibility filtering
+  - Enabled by default with 'convention' severity for both violation types
+- **[Fix]** Fix yard-lint silently returning "No offenses found" for non-existent file paths
+  - Previously, specifying a non-existent path would silently succeed with empty results
+  - Now raises `Errors::FileNotFoundError` with clear message: "No such file or directory: /path"
+  - Matches behavior of similar tools like RuboCop
+  - Only validates explicit file paths (glob patterns and directories are not affected)
+- **[Feature]** Add `--update` command to update existing `.yard-lint.yml` with new validators
+  - Adds new validators introduced in newer yard-lint versions with their template defaults
+  - Removes obsolete validators that no longer exist in yard-lint
+  - Preserves all existing user configuration (custom severities, exclusions, etc.)
+  - Reports added, removed, and preserved validator counts
+  - Supports `--strict` flag to use strict template defaults for new validators
+  - Example: `yard-lint --update` or `yard-lint --update --strict`
+- **[Fix]** Fix integration specs failing in parallel test runs due to relative fixture paths
+  - Updated `MeaninglessTag`, `EmptyCommentLine`, `MultiValidatorComprehensive`, `InformalNotation`, `BlankLineBeforeDefinition`, `MagicComments`, `CollectionType`, `TagTypePosition` specs to use absolute paths
+  - Updated `ValidatorCoverage` spec to use absolute paths for config and template files
+  - Uses `File.expand_path` with `__dir__` for reliable path resolution regardless of working directory
+
+## 1.2.3 (2025-11-13)
+- **[Feature]** Add per-validator exclusion support for fine-grained file filtering
+  - Individual validators can now specify `Exclude` patterns in `.yard-lint.yml`
+  - Exclusions work alongside global `AllValidators.Exclude` patterns
+  - Both global and per-validator exclusions are applied (union of both pattern sets)
+  - Enables excluding intentionally invalid documentation examples from specific validators
+  - Default config excludes validator implementation files and spec fixtures from `Tags/ExampleSyntax`
+  - Pattern matching works with glob patterns (`**/*.rb`, `**/validators/**/parser.rb`)
+  - Filters validator results based on file location, not just input file selection
+  - Handles both absolute and relative paths correctly in pattern matching
+  - Comprehensive integration test coverage for exclusion scenarios
+  - Example: Exclude parser.rb files with intentionally broken @example tags from syntax validation
+- **[Change]** Update `.yard-lint.yml` to set all validator severities to `error` level
+  - Changes `FailOnSeverity` from `warning` to `error` for stricter enforcement
+  - All validators now use `error` severity instead of `warning` or `convention`
+  - Ensures any documentation issue triggers exit code 1 for CI/CD pipelines
+  - Provides consistent behavior across all validation rules
+- **[Fix]** Fix integration tests failing due to fixture files being filtered by global exclusions
+  - Added `test_config` helper in spec_helper.rb that clears default exclusions for tests
+  - Updated all integration test files to use `test_config` instead of `Yard::Lint::Config.new`
+  - Prevents test fixtures in `spec/fixtures/` from being filtered out by `spec/**/*` exclusion pattern
+  - Ensures integration tests can properly validate linter behavior on fixture files
+- **[Fix]** Remove not needed `bin/` files.
+
 ## 1.2.2 (2025-11-13)
 - **[Fix]** Fix `--version` flag failing with `uninitialized constant Yard::Lint::VERSION` error
   - Zeitwerk expected `Version` (camel case) but file defined `VERSION` (all caps)
@@ -121,7 +294,7 @@
 - [Change] YARD database directories are now created under a base temp directory with unique subdirectories per argument set.
 
 ## 0.2.1 (2025-11-07)
-- Release to validate Trusted Publishing flow. 
+- Release to validate Trusted Publishing flow.
 
 ## 0.2.0 (2025-11-07)
 

data/README.md

@@ -9,7 +9,7 @@ A comprehensive linter for YARD documentation that helps you maintain clean, con
 
 ## 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.
+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%).
 
 **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.
 
@@ -23,6 +23,7 @@ YARD-Lint validates your YARD documentation for:
 - **Missing parameter documentation**: Methods with undocumented parameters
 - **Invalid tag types**: Type definitions that aren't valid Ruby classes or allowed defaults
 - **Invalid type syntax**: Malformed YARD type syntax (unclosed brackets, empty generics, etc.)
+- **Non-ASCII type characters**: Detects Unicode characters in type specifications (e.g., `…`, `→`, `—`) that are invalid Ruby identifiers
 - **Invalid tag ordering**: Tags that don't follow your specified order
 - **Meaningless tags**: `@param` or `@option` tags on classes, modules, or constants (only valid on methods)
 - **Collection type syntax**: Enforces `Hash{K => V}` over `Hash<K, V>` (YARD standard)
@@ -33,7 +34,12 @@ YARD-Lint validates your YARD documentation for:
 - **Option hash documentation**: Validate that methods with options parameters have @option tags
 - **Example code syntax validation**: Validates Ruby syntax in `@example` tags to catch broken code examples
 - **Redundant parameter descriptions**: Detects meaningless parameter descriptions that add no value (e.g., `@param user [User] The user`)
+- **Empty comment lines**: Detects unnecessary empty `#` lines at the start or end of documentation blocks
+- **Blank lines before definitions**: Detects blank lines between YARD documentation and method/class/module definitions (single blank line = convention violation, 2+ blank lines = orphaned documentation that YARD ignores)
+- **Informal notation patterns**: Detects `Note:`, `TODO:`, `See:` etc. and suggests proper YARD tags (`@note`, `@todo`, `@see`)
+- **Tag group separation**: Enforces blank lines between different YARD tag groups (e.g., between `@param` and `@return` tags) for improved readability
 - **YARD warnings**: Unknown tags, invalid directives, duplicated parameter names, and more
+- **Smart suggestions**: Provides "did you mean" suggestions for typos in parameter names using Ruby's `did_you_mean` gem with Levenshtein distance fallback
 
 ## Installation
 
@@ -67,6 +73,28 @@ yard-lint --init
 
 This creates `.yard-lint.yml` with sensible defaults in your current directory.
 
+For new projects with high documentation standards, use strict mode:
+
+```bash
+yard-lint --init --strict
+```
+
+This creates a strict configuration with:
+- All validators set to `error` severity (no warnings or conventions)
+- Minimum documentation coverage set to 100%
+- Perfect for bootstrapping new repositories with high quality standards
+
+After upgrading yard-lint, update your config to include any new validators:
+
+```bash
+yard-lint --update
+```
+
+This will:
+- Add any new validators introduced in the latest version (with their default settings)
+- Remove any obsolete validators that no longer exist
+- Preserve all your existing configuration
+
 ### Command Line
 
 Basic usage:
@@ -87,6 +115,9 @@ yard-lint lib/ --format json > report.json
 # Generate config file (use --force to overwrite existing)
 yard-lint --init
 yard-lint --init --force
+
+# Generate strict config (all errors, 100% coverage)
+yard-lint --init --strict
 ```
 
 ### Diff Mode (Incremental Linting)
@@ -197,6 +228,21 @@ jobs:
 - Works with diff mode to enforce coverage only on changed files
 - Performance optimized with auto-cleanup temp directories for large codebases
 
+### Running Specific Validators
+
+Run only specific validators using the `--only` option - useful for debugging, gradual adoption, or focused CI checks:
+
+```bash
+# Run only one validator
+yard-lint --only Tags/TypeSyntax lib/
+
+# Run multiple validators (comma-separated)
+yard-lint --only Tags/Order,Tags/TypeSyntax lib/
+
+# Combine with other options
+yard-lint --only Documentation/UndocumentedObjects --diff main lib/
+```
+
 ## Configuration
 
 YARD-Lint is configured via a `.yard-lint.yml` configuration file (similar to `.rubocop.yml`).
@@ -493,10 +539,13 @@ Supported glob patterns:
 | `Documentation/UndocumentedBooleanMethods` | Checks that question mark methods document their boolean return | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
 | `Documentation/UndocumentedOptions` | Detects methods with options hash/kwargs parameters but no `@option` tags | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
 | `Documentation/MarkdownSyntax` | Detects common markdown syntax errors in documentation (unclosed backticks, invalid list markers, etc.) | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
+| `Documentation/EmptyCommentLine` | Detects empty `#` lines at the start or end of documentation blocks | Enabled (convention) | `Enabled`, `Severity`, `Exclude`, `EnabledPatterns` |
+| `Documentation/BlankLineBeforeDefinition` | Detects blank lines between documentation and definitions (single blank = convention violation, 2+ blank = orphaned docs) | Enabled (convention) | `Enabled`, `Severity`, `OrphanedSeverity`, `Exclude`, `EnabledPatterns` |
 | **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/TypeSyntax` | Validates YARD type syntax (detects unclosed brackets, empty generics, etc.) | Enabled (warning) | `Enabled`, `Severity`, `Exclude`, `ValidatedTags` |
+| `Tags/NonAsciiType` | Detects non-ASCII characters in type specifications (e.g., `…`, `→`, `—`) | Enabled (warning) | `Enabled`, `Severity`, `Exclude`, `ValidatedTags` |
 | `Tags/MeaninglessTag` | Detects `@param`/`@option` tags on classes, modules, or constants (only valid on methods) | Enabled (warning) | `Enabled`, `Severity`, `Exclude`, `CheckedTags`, `InvalidObjectTypes` |
 | `Tags/CollectionType` | Enforces `Hash{K => V}` over `Hash<K, V>` (YARD standard collection syntax) | Enabled (convention) | `Enabled`, `Severity`, `Exclude`, `ValidatedTags` |
 | `Tags/TagTypePosition` | Validates type annotation position (`@param name [Type]` vs `@param [Type] name`) | Enabled (convention) | `Enabled`, `Severity`, `Exclude`, `CheckedTags`, `EnforcedStyle` |
@@ -504,13 +553,15 @@ Supported glob patterns:
 | `Tags/OptionTags` | Requires `@option` tags for methods with options parameters | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
 | `Tags/ExampleSyntax` | Validates Ruby syntax in `@example` tags to catch broken code examples | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
 | `Tags/RedundantParamDescription` | Detects meaningless parameter descriptions that add no value beyond the parameter name | Enabled (convention) | `Enabled`, `Severity`, `Exclude`, `CheckedTags`, `Articles`, `MaxRedundantWords`, `MinMeaningfulLength`, `GenericTerms`, `EnabledPatterns` |
+| `Tags/InformalNotation` | Detects informal notation patterns (`Note:`, `TODO:`, etc.) and suggests proper YARD tags | Enabled (warning) | `Enabled`, `Severity`, `Exclude`, `CaseSensitive`, `RequireStartOfLine`, `Patterns` |
+| `Tags/TagGroupSeparator` | Enforces blank line separators between different YARD tag groups (e.g., between `@param` and `@return` tags) | Disabled (opt-in) | `Enabled`, `Severity`, `Exclude`, `TagGroups`, `RequireAfterDescription` |
 | **Warnings Validators** |
-| `Warnings/UnknownTag` | Detects unknown YARD tags | Enabled (error) | `Enabled`, `Severity`, `Exclude` |
+| `Warnings/UnknownTag` | Detects unknown YARD tags with "did you mean" suggestions | 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` |
+| `Warnings/UnknownParameterName` | Detects `@param` tags for non-existent parameters with "did you mean" suggestions | Enabled (error) | `Enabled`, `Severity`, `Exclude` |
 | **Semantic Validators** |
 | `Semantic/AbstractMethods` | Ensures `@abstract` methods don't have real implementations | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
 
@@ -528,6 +579,61 @@ yard server
 
 Then open http://localhost:8808 in your browser to browse the full validator documentation with examples.
 
+### Smart Suggestions with "Did You Mean"
+
+YARD-Lint provides intelligent suggestions for common typos in both tag names and parameter names.
+
+#### Unknown Tag Suggestions
+
+The `Warnings/UnknownTag` validator suggests correct YARD tags for typos:
+
+**Example:**
+
+```ruby
+# @params value [String] should be @param
+# @returns [String] should be @return
+# @raises [Error] should be @raise
+def process(value)
+  # ...
+end
+```
+
+**Output:**
+
+```
+lib/processor.rb:10: [error] Unknown tag @params (did you mean '@param'?)
+lib/processor.rb:11: [error] Unknown tag @returns (did you mean '@return'?)
+lib/processor.rb:12: [error] Unknown tag @raises (did you mean '@raise'?)
+```
+
+#### Unknown Parameter Suggestions
+
+The `Warnings/UnknownParameterName` validator suggests correct parameter names:
+
+**Example:**
+
+```ruby
+# @param usr_name [String] the username
+# @param usr_email [String] the email
+def create_user(user_name, user_email)
+  # ...
+end
+```
+
+**Output:**
+
+```
+lib/user.rb:123: [error] @param tag has unknown parameter name: usr_name (did you mean 'user_name'?)
+lib/user.rb:124: [error] @param tag has unknown parameter name: usr_email (did you mean 'user_email'?)
+```
+
+**How it works:**
+- Uses Ruby's `did_you_mean` gem for intelligent suggestions
+- Falls back to Levenshtein distance algorithm when needed
+- For parameters: Parses method signatures directly from source files for accurate parameter detection
+- Supports all parameter types: regular, keyword, splat, block, and default values
+- For tags: Checks against all standard YARD tags and directives
+
 ### Quick Configuration Examples
 
 ```yaml
@@ -589,7 +695,16 @@ Options:
   -f, --format FORMAT     Output format (text, json)
   -q, --quiet             Quiet mode (only show summary)
       --stats             Show statistics summary
+      --min-coverage N    Minimum documentation coverage required (0-100)
       --[no-]progress     Show progress indicator (default: auto-detect TTY)
+      --diff [REF]        Lint only files changed since REF
+      --staged            Lint only staged files
+      --changed           Lint only uncommitted files
+      --only VALIDATORS   Run only specified validators (comma-separated)
+      --init              Generate .yard-lint.yml config file
+      --update            Update .yard-lint.yml with new validators
+      --strict            Generate strict config (use with --init or --update)
+      --force             Force overwrite when using --init
   -v, --version           Show version
   -h, --help              Show this help
 ```

data/Rakefile

@@ -2,3 +2,23 @@
 
 require 'bundler/setup'
 require 'bundler/gem_tasks'
+require 'etc'
+
+namespace :spec do
+  # Determine optimal number of parallel processes
+  # Use all CPUs if less than 8, otherwise cap at 8
+  def parallel_process_count
+    cpus = Etc.nprocessors
+    [cpus, 8].min
+  end
+
+  desc 'Run integration specs in parallel'
+  task :integrations do
+    sh "bundle exec parallel_rspec -n #{parallel_process_count} spec/integrations/"
+  end
+
+  desc 'Run all specs in parallel'
+  task :parallel do
+    sh "bundle exec parallel_rspec -n #{parallel_process_count} spec/"
+  end
+end

data/bin/yard-lint

@@ -11,7 +11,7 @@ config_file = nil
 diff_mode = nil
 
 OptionParser.new do |opts|
-  opts.banner = 'Usage: yard-lint [options] PATH'
+  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
@@ -52,6 +52,13 @@ OptionParser.new do |opts|
     diff_mode = { mode: :changed }
   end
 
+  opts.separator ''
+  opts.separator 'Validator selection:'
+
+  opts.on('--only VALIDATORS', 'Run only specified validators (comma-separated)') do |validators|
+    options[:only] = validators.split(',').map(&:strip)
+  end
+
   opts.separator ''
   opts.separator 'Other options:'
 
@@ -59,6 +66,14 @@ OptionParser.new do |opts|
     options[:init] = true
   end
 
+  opts.on('--update', 'Update .yard-lint.yml to add new validators and remove obsolete ones') do
+    options[:update] = true
+  end
+
+  opts.on('--strict', 'Generate strict config (all Error severity, 100% coverage). Use with --init or --update') do
+    options[:strict] = true
+  end
+
   opts.on('--force', 'Force overwrite when using --init') do
     options[:force] = true
   end
@@ -72,19 +87,29 @@ OptionParser.new do |opts|
     puts opts
     puts
     puts 'Examples:'
-    puts '  yard-lint lib/                          # Lint all files in lib/'
-    puts '  yard-lint lib/ --diff main              # Lint only files changed since main branch'
-    puts '  yard-lint lib/ --staged                 # Lint only staged files'
-    puts '  yard-lint lib/ --changed                # Lint only uncommitted files'
-    puts '  yard-lint lib/ --format json            # Output in JSON format'
+    puts '  yard-lint                                      # Lint current directory'
+    puts '  yard-lint lib/                                 # Lint all files in lib/'
+    puts '  yard-lint --only Tags/TypeSyntax lib/          # Run only one validator on lib/'
+    puts '  yard-lint --only Tags/Order,Tags/TypeSyntax    # Run specific validators'
+    puts '  yard-lint --diff main                          # Lint files changed since main branch'
+    puts '  yard-lint --staged                             # Lint only staged files'
+    puts '  yard-lint --changed                            # Lint only uncommitted files'
+    puts '  yard-lint --format json lib/                   # Output in JSON format'
+    puts '  yard-lint --init                               # Generate default config'
+    puts '  yard-lint --init --strict                      # Generate strict config'
+    puts '  yard-lint --update                             # Update config with new validators'
     exit
   end
 end.parse!
 
 # Handle --init flag
 if options[:init]
-  if Yard::Lint::ConfigGenerator.generate(force: options[:force])
-    puts 'Created .yard-lint.yml with default configuration'
+  if Yard::Lint::ConfigGenerator.generate(force: options[:force], strict: options[:strict])
+    if options[:strict]
+      puts 'Created .yard-lint.yml with strict configuration (all Error severity, 100% coverage)'
+    else
+      puts 'Created .yard-lint.yml with default configuration'
+    end
     exit 0
   else
     puts 'Error: .yard-lint.yml already exists'
@@ -93,38 +118,35 @@ if options[:init]
   end
 end
 
-# Get path argument
-path = ARGV[0]
+# Handle --update flag
+if options[:update]
+  begin
+    result = Yard::Lint::ConfigUpdater.update(strict: options[:strict])
 
-unless path
-  puts 'Error: PATH argument is required'
-  puts 'Usage: yard-lint [options] PATH'
-  exit 1
+    if result[:added].any? || result[:removed].any?
+      puts 'Updated .yard-lint.yml:'
+      if result[:added].any?
+        puts "  Added #{result[:added].size} new validator(s): #{result[:added].join(', ')}"
+      end
+      if result[:removed].any?
+        puts "  Removed #{result[:removed].size} obsolete validator(s): #{result[:removed].join(', ')}"
+      end
+      puts "  Preserved #{result[:preserved].size} existing validator(s)"
+    else
+      puts '.yard-lint.yml is already up to date'
+    end
+    exit 0
+  rescue Yard::Lint::Errors::ConfigFileNotFoundError => e
+    puts "Error: #{e.message}"
+    exit 1
+  end
 end
 
-# Clear YARD database and command cache to ensure fresh run on each CLI invocation
-#
-# Why this is necessary:
-#
-# 1. **Command Cache Reset** (`reset_command_cache!`)
-#    - The command cache stores results from YARD commands across validator instances
-#    - This cache is shared at the class level (Base.@shared_command_cache)
-#    - Without reset: Results from a previous CLI run could leak into the current run
-#    - Critical for CLI: Each `yard-lint` invocation should start with clean state
-#    - Not needed in-process: Within a single run, caching YARD results is beneficial
-#
-# 2. **YARD Database Clear** (`clear_yard_database!`)
-#    - YARD creates temp database directories for parsing documentation
-#    - Directories are isolated per-argument-set using SHA256 hash (see base.rb:84-97)
-#    - Base temp dir (YARDOC_BASE_TEMP_DIR) persists across CLI invocations
-#    - Without clear: Old databases accumulate in /tmp, wasting disk space
-#    - Database isolation prevents contamination within a single run, but doesn't
-#      clean up between runs
-#
-# In summary: These ensure each CLI invocation is independent and doesn't leak state
-# from previous runs, while also preventing temp directory accumulation.
-Yard::Lint::Validators::Base.reset_command_cache!
-Yard::Lint::Validators::Base.clear_yard_database!
+# Get path argument (defaults to current directory)
+path = ARGV[0] || '.'
+
+# Clear YARD registry to ensure fresh run on each CLI invocation
+YARD::Registry.clear
 
 # Load config and apply CLI overrides
 config = if config_file
@@ -136,6 +158,24 @@ config = if config_file
 # Apply CLI min_coverage override if provided
 config.min_coverage = options[:min_coverage] if options[:min_coverage]
 
+# Apply --only filter if provided
+if options[:only]
+  unknown = options[:only] - Yard::Lint::ConfigLoader::ALL_VALIDATORS
+  if unknown.any?
+    checker = DidYouMean::SpellChecker.new(dictionary: Yard::Lint::ConfigLoader::ALL_VALIDATORS)
+    messages = unknown.map do |name|
+      suggestions = checker.correct(name)
+      suggestions.any? ? "  #{name} (did you mean: #{suggestions.first}?)" : "  #{name}"
+    end
+    puts "Error: Unknown validator(s):"
+    puts messages.join("\n")
+    puts "\nAvailable validators:"
+    Yard::Lint::ConfigLoader::ALL_VALIDATORS.each { |v| puts "  #{v}" }
+    exit 1
+  end
+  config.only_validators = options[:only]
+end
+
 # Run the linter
 begin
   result = Yard::Lint.run(
@@ -147,6 +187,9 @@ begin
 rescue Yard::Lint::Git::Error => e
   puts "Git error: #{e.message}"
   exit 1
+rescue Yard::Lint::Errors::FileNotFoundError => e
+  puts "Error: #{e.message}"
+  exit 1
 end
 
 # Format and display results

data/lib/yard/lint/config.rb

@@ -6,6 +6,7 @@ module Yard
     # Configuration object for YARD Lint
     class Config
       attr_reader :raw_config, :validators
+      attr_accessor :only_validators
 
       # Default YAML config file name
       DEFAULT_CONFIG_FILE = '.yard-lint.yml'
@@ -20,6 +21,7 @@ module Yard
       def initialize(raw_config = {})
         @raw_config = raw_config
         @validators = build_validators_config
+        @only_validators = []
 
         yield self if block_given?
       end
@@ -146,6 +148,9 @@ module Yard
       # @param validator_name [String] full validator name (e.g., 'Tags/Order')
       # @return [Boolean] true if validator is enabled
       def validator_enabled?(validator_name)
+        # If --only is specified, it takes full control
+        return only_validators.include?(validator_name) if only_validators.any?
+
         validator_config = validators[validator_name] || {}
         validator_config['Enabled'] != false # Default to true
       end