Bump yard-lint from 1.5.2 to 1.7.0

[dependabot]

Bumps yard-lint from 1.5.2 to 1.7.0.

Release notes

Sourced from yard-lint's releases.

v1.7.0

• [Feature] Tags/ExampleSyntax gained an opt-in SkipNonRuby option (default false). The validator compiles every @example body as Ruby, so an irb/pry session, its => output, or a shell $ transcript was reported as a syntax error. With SkipNonRuby: true, @example blocks that are interactive console transcripts are skipped. Off by default so a genuine syntax error in a normal example is not hidden.
• [Feature] Tags/InvalidTypes gained an opt-in StrictConstantNames option (default false). The type check was deliberately lenient - any syntactically valid constant name was accepted - so a misspelled class name like Strng was never flagged, defeating the validator's headline use case. With StrictConstantNames: true, a CamelCase type that is neither a loaded Ruby constant nor resolvable in the analyzed codebase's YARD registry is reported. It stays off by default (types defined only in un-analyzed dependencies would otherwise be flagged - add those to ExtraTypes); the strict template (--init --strict) enables it. Boolean is now always accepted as a pseudo-type.
• [Feature] Tags/InformalNotation gained an opt-in SkipIndentedCodeBlocks option (default false). The validator skipped fenced (```) code blocks but not 4-space/tab indented Markdown code blocks, so informal-looking text inside an indented code sample (e.g. Note:) was flagged. With SkipIndentedCodeBlocks: true, indented code lines are skipped too. Off by default because indented text is also used for list continuations and wrapped prose.
• [Feature] Added Warnings/SyntaxError (enabled by default, severity error). A Ruby file YARD cannot parse used to be silently skipped - it registered no objects, produced no offense, and a run could exit 0 over code that does not even parse. The parser error is now surfaced as an offense (with file and line), so the run exits non-zero. Disable with Warnings/SyntaxError: { Enabled: false }.
• [Fix] Documentation/UndocumentedMethodArguments now matches each parameter to a @param tag by name instead of only comparing counts, so a misnamed tag (e.g. @param wrong for def push(item)) is now caught - the count-only check accepted it. This is the new default; set CheckParameterNames: false to restore the lenient count-only comparison. A separate opt-in SkipFullyUndocumented (default false) skips methods with no documentation at all, leaving them to Documentation/UndocumentedObjects instead of reporting the same method twice.
• [Fix] yard-lint --diff PATH (e.g. --diff lib/) no longer fails with fatal: ambiguous argument 'lib/...HEAD'. Because --diff [REF] takes an optional argument, OptionParser consumed the path as the REF, leaving no path. The --diff argument is now treated as the path (with the base ref auto-detected) when it is not a resolvable git ref but is an existing path; an explicit ref (--diff main), ref-plus-path (--diff main lib/), and an unknown ref (which still errors) are unaffected.
• [Fix] Documentation/TextSubstitution no longer flags a forbidden string that appears inside an inline code span (`…`). It already skipped fenced ``` code blocks but matched against the raw line, so e.g. an em-dash inside `start — finish` was reported even though it is literal code, not prose to substitute. Matching now ignores inline code spans; a forbidden string elsewhere in prose on the same line is still flagged.
• [Fix] Documentation/OrphanedDocComment no longer treats #-leading lines inside heredocs or string literals as documentation comments. A line like # @param x [Integer] … sitting inside a SQL heredoc or a multi-line string was scanned as a real comment and reported as orphaned. The scanner now identifies comments from the Ruby lexer (Ripper) rather than by line prefix, so only genuine full-line comments are considered (with a regex fallback for unparseable sources). Behaviour for real comments is unchanged, pinned by an expanded characterization test suite.
• [Fix] Documentation/OrphanedDocComment no longer reports false positives for three more DSL constructs that YARD does document: a wrapped def (memoize def value, module_function def …), a receiver DSL call (MyDSL.register :name do … end), and a call whose comment carries a @method/@attribute tag naming the created object (e.g. # @method dynamic_size above acts_as_counter do). Genuinely orphaned tagged comments are still flagged.
• [Fix] Tags/TagTypePosition no longer misfires in two cases: a comment detached from a definition by a blank line is no longer scanned (YARD does not attach it), and under EnforcedStyle: type_first a valid @option (whose grammar is always name [Type] :key) is no longer flagged with the nonsensical suggestion to put the type first.
• [Fix] Documentation/MarkdownSyntax no longer reports the exponent operator as unclosed bold. A ** run padded by whitespace on both sides (e.g. x ** y) cannot open or close CommonMark emphasis, so it is no longer counted toward the bold-marker balance. The check also now skips fenced code blocks (```...```), so a double-splat such as def call(**opts) inside an @example block is not mistaken for markdown. Genuine **bold**/**unclosed markers are still detected.
• [Fix] --update and --auto-gen-config now honor the -c CONFIG path. --update -c custom.yml updated (or errored on) ./.yard-lint.yml instead of the named file, and --auto-gen-config -c custom.yml generated the todo from the custom config but linked inherit_from into a separate ./.yard-lint.yml (leaving the custom config unconnected and shadowing it on later runs). Both now target the -c file.
• [Fix] Diff modes (--diff/--staged/--changed) now find changed files whose names contain non-ASCII characters. With git's default core.quotepath=true, such paths are emitted C-quoted (e.g. "caf0351.rb"), so the .rb suffix check failed and the file was silently skipped. git-quoted paths are now unquoted before filtering.
• [Fix] Documentation/OrphanedDocComment no longer treats a prose comment that merely begins with a magic-comment word (e.g. # encoding: UTF-8 is assumed for all inputs) as a real magic comment. It matched the prefix followed by anything, so such a line split the documentation block and the tagged part looked orphaned even though a definition followed. A magic comment is now required to have a single-token value.
• [Fix] --changed (uncommitted files) now includes untracked files. It used git diff --name-only HEAD, which lists only tracked changes, so a brand-new not-yet-staged .rb file was never linted despite being a working-directory change. Untracked, non-ignored files (git ls-files --others --exclude-standard) are now included.
• [Fix] An unnamed @example no longer corrupts Tags/ExampleSyntax / Tags/ExampleStyle output. YARD returns an empty string (not nil) for an unnamed example, so the example.name || "Example N" fallback never fired; the empty name line was then dropped by the parser, shifting fields - the syntax-error message ended up in the example-name slot and the actual error was lost. The fallback now triggers on an empty name.
• [Fix] Custom tags declared in a project's .yardopts (e.g. --tag custom_tag:"Custom") are no longer reported as Warnings/UnknownTag. The in-process parser called YARD.parse directly and never loaded .yardopts, so a project's own tags - which the real yard command honors - were flagged as unknown. .yardopts tag-defining options (--tag and its --type-tag/--name-tag/etc. variants) are now registered before parsing.
• [Fix] Tags/InformalNotation now suggests @note (not @deprecated) for a Warning: notation. A warning is a caveat, not a deprecation; mapping it to @deprecated was incorrect. The code default and both shipped templates are updated consistently.
• [Fix] --auto-gen-config no longer writes offenses that are already silenced by a per-validator Exclude pattern into the generated baseline. TodoGenerator#run_linting built validator results directly, bypassing Runner#filter_result_offenses, so excluded files were counted and added to .yard-lint-todo.yml. The same exclude filtering (and no-location-offense dropping) a normal run applies is now used.
• [Fix] Documentation coverage is no longer reported as 100% when the yard stats subprocess fails. StatsCalculator returned an empty string on failure, which became the default stats (coverage: 100.0), so a MinCoverage gate silently passed; a subprocess killed by a signal also raised a NoMethodError on nil.zero?. Failure now yields unknown coverage (nil), and the exit-code check fails safe when a minimum is required but coverage cannot be determined.
• [Fix] Offenses with a never severity no longer cause a non-zero exit code under FailOnSeverity: convention. The convention branch counted all offenses via offenses.any?, while #statistics (and the error/warning branches) correctly exclude never. A validator set to Severity: never - meant to report without ever failing the build - now behaves consistently.
• [Fix] --auto-gen-config now emits a usable exclude pattern for grouped root-level files. PathGrouper produced ./**/* for files at the project root (File.dirname is .), but ./**/* matches nothing under File.fnmatch with FNM_PATHNAME - so the generated .yard-lint-todo.yml failed to exclude exactly the files it grouped, and yard-lint kept reporting them right after generating the baseline. The root group now uses **/*.
• [Fix] Tags/RedundantParamDescription's ParamToVerb pattern now only fires when the word after "to" is actually a low-value verb (from the LowValueVerbs config). It previously flagged any <param> to <anything>, so meaningful noun phrases like @param path [String] path to file were reported as too generic.
• [Fix] Tags/NonAsciiType no longer flags non-ASCII characters inside string or quoted-symbol literal types (e.g. ["naïve", "plain"]). Those are literal values, not Ruby type names, so non-ASCII is legitimate - and the sibling Tags/TypeSyntax already exempts them. Real type names with non-ASCII characters are still flagged.
• [Fix] The Warnings/UnknownParameterName "did you mean" suggestion engine now reads parameters from the right method and parses modern signatures. It scanned from 15 lines before the reported location and returned the first def found (so it read an earlier method's parameters), missed receiver methods like def self.build(...), and mangled keyword defaults and defaults containing commas (def f(mode: :fast, list = [1, 2], name) parsed as ["mode fast", "list", "2]", "name"]). It now starts at the reported def line, matches receiver/operator method names, and splits parameters with bracket awareness. The dead yard list fallback (which always returned [], shelled out per offense, and created a .yardoc/ directory) was removed.
• [Fix] The "did you mean" Levenshtein fallback in Warnings/UnknownTag and Warnings/UnknownParameterName no longer offers absurd suggestions for short, very different names (e.g. @foo → @todo, @spec → @see). It accepted any candidate within half the longer length; it now requires the edit distance to be strictly less than half, so a name differing by half its characters is not "corrected".
• [Fix] AllValidators.DiffMode.DefaultBaseRef is now honored. --diff with no explicit REF went straight to main/master auto-detection, ignoring the configured default (and erroring with "Could not detect default branch" on repos without main/master - exactly when the option is needed). The configured DefaultBaseRef is now used before falling back to auto-detection; an explicit REF still wins.
• [Fix] Semantic/AbstractMethods now honors its AllowedImplementations config option, which was defined in the defaults (and asserted by a test) but never read - the validator used a hardcoded heuristic, so customizing the option did nothing. Body lines are now checked against the configured patterns (compiled as regexps); a line matching any of them does not count as a real implementation.
• [Fix] Tags/CollectionType now produces a valid long-syntax suggestion for nested short-style hashes. The non-greedy gsub(/Hash<(.+?)>/) could not handle nesting, so Hash<Symbol, Hash<String, Integer>> was suggested as Hash{Symbol => Hash<String, Integer}> (mismatched brackets). Conversion now splits on the top-level comma with balanced-bracket awareness and recurses, yielding Hash{Symbol => Hash{String => Integer}}.
• [Fix] An unknown --format value is now rejected up front instead of after the entire (potentially long) lint run completes. yard-lint --format xml lib/ previously analyzed everything and only then printed "Unknown format".
• [Fix] The config error for an unrecognizable validator name no longer points to a nonexistent yard-lint --list-validators flag (following that advice produced an invalid-option error). It now links the wiki Validators page.
• [Fix] Category-level configuration is now honored. A department key such as Documentation: with Enabled: false passed validation but was silently ignored, so the category's validators still ran. Config#validator_enabled? now consults a category-level Enabled setting (an explicit per-validator setting still takes precedence).
• [Fix] Tags/ApiTags no longer requires an @api tag on constants. The missing-tag check flagged any public non-root object, so a constant (e.g. MAX_RETRIES = 5) was reported as "missing @​api tag" - although the validator's documentation promises it checks classes, modules, and methods. The check is now restricted to those three object types.
• [Fix] Diff modes (--diff, --staged, --changed) now find changed files when yard-lint is run from a repository subdirectory. git diff --name-only reports paths relative to the repo root, but the filter expanded them against the current working directory - so from a subdirectory every path failed File.exist? and the diff modes silently linted nothing (exiting 0). Paths are now expanded against the repository root (git rev-parse --show-toplevel).
• [Fix] Diamond-shaped config inheritance no longer raises a false CircularDependencyError. The loader tracked every file ever loaded instead of the files on the inheritance path currently being resolved, so two configs both inheriting one shared base (e.g. inherit_from: [a.yml, b.yml] where both inherit common.yml) aborted although no cycle exists. The tracker now acts as a proper recursion stack; true cycles are still detected.
• [Fix] Tags/ExampleSyntax no longer reports bogus syntax errors for example code containing a # => sequence inside a string literal. The cleaner that strips YARD output markers used line.sub(/\s*#\s*=>.*$/, ''), truncating at the first # => anywhere on the line - so msg = "result # => not output" became an unterminated string and was flagged as a syntax error. Stripping is now comment-aware: a # inside a string or character literal is left untouched.
• [Fix] Tags/CollectionType no longer flags custom classes whose names merely contain Hash or Array (e.g. MyHash<String, Integer>, ByteArray<Integer>). The style-detection regexes used unanchored substring matches (/Hash<.*>/, /Array<.*>/), so a custom collection type was misdetected and reported with a nonsense suggestion like MyHash{String => Integer}. The prefixes are now anchored with a negative lookbehind so only the built-in Hash and Array types match.
• [Fix] Tags/Order no longer crashes the entire run when EnforcedOrder is explicitly set to null in the config. The validator read the config value directly with no default fallback, so EnforcedOrder: ~ replaced the seeded array with nil and nil.dup raised a NoMethodError that aborted the run. It now falls back to the default order.
• [Fix] Tags/OptionTags no longer demands @option tags for a parameter that merely has an options-like name but is documented as a non-Hash type. The check looked only at the parameter name, so a boolean keyword argument (def run(options: false) with @param options [Boolean]) or an array parameter (@param opts [Array<String>]) was wrongly required to document @option. A parameter documented with a concrete non-Hash @param type is now treated as not an options hash. Genuine options hashes (documented [Hash] or with no type) are still checked.
• [Fix] Tags/TagGroupSeparator no longer treats indented @-leading lines inside an @example body (e.g. an instance variable like @result = compute) as YARD tag groups. Real YARD tags begin at column 0 of the docstring, but the scanner stripped each line before checking for a leading @, so example/code content created phantom one-tag groups and spurious "missing a blank line between groups" offenses. The check now requires the @ at column 0 of the unstripped line, matching how Tags/Order scans tags.
• [Fix] Documentation/MarkdownSyntax no longer reports a spurious "unclosed backtick" for a backtick inside a fenced code block. It counted every backtick in the docstring - including the ``` fences and code content - so a fenced block containing a lone backtick made the total odd. Inline backticks are now counted only outside fenced code blocks.
• [Fix] The in-process registry now restores YARD's global logger level even when parsing raises. The level was raised to fatal-only during parsing and reset as the final statement with no ensure, so an exception during YARD.parse left the logger silenced for the rest of the run.
• [Fix] Documentation/UndocumentedOptions no longer demands @option tags for a named parameter that merely matches an options-like name (option/opts/options/kwargs) but is documented as a non-Hash type (e.g. @param option [Symbol]). It looked only at the parameter name. A param documented with a concrete non-Hash @param type is now treated as not an options hash; double-splat (**opts) collectors and genuine Hash params are still checked.
• [Fix] --auto-gen-config no longer destroys the comments and formatting in an existing .yard-lint.yml when adding the inherit_from line. It round-tripped the whole config through YAML.load_file(...).to_yaml, deleting every comment and reformatting the file. It now edits the file textually: prepending an inherit_from block when none exists (preserving the rest verbatim), or inserting the todo entry into an existing block list.
• [Fix] yard-lint --update no longer silently drops inherit_from / inherit_gem. The updater rebuilt the config from AllValidators plus validator keys only and never copied or wrote the inheritance directives, so updating a config that inherits .yard-lint-todo.yml deleted that line and resurrected the entire baseline (every silenced offense reappeared). The directives are now preserved and written at the top of the regenerated config.
• [Fix] The one-line YARD-warning parsers (Warnings/UnknownTag, Warnings/UnknownDirective, Warnings/InvalidTagFormat, Warnings/InvalidDirectiveFormat) now extract the line number and message correctly when the source file path contains line or in file. The line regex /line (\d*)/ matched the first line anywhere (so a path like .../command line tools/x.rb yielded line 0), and the greedy message regex /(.*) in file/ matched up to the last in file (leaking a path fragment into the message). The line regex now anchors on near line (\d+) and the message capture is non-greedy.
• [Fix] Documentation/UndocumentedMethodArguments no longer demands @param tags for block (&block) or splat (*args, **opts) parameters. The check compared the @param tag count against object.parameters.size, which counted blocks (documented with @yield, never @param) and splats - unlike every other arity computation in the gem, which excludes * and &. A method documenting its block with @yield (e.g. def each(limit, &block) with @param limit + @yield) was wrongly flagged as missing argument documentation. The count now excludes splat and block parameters, matching the gem-wide convention.
• [Fix] Documentation/EmptyCommentLine no longer attributes a file-header comment (separated from a definition by a blank line) to that definition. The upward scan skipped any number of blank lines before the comment block, so a header such as # frozen_string_literal: true + # was treated as a class's documentation and its bare # reported as an empty trailing line - although YARD only attaches a docstring that sits immediately above the definition. The scan now stops at a blank line above the definition.
• [Fix] Documentation/BlankLineBeforeDefinition no longer treats shebangs (#!...), tool sigils/directives (Sorbet # typed:, # rubocop:..., # standard:...), or a bare # comment as documentation. The upward scan stopped at the first non-magic comment and called it a doc block, so a blank line between such a non-doc comment and a definition produced a spurious "blank line between documentation and definition" offense for an undocumented class (and its suggested fix - removing the blank - would have turned the directive into the docstring). These lines are now skipped like magic comments.

... (truncated)

Changelog

Sourced from yard-lint's changelog.

1.7.0 (2026-06-15)

• [Feature] Tags/ExampleSyntax gained an opt-in SkipNonRuby option (default false). The validator compiles every @example body as Ruby, so an irb/pry session, its => output, or a shell $ transcript was reported as a syntax error. With SkipNonRuby: true, @example blocks that are interactive console transcripts are skipped. Off by default so a genuine syntax error in a normal example is not hidden.
• [Feature] Tags/InvalidTypes gained an opt-in StrictConstantNames option (default false). The type check was deliberately lenient - any syntactically valid constant name was accepted - so a misspelled class name like Strng was never flagged, defeating the validator's headline use case. With StrictConstantNames: true, a CamelCase type that is neither a loaded Ruby constant nor resolvable in the analyzed codebase's YARD registry is reported. It stays off by default (types defined only in un-analyzed dependencies would otherwise be flagged - add those to ExtraTypes); the strict template (--init --strict) enables it. Boolean is now always accepted as a pseudo-type.
• [Feature] Tags/InformalNotation gained an opt-in SkipIndentedCodeBlocks option (default false). The validator skipped fenced (```) code blocks but not 4-space/tab indented Markdown code blocks, so informal-looking text inside an indented code sample (e.g. Note:) was flagged. With SkipIndentedCodeBlocks: true, indented code lines are skipped too. Off by default because indented text is also used for list continuations and wrapped prose.
• [Feature] Added Warnings/SyntaxError (enabled by default, severity error). A Ruby file YARD cannot parse used to be silently skipped - it registered no objects, produced no offense, and a run could exit 0 over code that does not even parse. The parser error is now surfaced as an offense (with file and line), so the run exits non-zero. Disable with Warnings/SyntaxError: { Enabled: false }.
• [Fix] Documentation/UndocumentedMethodArguments now matches each parameter to a @param tag by name instead of only comparing counts, so a misnamed tag (e.g. @param wrong for def push(item)) is now caught - the count-only check accepted it. This is the new default; set CheckParameterNames: false to restore the lenient count-only comparison. A separate opt-in SkipFullyUndocumented (default false) skips methods with no documentation at all, leaving them to Documentation/UndocumentedObjects instead of reporting the same method twice.
• [Fix] yard-lint --diff PATH (e.g. --diff lib/) no longer fails with fatal: ambiguous argument 'lib/...HEAD'. Because --diff [REF] takes an optional argument, OptionParser consumed the path as the REF, leaving no path. The --diff argument is now treated as the path (with the base ref auto-detected) when it is not a resolvable git ref but is an existing path; an explicit ref (--diff main), ref-plus-path (--diff main lib/), and an unknown ref (which still errors) are unaffected.
• [Fix] Documentation/TextSubstitution no longer flags a forbidden string that appears inside an inline code span (`…`). It already skipped fenced ``` code blocks but matched against the raw line, so e.g. an em-dash inside `start — finish` was reported even though it is literal code, not prose to substitute. Matching now ignores inline code spans; a forbidden string elsewhere in prose on the same line is still flagged.
• [Fix] Documentation/OrphanedDocComment no longer treats #-leading lines inside heredocs or string literals as documentation comments. A line like # @param x [Integer] … sitting inside a SQL heredoc or a multi-line string was scanned as a real comment and reported as orphaned. The scanner now identifies comments from the Ruby lexer (Ripper) rather than by line prefix, so only genuine full-line comments are considered (with a regex fallback for unparseable sources). Behaviour for real comments is unchanged, pinned by an expanded characterization test suite.
• [Fix] Documentation/OrphanedDocComment no longer reports false positives for three more DSL constructs that YARD does document: a wrapped def (memoize def value, module_function def …), a receiver DSL call (MyDSL.register :name do … end), and a call whose comment carries a @method/@attribute tag naming the created object (e.g. # @method dynamic_size above acts_as_counter do). Genuinely orphaned tagged comments are still flagged.
• [Fix] Tags/TagTypePosition no longer misfires in two cases: a comment detached from a definition by a blank line is no longer scanned (YARD does not attach it), and under EnforcedStyle: type_first a valid @option (whose grammar is always name [Type] :key) is no longer flagged with the nonsensical suggestion to put the type first.
• [Fix] Documentation/MarkdownSyntax no longer reports the exponent operator as unclosed bold. A ** run padded by whitespace on both sides (e.g. x ** y) cannot open or close CommonMark emphasis, so it is no longer counted toward the bold-marker balance. The check also now skips fenced code blocks (```...```), so a double-splat such as def call(**opts) inside an @example block is not mistaken for markdown. Genuine **bold**/**unclosed markers are still detected.
• [Fix] --update and --auto-gen-config now honor the -c CONFIG path. --update -c custom.yml updated (or errored on) ./.yard-lint.yml instead of the named file, and --auto-gen-config -c custom.yml generated the todo from the custom config but linked inherit_from into a separate ./.yard-lint.yml (leaving the custom config unconnected and shadowing it on later runs). Both now target the -c file.
• [Fix] Diff modes (--diff/--staged/--changed) now find changed files whose names contain non-ASCII characters. With git's default core.quotepath=true, such paths are emitted C-quoted (e.g. "caf0351.rb"), so the .rb suffix check failed and the file was silently skipped. git-quoted paths are now unquoted before filtering.
• [Fix] Documentation/OrphanedDocComment no longer treats a prose comment that merely begins with a magic-comment word (e.g. # encoding: UTF-8 is assumed for all inputs) as a real magic comment. It matched the prefix followed by anything, so such a line split the documentation block and the tagged part looked orphaned even though a definition followed. A magic comment is now required to have a single-token value.
• [Fix] --changed (uncommitted files) now includes untracked files. It used git diff --name-only HEAD, which lists only tracked changes, so a brand-new not-yet-staged .rb file was never linted despite being a working-directory change. Untracked, non-ignored files (git ls-files --others --exclude-standard) are now included.
• [Fix] An unnamed @example no longer corrupts Tags/ExampleSyntax / Tags/ExampleStyle output. YARD returns an empty string (not nil) for an unnamed example, so the example.name || "Example N" fallback never fired; the empty name line was then dropped by the parser, shifting fields - the syntax-error message ended up in the example-name slot and the actual error was lost. The fallback now triggers on an empty name.
• [Fix] Custom tags declared in a project's .yardopts (e.g. --tag custom_tag:"Custom") are no longer reported as Warnings/UnknownTag. The in-process parser called YARD.parse directly and never loaded .yardopts, so a project's own tags - which the real yard command honors - were flagged as unknown. .yardopts tag-defining options (--tag and its --type-tag/--name-tag/etc. variants) are now registered before parsing.
• [Fix] Tags/InformalNotation now suggests @note (not @deprecated) for a Warning: notation. A warning is a caveat, not a deprecation; mapping it to @deprecated was incorrect. The code default and both shipped templates are updated consistently.
• [Fix] --auto-gen-config no longer writes offenses that are already silenced by a per-validator Exclude pattern into the generated baseline. TodoGenerator#run_linting built validator results directly, bypassing Runner#filter_result_offenses, so excluded files were counted and added to .yard-lint-todo.yml. The same exclude filtering (and no-location-offense dropping) a normal run applies is now used.
• [Fix] Documentation coverage is no longer reported as 100% when the yard stats subprocess fails. StatsCalculator returned an empty string on failure, which became the default stats (coverage: 100.0), so a MinCoverage gate silently passed; a subprocess killed by a signal also raised a NoMethodError on nil.zero?. Failure now yields unknown coverage (nil), and the exit-code check fails safe when a minimum is required but coverage cannot be determined.
• [Fix] Offenses with a never severity no longer cause a non-zero exit code under FailOnSeverity: convention. The convention branch counted all offenses via offenses.any?, while #statistics (and the error/warning branches) correctly exclude never. A validator set to Severity: never - meant to report without ever failing the build - now behaves consistently.
• [Fix] --auto-gen-config now emits a usable exclude pattern for grouped root-level files. PathGrouper produced ./**/* for files at the project root (File.dirname is .), but ./**/* matches nothing under File.fnmatch with FNM_PATHNAME - so the generated .yard-lint-todo.yml failed to exclude exactly the files it grouped, and yard-lint kept reporting them right after generating the baseline. The root group now uses **/*.
• [Fix] Tags/RedundantParamDescription's ParamToVerb pattern now only fires when the word after "to" is actually a low-value verb (from the LowValueVerbs config). It previously flagged any <param> to <anything>, so meaningful noun phrases like @param path [String] path to file were reported as too generic.
• [Fix] Tags/NonAsciiType no longer flags non-ASCII characters inside string or quoted-symbol literal types (e.g. ["naïve", "plain"]). Those are literal values, not Ruby type names, so non-ASCII is legitimate - and the sibling Tags/TypeSyntax already exempts them. Real type names with non-ASCII characters are still flagged.
• [Fix] The Warnings/UnknownParameterName "did you mean" suggestion engine now reads parameters from the right method and parses modern signatures. It scanned from 15 lines before the reported location and returned the first def found (so it read an earlier method's parameters), missed receiver methods like def self.build(...), and mangled keyword defaults and defaults containing commas (def f(mode: :fast, list = [1, 2], name) parsed as ["mode fast", "list", "2]", "name"]). It now starts at the reported def line, matches receiver/operator method names, and splits parameters with bracket awareness. The dead yard list fallback (which always returned [], shelled out per offense, and created a .yardoc/ directory) was removed.
• [Fix] The "did you mean" Levenshtein fallback in Warnings/UnknownTag and Warnings/UnknownParameterName no longer offers absurd suggestions for short, very different names (e.g. @foo → @todo, @spec → @see). It accepted any candidate within half the longer length; it now requires the edit distance to be strictly less than half, so a name differing by half its characters is not "corrected".
• [Fix] AllValidators.DiffMode.DefaultBaseRef is now honored. --diff with no explicit REF went straight to main/master auto-detection, ignoring the configured default (and erroring with "Could not detect default branch" on repos without main/master - exactly when the option is needed). The configured DefaultBaseRef is now used before falling back to auto-detection; an explicit REF still wins.
• [Fix] Semantic/AbstractMethods now honors its AllowedImplementations config option, which was defined in the defaults (and asserted by a test) but never read - the validator used a hardcoded heuristic, so customizing the option did nothing. Body lines are now checked against the configured patterns (compiled as regexps); a line matching any of them does not count as a real implementation.
• [Fix] Tags/CollectionType now produces a valid long-syntax suggestion for nested short-style hashes. The non-greedy gsub(/Hash<(.+?)>/) could not handle nesting, so Hash<Symbol, Hash<String, Integer>> was suggested as Hash{Symbol => Hash<String, Integer}> (mismatched brackets). Conversion now splits on the top-level comma with balanced-bracket awareness and recurses, yielding Hash{Symbol => Hash{String => Integer}}.
• [Fix] An unknown --format value is now rejected up front instead of after the entire (potentially long) lint run completes. yard-lint --format xml lib/ previously analyzed everything and only then printed "Unknown format".
• [Fix] The config error for an unrecognizable validator name no longer points to a nonexistent yard-lint --list-validators flag (following that advice produced an invalid-option error). It now links the wiki Validators page.
• [Fix] Category-level configuration is now honored. A department key such as Documentation: with Enabled: false passed validation but was silently ignored, so the category's validators still ran. Config#validator_enabled? now consults a category-level Enabled setting (an explicit per-validator setting still takes precedence).
• [Fix] Tags/ApiTags no longer requires an @api tag on constants. The missing-tag check flagged any public non-root object, so a constant (e.g. MAX_RETRIES = 5) was reported as "missing @​api tag" - although the validator's documentation promises it checks classes, modules, and methods. The check is now restricted to those three object types.
• [Fix] Diff modes (--diff, --staged, --changed) now find changed files when yard-lint is run from a repository subdirectory. git diff --name-only reports paths relative to the repo root, but the filter expanded them against the current working directory - so from a subdirectory every path failed File.exist? and the diff modes silently linted nothing (exiting 0). Paths are now expanded against the repository root (git rev-parse --show-toplevel).
• [Fix] Diamond-shaped config inheritance no longer raises a false CircularDependencyError. The loader tracked every file ever loaded instead of the files on the inheritance path currently being resolved, so two configs both inheriting one shared base (e.g. inherit_from: [a.yml, b.yml] where both inherit common.yml) aborted although no cycle exists. The tracker now acts as a proper recursion stack; true cycles are still detected.
• [Fix] Tags/ExampleSyntax no longer reports bogus syntax errors for example code containing a # => sequence inside a string literal. The cleaner that strips YARD output markers used line.sub(/\s*#\s*=>.*$/, ''), truncating at the first # => anywhere on the line - so msg = "result # => not output" became an unterminated string and was flagged as a syntax error. Stripping is now comment-aware: a # inside a string or character literal is left untouched.
• [Fix] Tags/CollectionType no longer flags custom classes whose names merely contain Hash or Array (e.g. MyHash<String, Integer>, ByteArray<Integer>). The style-detection regexes used unanchored substring matches (/Hash<.*>/, /Array<.*>/), so a custom collection type was misdetected and reported with a nonsense suggestion like MyHash{String => Integer}. The prefixes are now anchored with a negative lookbehind so only the built-in Hash and Array types match.
• [Fix] Tags/Order no longer crashes the entire run when EnforcedOrder is explicitly set to null in the config. The validator read the config value directly with no default fallback, so EnforcedOrder: ~ replaced the seeded array with nil and nil.dup raised a NoMethodError that aborted the run. It now falls back to the default order.
• [Fix] Tags/OptionTags no longer demands @option tags for a parameter that merely has an options-like name but is documented as a non-Hash type. The check looked only at the parameter name, so a boolean keyword argument (def run(options: false) with @param options [Boolean]) or an array parameter (@param opts [Array<String>]) was wrongly required to document @option. A parameter documented with a concrete non-Hash @param type is now treated as not an options hash. Genuine options hashes (documented [Hash] or with no type) are still checked.
• [Fix] Tags/TagGroupSeparator no longer treats indented @-leading lines inside an @example body (e.g. an instance variable like @result = compute) as YARD tag groups. Real YARD tags begin at column 0 of the docstring, but the scanner stripped each line before checking for a leading @, so example/code content created phantom one-tag groups and spurious "missing a blank line between groups" offenses. The check now requires the @ at column 0 of the unstripped line, matching how Tags/Order scans tags.
• [Fix] Documentation/MarkdownSyntax no longer reports a spurious "unclosed backtick" for a backtick inside a fenced code block. It counted every backtick in the docstring - including the ``` fences and code content - so a fenced block containing a lone backtick made the total odd. Inline backticks are now counted only outside fenced code blocks.
• [Fix] The in-process registry now restores YARD's global logger level even when parsing raises. The level was raised to fatal-only during parsing and reset as the final statement with no ensure, so an exception during YARD.parse left the logger silenced for the rest of the run.
• [Fix] Documentation/UndocumentedOptions no longer demands @option tags for a named parameter that merely matches an options-like name (option/opts/options/kwargs) but is documented as a non-Hash type (e.g. @param option [Symbol]). It looked only at the parameter name. A param documented with a concrete non-Hash @param type is now treated as not an options hash; double-splat (**opts) collectors and genuine Hash params are still checked.
• [Fix] --auto-gen-config no longer destroys the comments and formatting in an existing .yard-lint.yml when adding the inherit_from line. It round-tripped the whole config through YAML.load_file(...).to_yaml, deleting every comment and reformatting the file. It now edits the file textually: prepending an inherit_from block when none exists (preserving the rest verbatim), or inserting the todo entry into an existing block list.
• [Fix] yard-lint --update no longer silently drops inherit_from / inherit_gem. The updater rebuilt the config from AllValidators plus validator keys only and never copied or wrote the inheritance directives, so updating a config that inherits .yard-lint-todo.yml deleted that line and resurrected the entire baseline (every silenced offense reappeared). The directives are now preserved and written at the top of the regenerated config.
• [Fix] The one-line YARD-warning parsers (Warnings/UnknownTag, Warnings/UnknownDirective, Warnings/InvalidTagFormat, Warnings/InvalidDirectiveFormat) now extract the line number and message correctly when the source file path contains line or in file. The line regex /line (\d*)/ matched the first line anywhere (so a path like .../command line tools/x.rb yielded line 0), and the greedy message regex /(.*) in file/ matched up to the last in file (leaking a path fragment into the message). The line regex now anchors on near line (\d+) and the message capture is non-greedy.
• [Fix] Documentation/UndocumentedMethodArguments no longer demands @param tags for block (&block) or splat (*args, **opts) parameters. The check compared the @param tag count against object.parameters.size, which counted blocks (documented with @yield, never @param) and splats - unlike every other arity computation in the gem, which excludes * and &. A method documenting its block with @yield (e.g. def each(limit, &block) with @param limit + @yield) was wrongly flagged as missing argument documentation. The count now excludes splat and block parameters, matching the gem-wide convention.
• [Fix] Documentation/EmptyCommentLine no longer attributes a file-header comment (separated from a definition by a blank line) to that definition. The upward scan skipped any number of blank lines before the comment block, so a header such as # frozen_string_literal: true + # was treated as a class's documentation and its bare # reported as an empty trailing line - although YARD only attaches a docstring that sits immediately above the definition. The scan now stops at a blank line above the definition.
• [Fix] Documentation/BlankLineBeforeDefinition no longer treats shebangs (#!...), tool sigils/directives (Sorbet # typed:, # rubocop:..., # standard:...), or a bare # comment as documentation. The upward scan stopped at the first non-magic comment and called it a doc block, so a blank line between such a non-doc comment and a definition produced a spurious "blank line between documentation and definition" offense for an undocumented class (and its suggested fix - removing the blank - would have turned the directive into the docstring). These lines are now skipped like magic comments.

... (truncated)

Commits

• 622d7eb v1.7.0 (#259)
• 8758a1f Fix UndocumentedMethodArguments count-only check; name-based @​param matching ...
• ea76539 Treat --diff PATH as a path, not a bad git ref (BUG-022) (#258)
• 89fa085 Add opt-in SkipNonRuby to Tags/ExampleSyntax (BUG-046) (#255)
• 462a98d Update ruby setup to v1.312.0 (#256)
• c2abde0 Add opt-in StrictConstantNames to Tags/InvalidTypes (BUG-053) (#253)
• 75302d0 Add opt-in SkipIndentedCodeBlocks to Tags/InformalNotation (BUG-051) (#254)
• 96219e0 Add Warnings/SyntaxError: exit non-zero on files YARD cannot parse (BUG-082) ...
• 888ae3f chore: untrack local BUGS.md audit tracker (#251)
• a495d7c Fix TextSubstitution flagging forbidden strings inside inline code spans (#250)
• Additional commits viewable in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

---

Dependabot commands and options

You can trigger Dependabot actions by commenting on this PR:

• @dependabot rebase will rebase this PR
• @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
• @dependabot show <dependency name> ignore conditions will show all of the ignore conditions of the specified dependency
• @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)

[dependabot]

Superseded by #2658.