yard-lint 1.5.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88a6ef4d1499a08d7c1776c73605011fd32af9c7afc3f473e4e2c000b2f1d4b6
-  data.tar.gz: a4002c074922df07b82d963f8844745bdd925087b1f6f4b2ba87af10dab1e523
+  metadata.gz: ef1425a1be17cac04595b6558a742eb4036fc1cc66891e1d8f31eb46094c8914
+  data.tar.gz: d5ba0ef812eb0261718d7259d2da0b0f0b2fa37a1674893f6d7d3178be3bf551
 SHA512:
-  metadata.gz: 4c7cd92f75e9b839a90340241288966f157c50ba2d82bea1a50892f70b6d62493e81d2f60c4a147616adeada79f65e9ed3ad00fddc6353a9229ec705073ae1c2
-  data.tar.gz: ce364d5460ee86d59e058a78e3d7c72f6d76f32b96279436dd71f9f50b0ff4fb7e16e2bc60a06542642a337707df0df6e8d1e798b0c5282d7f350a3f39a38680
+  metadata.gz: 23d60c91521b5afbadd0a43380682686f7b10aa68a968f5091da2de425f477f71ce3b8a6477ca5d0197d7138979dffc4a0aebe2582b3a64cd4092b18b6222c95
+  data.tar.gz: 966fe65d5e72ba1dbf225fe8802f2259dcdb436a66b2571d6caf7aff7d59491e1b337c7fe4db0e68354bceebb192c89d40ed6c1229b5e2bd2f75d2f5cbde456a

data/CHANGELOG.md

@@ -1,5 +1,56 @@
 # YARD-Lint Changelog
 
+## 1.6.0 (2026-06-11)
+- **[Feature]** New `--format quickfix` output mode emits one offense per line in the standard `file:line: S: Validator: message` format. Vim users can set `makeprg=yard-lint\ --format\ quickfix\ --no-progress\ %` and navigate offenses with `:cnext`/`:cprev`; Emacs users can use it as their `compile-command` and navigate with `M-g n`/`M-g p`. Produces no output (and exits 0) when there are no offenses.
+- **[Feature]** New opt-in validator `Documentation/LineLength` detects documentation comment lines that exceed a configurable maximum length (#176). Disabled by default (`Enabled: false`) to avoid breaking existing projects; enable with `Documentation/LineLength: Enabled: true` and tune with `MaxLength: 120` (default). Uses YARD's already-parsed docstring to determine which source lines belong to the comment block, avoiding fragile backwards-scanning. Each over-length line produces a separate offense at its exact file location.
+- **[Feature]** `Yard::Lint.run` now accepts an optional `source:` keyword argument for linting in-memory source without reading from disk. `path:` is still required and governs config resolution, exclusion matching, and offense location reporting — only the source bytes come from the caller. The CLI gains a corresponding `--stdin` flag (`cat lib/foo.rb | yard-lint --stdin lib/foo.rb`). Enables LSP/editor integration tools (e.g. `solargraph-yard-lint`) to lint unsaved buffers without waiting for a save. (#173)
+- **[Feature]** `Documentation/UndocumentedMethodArguments` now supports an `AllowedMethods` config option. Methods listed there are silently skipped for `@param` documentation checks. Three pattern forms are supported: exact name (`call`), arity notation (`initialize/1` — matches only that parameter count, with `*` and `&` params excluded from the count), and regex (`/^perform/`). Invalid regex patterns are silently ignored; the empty regex `//` is always rejected. Useful for idiomatic Ruby conventions like service objects where `call(args)` is self-documenting, or `respond_to_missing?` / `method_missing` whose arguments are rarely worth documenting.
+- **[Feature]** All Documentation validators (`Documentation/UndocumentedObjects`, `Documentation/UndocumentedMethodArguments`, `Documentation/UndocumentedBooleanMethods`, `Documentation/UndocumentedOptions`, `Documentation/MissingReturn`) now support an `AllowedParentClasses` config option. When set, any class or method whose enclosing class directly inherits from one of the listed base classes is silently skipped by that validator. Useful for exempting exception hierarchies (`StandardError`), ORM model methods (`ActiveRecord::Base`, `ApplicationRecord`), or any framework base class whose subclasses don't need YARD coverage. Uses exact full-path matching (`"ActiveRecord::Base"`, not `"Base"`). `Object` and `BasicObject` are never matched to avoid accidentally exempting all classes.
+- **[Feature]** New opt-in validator `Tags/MissingYield` detects methods that call `yield` in their body but do not document the block with a `@yield`, `@yieldparam`, or `@yieldreturn` tag. Callers need to know a method yields in order to pass a block; the validator checks raw docstring text rather than YARD's inferred tag list, so YARD's automatic `@yield` inference for bare `yield expr` statements does not suppress the offense. Method calls like `Fiber.yield` and `yielder.yield` are not flagged. Disabled by default - enable with `Tags/MissingYield: Enabled: true`.
+- **[Feature]** New opt-in validator `Documentation/TextSubstitution` detects forbidden characters or strings in YARD documentation and suggests user-defined replacements. Ships with em-dash (—, U+2014) and en-dash (–, U+2013) → hyphen as built-in defaults to catch AI-generated punctuation that projects prefer as plain ASCII hyphens. Fully generic — configure any string-to-string rules via `Substitutions`. Content inside fenced code blocks is skipped. Disabled by default. (#182)
+- **[Feature]** New validator `Documentation/OrphanedDocComment` detects YARD comment blocks with tags (`@param`, `@return`, etc.) that are not attached to any documentable Ruby construct and will be silently dropped by YARD. Triggered when a tagged comment is immediately followed by a non-documentable statement (variable assignment, `require`, `include`, etc.) or sits at end-of-file. Enabled by default. Complementary to `Documentation/BlankLineBeforeDefinition` which handles the blank-lines-before-def case.
+- **[Enhancement]** Each offense now includes a `validator` field with the full config key (e.g. `"Documentation/MissingReturn"`, `"Tags/Order"`) identifying which validator produced it. The text formatter also now displays this path instead of the short offense name, making it easier to locate the right `.yard-lint.yml` setting to adjust.
+- **[Fix]** `Tags/InvalidTypes` no longer reports false positives for YARD's semicolon shorthand in multi-pair fixed-shape Hash types (#171)
+  - Types like `Hash{:range => Hash; :severity => Integer; :source, :code, :message => String}` were incorrectly flagged because `;` was not included in the type-name splitter's delimiter set, leaving fragments such as `Hash;` and `Integer;` as tokens that appeared invalid
+  - Added `;` to the `extract_type_names` regex so each component is extracted cleanly; invalid types genuinely nested inside semicolon-delimited pairs are still caught
+- **[Enhancement]** Add Ruby warning category opt-in to test helpers
+- **[Fix]** Use `remove_method` instead of `define_singleton_method` to restore `warn` in `InProcessRegistry#capture_warnings`, eliminating a spurious method redefinition warning
+
+## 1.5.2 (2026-06-02)
+- **[Fix]** `Tags/InvalidTypes` no longer reports false positives for YARD pseudo-types `undefined`, `unspecified`, and `unknown` (#152)
+  - These lowercase pseudo-types are used in real-world YARD docs (e.g. Solargraph uses `Hash{String => undefined}` extensively) to signal that a type is intentionally unspecified
+  - They are now treated as valid types alongside the existing `nil`, `void`, `self`, `true`, `false` defaults
+- **[Fix]** `Tags/InvalidTypes` no longer reports false positives for string literal hash keys (e.g. `Hash{"to" => String}`) (#152)
+  - String literal keys like `"email"` or `"name"` are valid YARD hash key notation and are now treated as valid alongside the existing symbol literal support (`:key`)
+- **[Fix]** `Tags/InvalidTypes` no longer reports false positives for nested `Hash{K => V}` types (#151, #152)
+  - Complex hash types such as `Hash{String => Hash{Symbol => Array<String>}}` were occasionally flagged as invalid; the `extract_type_names` splitter already handled them correctly after the 1.5.2 sanitizer rewrite, and regression tests now lock that behaviour in
+  - Invalid types genuinely nested inside hash values (e.g. `Hash{String => bad_type}`) are still caught and surfaced correctly
+- **[Enhancement]** `Tags/InvalidTypes` offense messages now name the invalid type(s) and the tag they appear in (#151)
+  - Previously reported a generic `"has at least one tag with an invalid type definition"` message with no further detail
+  - Now reports `"has invalid type(s): @param body: \`bad_type\`; @return: \`wrong_type\`"` - the exact offending type and the tag (including param name for `@param`) where it was found
+- **[Fix]** Do not flag `@param` on `Struct.new` / `Data.define` constants in `Tags/MeaninglessTag` (#152)
+  - Solargraph uses `@param` annotations on these constants to type the synthesised accessors; flagging them was a false positive
+  - `@option` on these constants is still reported as meaningless
+- **[Fix]** Fix `--auto-gen-config` crash (`NoMethodError`) when a YARD warning is emitted without file context (#150)
+  - A `@!macro [new]` body with an invalid tag format (e.g. `@return name [Type]`) that is also referenced inside the defining method's body causes YARD to expand the macro with `object=nil`, emitting `Invalid tag format` without a file path → `offense[:location] = nil` → `make_relative_path(nil)` → crash
+  - `TodoGenerator#make_relative_path` now returns `nil` for `nil` input; `run_linting` uses `filter_map` to skip nil locations when building exclusion lists
+  - `Runner#filter_result_offenses` now always drops nil-location offenses before exclusion-pattern filtering (they would otherwise appear as `:0` in output)
+  - Fix `Warnings/DuplicatedParameterName::Parser`: was inheriting from `OneLineBase` despite YARD emitting the warning across two lines (same format as `UnknownParameterName`), causing `offense[:location]` to always be `nil`; switched to `TwoLineBase` and corrected the location regex to match YARD's backtick-open/single-quote-close path format
+- **[Fix]** Stop false positives for allowed defaults (`self`, `nil`, `true`, `false`, `void`) inside generic types in `Tags/InvalidTypes` validator
+  - Types like `Array<self>`, `Hash{Symbol => nil}`, `Array<true>` were incorrectly flagged as `InvalidTagType` because the sanitize logic concatenated type components (e.g., `Array<self>` became `Arrayself`, which is not in `ALLOWED_DEFAULTS`)
+  - Replaced the `tr`-based sanitizer with a proper type name splitter that checks each component individually
+- **[Fix]** Validate types inside `@overload` blocks across all type validators (`Tags/TypeSyntax`, `Tags/InvalidTypes`, `Tags/CollectionType`, `Tags/NonAsciiType`)
+  - YARD stores `@overload` inner tags on the overload's own docstring, making them invisible to validators that only traverse `object.docstring.tags`
+  - Added `all_typed_tags` helper to `Validators::Base` that collects matching tags from both the docstring and any `@overload` blocks
+- **[Fix]** Add `@raise` and `@yieldparam` to `ValidatedTags` in all type validators
+  - `@raise` tag types (e.g., `@raise [ArgumentError]`) were never validated for type syntax or correctness by any validator
+  - `@yieldparam` was missing from `Tags/InvalidTypes`, `Tags/TypeSyntax`, and `Tags/CollectionType` (only `Tags/NonAsciiType` included it)
+  - Both tags are now validated consistently across `Tags/InvalidTypes`, `Tags/TypeSyntax`, `Tags/CollectionType`, and `Tags/NonAsciiType`
+- **[Fix]** Skip attribute methods in `Tags/ApiTags` validator (#128)
+  - Methods generated by `attr_*`, `@!attribute` directives, `Struct.new`, and `Data.define` are no longer flagged for missing `@api` tags
+  - YARD's `Data.define` and `Struct.new` handlers hard-replace the generated methods' docstrings, stripping any `@api` tag inherited from the enclosing class, and `@!attribute` directives written above a `Data.define` constant attach to the wrong namespace - leaving users with no way to attach per-method `@api` tags to those accessors
+  - Matches the approach taken for `UndocumentedMethodArguments` in #115
+
 ## 1.5.1 (2026-04-09)
 - **[Fix]** Remove `mise.toml` and `proxy_types` from the repository and exclude non-production files (`.ruby-version`, `Rakefile`, `misc/`, `renovate.json`, `package.json`, `package-lock.json`, lock files) from RubyGems releases
 

data/README.md

@@ -19,18 +19,18 @@ Accurate documentation isn't just for human developers anymore. [Research shows]
 
 YARD-Lint validates your YARD documentation for:
 
-- **Documentation Completeness** - Undocumented classes, modules, methods, parameters, boolean return values, and missing `@return` tags
+- **Documentation Completeness** - Undocumented classes, modules, methods, parameters, boolean return values, and missing `@return` tags; orphaned doc comments with YARD tags that YARD silently drops
 - **Type Accuracy** - Invalid type definitions, malformed type syntax, non-ASCII characters in types, tuple types, and literal types (symbols, strings, numbers)
-- **Tag Validation** - Incorrect tag ordering, meaningless tags, invalid tag positions, unknown tags with suggestions, forbidden tag patterns
+- **Tag Validation** - Incorrect tag ordering, meaningless tags, invalid tag positions, unknown tags with suggestions, forbidden tag patterns, undocumented `yield` calls (opt-in)
 - **Code Examples** - Syntax validation in `@example` tags, optional style validation with RuboCop/StandardRB
 - **Semantic Correctness** - Abstract methods with implementations, redundant descriptions
-- **Style & Formatting** - Empty comment lines, blank lines before definitions, informal notation patterns, tag group separators
+- **Style & Formatting** - Empty comment lines, blank lines before definitions, informal notation patterns, tag group separators, configurable documentation line length (opt-in)
 - **Smart Suggestions** - "Did you mean" suggestions for typos in parameter names, tags, and configuration settings
 - **Configuration Safety** - Validates `.yard-lint.yml` for typos and invalid settings before processing
 - **Performance** - In-process YARD execution with shared registry (~10x faster than shell-based execution)
 - **Incremental Adoption** - `--auto-gen-config` generates a baseline todo file to adopt on legacy codebases without fixing everything first
 
-**See the complete list:** [All Features](https://github.com/mensfeld/yard-lint/wiki/Features) | [30 Validators](https://github.com/mensfeld/yard-lint/wiki/Validators)
+**See the complete list:** [All Features](https://github.com/mensfeld/yard-lint/wiki/Features) | [34 Validators](https://github.com/mensfeld/yard-lint/wiki/Validators)
 
 ## Installation
 
@@ -142,6 +142,63 @@ yard-lint lib/ --only Tags/Order,Documentation/UndocumentedObjects
 
 **Learn more:** [Advanced Usage Guide](https://github.com/mensfeld/yard-lint/wiki/Advanced-Usage)
 
+### Lint from stdin (LSP / Editor Integration)
+
+Pass source bytes directly without reading from disk. The `path` argument is still required - it governs config resolution, exclusion matching, and offense location reporting.
+
+**CLI:**
+
+```bash
+# Lint source piped through stdin - path is used for config/reporting only
+cat lib/foo.rb | yard-lint --stdin lib/foo.rb
+```
+
+**Ruby API:**
+
+```ruby
+# Lint an in-memory buffer - file does not need to exist on disk
+result = Yard::Lint.run(
+  path: 'lib/foo.rb',            # used for config, exclusions, and offense locations
+  source: editor_buffer_content, # actual source bytes to lint
+  progress: false
+)
+```
+
+This is how [solargraph-yard-lint](https://github.com/lekemula/solargraph-yard-lint) surfaces yard-lint offenses on unsaved editor buffers - the file path provides context while the live buffer content is linted directly, matching the behaviour of RuboCop's `--stdin` flag.
+
+### Quickfix Output (Vim / Emacs)
+
+Use `--format quickfix` to get one offense per line in the standard `file:line: S: Validator: message` format that editors parse natively for their quickfix/error lists:
+
+```bash
+yard-lint --format quickfix lib/
+```
+
+Example output:
+
+```
+lib/foo.rb:42: E: Documentation/UndocumentedObjects: Class Foo is not documented
+lib/foo.rb:57: W: Tags/InvalidTypes: has invalid type(s): @return: `Sting`
+lib/bar.rb:12: C: Tags/Order: Tags are not in the correct order
+```
+
+**Vim** — set `makeprg` and use `:make` to populate the quickfix list:
+
+```vim
+set makeprg=yard-lint\ --format\ quickfix\ --no-progress\ %
+set errorformat=%f:%l:\ %t:\ %m
+```
+
+Then `:make` lints the current file and `:cnext` / `:cprev` jump between offenses. Note: Vim only recognises `E` and `W` as named types for `:clist E`/`:clist W` filtering — `C` (convention) offenses are stored and navigable but appear without a named type in filtered views.
+
+**Emacs** — set `compile-command`:
+
+```elisp
+(setq compile-command "yard-lint --format quickfix --no-progress lib/")
+```
+
+Then `M-x compile` and `M-g n` / `M-g p` navigate between offenses.
+
 ## Configuration Basics
 
 Create a `.yard-lint.yml` file in your project root:
@@ -173,10 +230,19 @@ Documentation/UndocumentedObjects:
   ExcludedMethods:
     - 'initialize/0'
     - '/^_/'
+  # Skip classes inheriting from these base classes (exact full-path match)
+  AllowedParentClasses:
+    - StandardError
+    - ActiveRecord::Base
 
 Documentation/UndocumentedMethodArguments:
   Enabled: true
   Severity: warning
+  # Skip @param checks for specific methods (exact name, name/arity, /regex/)
+  AllowedMethods:
+    - call            # service objects: call(args) is self-documenting
+    - perform         # background jobs
+    - initialize/1    # only this specific arity of initialize
 
 Tags/Order:
   Enabled: true
@@ -197,8 +263,11 @@ Tags/Order:
 Tags/InvalidTypes:
   Enabled: true
   Severity: warning
+  # ExtraTypes: declare non-standard type names that should not be flagged.
+  # Useful for project aliases, LSP extensions (e.g. Solargraph's `generic`),
+  # or any informal type name your team uses in YARD docs.
   ExtraTypes:
-    - CustomType
+    - generic          # Solargraph generic type parameter (lsegal/yard#1683)
     - MyNamespace::CustomType
 
 # Opt-in: Require @return tags on all methods
@@ -212,6 +281,11 @@ Documentation/MissingReturn:
 Tags/ExampleStyle:
   Enabled: true
   Severity: convention
+
+# Opt-in: Enforce max line length in documentation comments
+Documentation/LineLength:
+  Enabled: true
+  MaxLength: 100
 ```
 
 **Key features:**
@@ -222,6 +296,113 @@ Tags/ExampleStyle:
 
 **Learn more:** [Complete Configuration Guide](https://github.com/mensfeld/yard-lint/wiki/Configuration)
 
+## Catching Orphaned Documentation Comments
+
+YARD silently ignores comment blocks that contain YARD tags (`@param`, `@return`, etc.) when they are not immediately followed by a documentable construct (method, class, module, constant, attribute). This happens with local variable assignments, `require` calls, `include`/`extend` statements, bare `private`/`public` keywords, or comments at the end of a file - the documentation is simply lost with no warning.
+
+The `Documentation/OrphanedDocComment` validator (enabled by default) catches this:
+
+```ruby
+# Bad - YARD drops this silently; local variable is not documentable
+# @param name [String] the name
+# @return [void]
+local_var = "value"
+
+# Bad - require is not documentable
+# @param id [Integer] user id
+# @return [User]
+require 'some_gem'
+
+# Bad - orphaned at end of file
+# @param id [Integer] user id
+# @return [User]
+
+# Good - properly attached to a method
+# @param name [String] the name
+# @return [void]
+def greet(name); end
+
+# Good - constant assignments are documentable, not flagged
+# @return [Integer] the answer
+ANSWER = 42
+```
+
+This validator is complementary to `Documentation/BlankLineBeforeDefinition` (which handles the case where blank lines separate a doc comment from a `def` - YARD still attaches it despite the gap).
+
+## Documenting yield (opt-in)
+
+The `Tags/MissingYield` validator (opt-in, disabled by default) detects methods that call `yield` in their body but do not document the block with a `@yield`, `@yieldparam`, or `@yieldreturn` tag. Callers need to know a method yields in order to pass a block.
+
+Enable it in `.yard-lint.yml`:
+
+```yaml
+Tags/MissingYield:
+  Enabled: true
+  Severity: warning
+```
+
+```ruby
+# Bad - method yields but block is not documented
+# @param items [Array] the items to process
+def each(items)
+  items.each { |item| yield item }
+end
+
+# Good - block documented with @yield
+# @param items [Array] the items to process
+# @yield [item] each item in the collection
+def each(items)
+  items.each { |item| yield item }
+end
+
+# Good - @yieldparam is also accepted
+# @param items [Array] the items to process
+# @yieldparam item [Object] each item
+def each(items)
+  items.each { |item| yield item }
+end
+```
+
+Method calls like `Fiber.yield` and `yielder.yield` (Enumerator::Yielder) are not flagged - only the `yield` keyword triggers the check.
+
+## Handling Non-Standard Types
+
+By default `Tags/InvalidTypes` accepts all built-in Ruby classes, constants, and a set of YARD pseudo-types (`nil`, `true`, `false`, `self`, `void`, `undefined`, `unspecified`, `unknown`). If your project uses additional type names that are not real Ruby classes - project-specific aliases, LSP extensions, or informal conventions - you can declare them via `ExtraTypes` so yard-lint does not report them as `InvalidTagType` offenses.
+
+### Project-Specific Type Aliases
+
+```yaml
+Tags/InvalidTypes:
+  ExtraTypes:
+    - Callable        # informal "anything that responds to #call"
+    - Awaitable       # async type alias used across the project
+    - Result          # dry-monad-style Result type used in prose docs
+```
+
+### LSP / Tool-Specific Extensions
+
+[Solargraph](https://solargraph.org) supports a `generic` type-parameter notation (e.g. `Hash{Class<generic<T>> => Set<generic<T>>}`) that is [proposed for adoption](https://github.com/lsegal/yard/issues/1683) but not yet part of the YARD standard. Until it is, add it to `ExtraTypes` to prevent false positives:
+
+```yaml
+Tags/InvalidTypes:
+  ExtraTypes:
+    - generic
+```
+
+### Built-In Pseudo-Types (no configuration needed)
+
+The following lowercase YARD pseudo-types are accepted out of the box and do **not** need to be listed in `ExtraTypes`:
+
+| Type | Meaning |
+|------|---------|
+| `nil` | Explicitly nil |
+| `true` / `false` | Boolean literals |
+| `self` | Returns the receiver |
+| `void` | No meaningful return value |
+| `undefined` | Type is intentionally unspecified (used by Solargraph) |
+| `unspecified` | Alias for undefined |
+| `unknown` | Type is unknown |
+
 ## CI Integration
 
 ### GitHub Actions
@@ -253,7 +434,7 @@ jobs:
 ```bash
 #!/bin/bash
 # .git/hooks/pre-commit
-bundle exec yard-lint lib/ --staged --fail-on-severity error
+bundle exec yard-lint lib/ --staged
 ```
 
 ### GitLab CI
@@ -279,10 +460,11 @@ Configuration:
   -c, --config FILE       Path to config file (default: .yard-lint.yml)
 
 Output:
-  -f, --format FORMAT     Output format (text, json)
+  -f, --format FORMAT     Output format (text, json, quickfix)
   -q, --quiet             Quiet mode (only show summary)
       --stats             Show documentation coverage statistics
       --[no-]progress     Show progress indicator (default: auto-detect TTY)
+      --stdin             Read source from stdin; PATH still required for config/reporting
 
 Coverage:
       --min-coverage N    Minimum documentation coverage required (0-100)
@@ -311,6 +493,23 @@ Information:
 
 **Learn more:** [Advanced Usage](https://github.com/mensfeld/yard-lint/wiki/Advanced-Usage) - CLI reference, JSON output, coverage
 
+## Offense Structure
+
+Every offense (in text, JSON, and quickfix output) includes a `validator` field with the full config key that produced it, making it easy to find the right `.yard-lint.yml` setting to adjust:
+
+```json
+{
+  "name": "OrphanedDocComment",
+  "validator": "Documentation/OrphanedDocComment",
+  "severity": "warning",
+  "message": "Documentation comment with @param, @return is orphaned - YARD will ignore it",
+  "location": "lib/my_class.rb",
+  "location_line": 42
+}
+```
+
+The text formatter also shows the validator path (e.g., `[Documentation/OrphanedDocComment]`) instead of just the short offense name.
+
 ## Documentation
 
 ### Quick Links
@@ -318,7 +517,7 @@ Information:
 - **[Wiki Home](https://github.com/mensfeld/yard-lint/wiki)** - Full documentation
 - **[Installation](https://github.com/mensfeld/yard-lint/wiki/Installation)** - Installation guide
 - **[Configuration](https://github.com/mensfeld/yard-lint/wiki/Configuration)** - Complete configuration reference
-- **[Validators](https://github.com/mensfeld/yard-lint/wiki/Validators)** - All 30 validators documented
+- **[Validators](https://github.com/mensfeld/yard-lint/wiki/Validators)** - All 34 validators documented
 - **[Features](https://github.com/mensfeld/yard-lint/wiki/Features)** - All features explained
 
 ### Workflows

data/bin/yard-lint

@@ -17,7 +17,7 @@ OptionParser.new do |opts|
     config_file = file
   end
 
-  opts.on('-f', '--format FORMAT', 'Output format (text, json)') do |format|
+  opts.on('-f', '--format FORMAT', 'Output format (text, json, quickfix)') do |format|
     options[:format] = format
   end
 
@@ -37,6 +37,10 @@ OptionParser.new do |opts|
     options[:progress] = value
   end
 
+  opts.on('--stdin', 'Read source from stdin; PATH argument is required for config/reporting') do
+    options[:stdin] = true
+  end
+
   opts.separator ''
   opts.separator 'Diff mode options (mutually exclusive):'
 
@@ -111,12 +115,14 @@ OptionParser.new do |opts|
     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 --format quickfix lib/               # Output in quickfix format (Vim/Emacs)'
     puts '  yard-lint --init                               # Generate default config'
     puts '  yard-lint --init --strict                      # Generate strict config'
     puts '  yard-lint --update                             # Update config with new validators'
     puts '  yard-lint --auto-gen-config                    # Generate todo file for existing violations'
     puts '  yard-lint --regenerate-todo                    # Regenerate todo file'
     puts '  yard-lint --auto-gen-config --exclude-limit 10 # Custom grouping threshold'
+    puts '  cat lib/foo.rb | yard-lint --stdin lib/foo.rb  # Lint source piped from stdin'
     exit
   end
 end.parse!
@@ -199,6 +205,16 @@ end
 # Get path argument (defaults to current directory)
 path = ARGV[0] || '.'
 
+# Read stdin source when --stdin flag is given
+stdin_source = nil
+if options[:stdin]
+  if path == '.' || File.directory?(path)
+    puts 'Error: --stdin requires an explicit file path argument (e.g. yard-lint --stdin lib/foo.rb)'
+    exit 1
+  end
+  stdin_source = $stdin.read
+end
+
 # Clear YARD registry to ensure fresh run on each CLI invocation
 YARD::Registry.clear
 
@@ -235,14 +251,21 @@ if options[:only]
   config.only_validators = options[:only]
 end
 
+# Suppress progress for quickfix to avoid contaminating machine-readable output
+options[:progress] = false if options[:format] == 'quickfix' && options[:progress].nil?
+
 # Run the linter
 begin
   result = Yard::Lint.run(
     path: path,
     config: config,
     progress: options[:progress],
-    diff: diff_mode
+    diff: diff_mode,
+    source: stdin_source
   )
+rescue ArgumentError => e
+  puts "Error: #{e.message}"
+  exit 1
 rescue Yard::Lint::Git::Error => e
   puts "Git error: #{e.message}"
   exit 1
@@ -251,6 +274,11 @@ rescue Yard::Lint::Errors::FileNotFoundError => e
   exit 1
 end
 
+# Maps a severity string to its single-character quickfix/display code
+severity_char = lambda do |s|
+  { 'error' => 'E', 'warning' => 'W', 'convention' => 'C', 'never' => 'C' }.fetch(s.to_s, '?')
+end
+
 # Format and display results
 case options[:format]
 when 'json'
@@ -260,6 +288,19 @@ when 'json'
     offenses: result.offenses
   })
   exit result.exit_code
+when 'quickfix'
+  if config.min_coverage
+    coverage = result.documentation_coverage
+    if coverage && coverage[:coverage] < config.min_coverage
+      warn "Error: Documentation coverage #{coverage[:coverage].round(2)}% is below minimum #{config.min_coverage}%"
+    end
+  end
+  result.offenses.each do |offense|
+    char = severity_char.call(offense[:severity])
+    message = offense[:message].to_s.gsub(/\n/, ' ')
+    puts "#{offense[:location]}:#{offense[:location_line]}: #{char}: #{offense[:validator]}: #{message}"
+  end
+  exit result.exit_code
 when 'text', nil
   # Calculate coverage stats if requested or configured
   coverage = result.documentation_coverage if options[:stats] || options[:min_coverage] || config.min_coverage
@@ -306,15 +347,8 @@ when 'text', nil
       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 "[#{severity_char.call(offense[:severity])}] #{offense[:location]}:#{offense[:location_line]}"
+        puts "    #{offense[:validator]}: #{offense[:message]}"
         puts
       end
     end

data/lib/yard/lint/executor/in_process_registry.rb

@@ -21,8 +21,10 @@ module Yard
         # Parse Ruby source files and populate the YARD registry.
         # Captures any warnings emitted by YARD during parsing for later dispatch.
         # @param files [Array<String>] absolute or relative paths to Ruby source files
+        # @param source [String, nil] in-memory source; when given, `files.first` is used
+        #   as the virtual filename for registry/location reporting only
         # @return [void]
-        def parse(files)
+        def parse(files, source: nil)
           @mutex.synchronize do
             return if @parsed
 
@@ -33,16 +35,28 @@ module Yard
             original_level = YARD::Logger.instance.level
             YARD::Logger.instance.level = 4 # Only show fatal errors
 
-            # First pass: parse all files to process directive definitions
-            YARD.parse(files)
-
-            # Clear checksums to force reparsing without clearing the registry.
-            # This allows macro definitions from the first pass to be available
-            # during the second pass, enabling proper directive expansion regardless of parse order.
-            YARD::Registry.checksums.clear
+            if source
+              virtual_path = files.first
+              # First pass: register directive/macro definitions from the in-memory source.
+              # We set parser.file manually so registered objects carry the virtual path.
+              parse_source_string(source, virtual_path)
+              # Clear checksums so the second pass is not skipped
+              YARD::Registry.checksums.clear
+              # Second pass: full parse with all directives available
+              @warnings = capture_warnings { parse_source_string(source, virtual_path) }
+            else
+              # First pass: parse all files to process directive definitions
+              YARD.parse(files)
+
+              # Clear checksums to force reparsing without clearing the registry.
+              # This allows macro definitions from the first pass to be available
+              # during the second pass, enabling proper directive expansion regardless of parse order.
+              YARD::Registry.checksums.clear
+
+              # Second pass: reparse files now that all directive definitions are available
+              @warnings = capture_warnings { YARD.parse(files) }
+            end
 
-            # Second pass: reparse files now that all directive definitions are available
-            @warnings = capture_warnings { YARD.parse(files) }
             @parsed = true
 
             YARD::Logger.instance.level = original_level
@@ -110,6 +124,18 @@ module Yard
 
         private
 
+        # Parse Ruby source from a string and register objects under a virtual path.
+        # YARD::Parser::SourceParser#parse accepts a StringIO but keeps @file as '(stdin)'
+        # unless we set it explicitly before parsing.
+        # @param source [String] Ruby source code to parse
+        # @param virtual_path [String] filename to assign to registered objects
+        # @return [void]
+        def parse_source_string(source, virtual_path)
+          parser = YARD::Parser::SourceParser.new(:ruby)
+          parser.file = virtual_path
+          parser.parse(StringIO.new(source))
+        end
+
         # Capture warnings during a block execution
         # @yield Block to execute while capturing warnings
         # @return [Array<String>] captured warnings
@@ -130,8 +156,8 @@ module Yard
 
           captured
         ensure
-          # Restore original warn method
-          YARD::Logger.instance.define_singleton_method(:warn, original_warn) if original_warn
+          sc = YARD::Logger.instance.singleton_class
+          sc.remove_method(:warn) if sc.public_instance_methods(false).include?(:warn)
         end
       end
     end

data/lib/yard/lint/results/base.rb

@@ -96,6 +96,8 @@ module Yard
         # @return [String] validator name for config lookup
         def validator_name
           # Extract from class path: Validators::Tags::Order::Result => 'Tags/Order'
+          return '' unless self.class.name
+
           parts = self.class.name.split('::')
           validators_index = parts.index('Validators')
           return '' unless validators_index
@@ -125,6 +127,7 @@ module Yard
               severity: configured_severity,
               type: self.class.offense_type,
               name: computed_offense_name,
+              validator: validator_name,
               message: build_message(offense_data),
               location: offense_data[:location] || offense_data[:file],
               location_line: offense_data[:line] || offense_data[:location_line] || 0

data/lib/yard/lint/runner.rb

@@ -15,9 +15,11 @@ module Yard
 
       # @param selection [Array<String>] array with ruby files to check
       # @param config [Yard::Lint::Config] configuration object
-      def initialize(selection, config = Config.new)
+      # @param source [String, nil] in-memory source content (overrides disk reads)
+      def initialize(selection, config = Config.new, source: nil)
         @selection = Array(selection).flatten
         @config = config
+        @source = source
         @result_builder = ResultBuilder.new(config)
         @progress_formatter = nil
       end
@@ -45,7 +47,7 @@ module Yard
 
         # Initialize in-process infrastructure
         registry = Executor::InProcessRegistry.new
-        registry.parse(selection)
+        registry.parse(selection, source: @source)
 
         query_executor = Executor::QueryExecutor.new(registry)
         warning_dispatcher = Executor::WarningDispatcher.new
@@ -108,12 +110,18 @@ module Yard
       end
 
       # Filter result offenses based on per-validator exclusions
-      # Removes offenses where the file path matches exclusion patterns
+      # Also always removes offenses with no file location (e.g. YARD warnings
+      # emitted without file context such as from macro expansion with nil object)
+      # since they carry no actionable information and would display as `:0`.
       # @param validator_name [String] full validator name
       # @param result [Results::Base] result object with offenses
       # @return [Results::Base, nil] result with filtered offenses, or nil if no offenses remain
       def filter_result_offenses(validator_name, result)
         validator_excludes = config.validator_all_excludes(validator_name)
+
+        # Drop offenses with no file location regardless of exclusion config
+        result.offenses = result.offenses.reject { |o| (o[:location] || o[:file]).nil? }
+        return nil if result.offenses.empty?
         return result if validator_excludes.empty?
 
         working_dir = Dir.pwd