yard-lint 1.5.2 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c96b4e1a2adb1c849b9716bbf413db8a9515cab506a350219351f56f140e19c
-  data.tar.gz: c5857861bf183876d1030d9b07b7ed295cb08f6951629d651a54a2aec4e4df54
+  metadata.gz: ef1425a1be17cac04595b6558a742eb4036fc1cc66891e1d8f31eb46094c8914
+  data.tar.gz: d5ba0ef812eb0261718d7259d2da0b0f0b2fa37a1674893f6d7d3178be3bf551
 SHA512:
-  metadata.gz: 1c3b748cfcc894cd34715e4cda65a62b321fb1d96372a3b49934c2516dc8f74e60ab1cf3e632cca6491da37951a0b0713149f57545aae6d495b6e45530bc169b
-  data.tar.gz: 95132fedf072bb07466bc1d83e8a3b0bcc37df8e5ad85a811e20ddeaf8c30c354af89282de66df03cbcfc2fdae7721637772863828eba3a2b228e95993985faa
+  metadata.gz: 23d60c91521b5afbadd0a43380682686f7b10aa68a968f5091da2de425f477f71ce3b8a6477ca5d0197d7138979dffc4a0aebe2582b3a64cd4092b18b6222c95
+  data.tar.gz: 966fe65d5e72ba1dbf225fe8802f2259dcdb436a66b2571d6caf7aff7d59491e1b337c7fe4db0e68354bceebb192c89d40ed6c1229b5e2bd2f75d2f5cbde456a

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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
@@ -11,7 +27,7 @@
   - 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
+  - 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
@@ -32,7 +48,7 @@
   - 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
+  - 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)

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
@@ -215,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:**
@@ -225,6 +296,75 @@ 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.
@@ -294,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
@@ -320,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)
@@ -352,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
@@ -359,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

data/lib/yard/lint/templates/default_config.yml

@@ -36,21 +36,34 @@ Documentation/UndocumentedObjects:
   ExcludedMethods:
     - 'initialize/0'  # Exclude parameter-less initialize
     - '/^_/'          # Exclude private methods (by convention)
+  # AllowedParentClasses:
+  #   - StandardError           # Skip error subclasses
+  #   - ApplicationRecord       # Skip Rails model subclasses
 
 Documentation/UndocumentedMethodArguments:
   Description: 'Checks for method parameters without @param tags.'
   Enabled: true
   Severity: warning
+  # AllowedParentClasses:
+  #   - StandardError
+  # AllowedMethods: skip @param checks for specific methods (exact name, name/arity, /regex/)
+  #   - call
+  #   - perform
+  #   - initialize/1
 
 Documentation/UndocumentedBooleanMethods:
   Description: 'Checks that question mark methods document their boolean return.'
   Enabled: true
   Severity: warning
+  # AllowedParentClasses:
+  #   - StandardError
 
 Documentation/UndocumentedOptions:
   Description: 'Detects methods with options hash parameters but no @option tags.'
   Enabled: true
   Severity: warning
+  # AllowedParentClasses:
+  #   - StandardError
 
 Documentation/MissingReturn:
   Description: 'Requires @return tags on all methods (opt-in for strict documentation).'
@@ -59,6 +72,13 @@ Documentation/MissingReturn:
   ExcludedMethods:
     - 'initialize'    # Exclude all initialize methods
     # - '/^_/'        # Uncomment to exclude private methods (by convention)
+  # AllowedParentClasses:
+  #   - StandardError
+
+Documentation/OrphanedDocComment:
+  Description: 'Detects YARD comment blocks with tags not attached to any documentable construct.'
+  Enabled: true
+  Severity: warning
 
 Documentation/MarkdownSyntax:
   Description: 'Detects common markdown syntax errors in documentation.'
@@ -82,6 +102,20 @@ Documentation/BlankLineBeforeDefinition:
     SingleBlankLine: true
     OrphanedDocs: true
 
+Documentation/LineLength:
+  Description: 'Detects documentation comment lines that exceed the configured maximum length.'
+  Enabled: false  # Opt-in validator
+  Severity: convention
+  MaxLength: 120
+
+Documentation/TextSubstitution:
+  Description: 'Detects forbidden characters or strings in documentation and suggests replacements.'
+  Enabled: false  # Opt-in validator
+  Severity: warning
+  Substitutions:
+    "—": "-"    # em-dash (U+2014)
+    "–": "-"    # en-dash (U+2013)
+
 # Tags validators
 Tags/Order:
   Description: 'Enforces consistent ordering of YARD tags.'
@@ -131,6 +165,11 @@ Tags/MeaninglessTag:
     - module
     - constant
 
+Tags/MissingYield:
+  Description: 'Detects methods that yield to a block without a @yield, @yieldparam, or @yieldreturn tag.'
+  Enabled: false  # Opt-in validator
+  Severity: warning
+
 Tags/CollectionType:
   Description: 'Validates Hash collection syntax consistency.'
   Enabled: true
@@ -205,6 +244,7 @@ Tags/RedundantParamDescription:
     - element
   EnabledPatterns:
     ArticleParam: true
+    ArticleParamPhrase: true
     PossessiveParam: true
     TypeRestatement: true
     ParamToVerb: true