From e06138b2f6ad30afea2785c74af2839a26cbecba Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Tue, 5 May 2026 10:03:34 -0600 Subject: [PATCH 1/9] add minimal yardlint --- .github/workflows/lint.yml | 15 +++++ .yard-lint.yml | 109 +++++++++++++++++++++++++++++++++++++ Gemfile | 1 + Gemfile.lock | 5 ++ 4 files changed, 130 insertions(+) create mode 100644 .yard-lint.yml diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 483898def..0fb580015 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -91,3 +91,18 @@ jobs: bundle exec erb_lint --lint-all env: RAILS_VERSION: '~> 8' + yard-lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Setup Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: 4.0 + bundler-cache: true + - name: YARD Lint + run: bundle exec yard-lint lib/ + env: + RAILS_VERSION: '~> 8' diff --git a/.yard-lint.yml b/.yard-lint.yml new file mode 100644 index 000000000..cdc08c1aa --- /dev/null +++ b/.yard-lint.yml @@ -0,0 +1,109 @@ +# YARD-Lint Configuration +# See https://github.com/mensfeld/yard-lint for documentation +# +# Starting with minimal enforcement (Warnings/UnknownTag only). +# Additional validators can be enabled in subsequent PRs. + +AllValidators: + YardOptions: + - --plugin + - activesupport-concern + + Exclude: + - 'vendor/**/*' + - 'spec/**/*' + - 'test/**/*' + - 'performance/**/*' + + FailOnSeverity: error + +Documentation/UndocumentedObjects: + Enabled: false + +Documentation/UndocumentedMethodArguments: + Enabled: false + +Documentation/UndocumentedBooleanMethods: + Enabled: false + +Documentation/UndocumentedOptions: + Enabled: false + +Documentation/MissingReturn: + Enabled: false + +Documentation/MarkdownSyntax: + Enabled: false + +Documentation/EmptyCommentLine: + Enabled: false + +Documentation/BlankLineBeforeDefinition: + Enabled: false + +Tags/Order: + Enabled: false + +Tags/InvalidTypes: + Enabled: false + +Tags/TypeSyntax: + Enabled: false + +Tags/MeaninglessTag: + Enabled: false + +Tags/CollectionType: + Enabled: false + +Tags/TagTypePosition: + Enabled: false + +Tags/ApiTags: + Enabled: false + +Tags/OptionTags: + Enabled: false + +Tags/ExampleSyntax: + Enabled: false + +Tags/ExampleStyle: + Enabled: false + +Tags/RedundantParamDescription: + Enabled: false + +Tags/InformalNotation: + Enabled: false + +Tags/NonAsciiType: + Enabled: false + +Tags/TagGroupSeparator: + Enabled: false + +Tags/ForbiddenTags: + Enabled: false + +Warnings/UnknownTag: + Enabled: true + Severity: error + +Warnings/UnknownDirective: + Enabled: false + +Warnings/InvalidTagFormat: + Enabled: false + +Warnings/InvalidDirectiveFormat: + Enabled: false + +Warnings/DuplicatedParameterName: + Enabled: false + +Warnings/UnknownParameterName: + Enabled: false + +Semantic/AbstractMethods: + Enabled: false diff --git a/Gemfile b/Gemfile index d27f4c484..d1aa87cf1 100644 --- a/Gemfile +++ b/Gemfile @@ -46,5 +46,6 @@ group :development, :test do gem "turbo-rails" gem "warning" gem "yard-activesupport-concern", "< 1" + gem "yard-lint", "~> 1.5" gem "yard", "< 1" end diff --git a/Gemfile.lock b/Gemfile.lock index 3b796204f..b7824b9f0 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -409,6 +409,9 @@ GEM yard (0.9.43) yard-activesupport-concern (0.0.1) yard (>= 0.8) + yard-lint (1.5.1) + yard (~> 0.9) + zeitwerk (~> 2.6) zeitwerk (2.7.5) PLATFORMS @@ -460,6 +463,7 @@ DEPENDENCIES warning yard (< 1) yard-activesupport-concern (< 1) + yard-lint (~> 1.5) CHECKSUMS action_text-trix (2.1.18) sha256=3fdb83f8bff4145d098be283cdd47ac41caf5110bfa6df4695ed7127d7fb3642 @@ -621,6 +625,7 @@ CHECKSUMS xpath (3.2.0) sha256=6dfda79d91bb3b949b947ecc5919f042ef2f399b904013eb3ef6d20dd3a4082e yard (0.9.43) sha256=cf8733a8f0485df2a162927e9b5f182215a61f6d22de096b8f402c726a1c5821 yard-activesupport-concern (0.0.1) sha256=be790cb0efc23e2e87677063598ac8b743586154657bbd9655a7f03ce78390ef + yard-lint (1.5.1) sha256=41d194855b4f54aa957a0337720c6f48e252e4a31d7412c46cc94a12399c0149 zeitwerk (2.7.5) sha256=d8da92128c09ea6ec62c949011b00ed4a20242b255293dd66bf41545398f73dd RUBY VERSION From 775ec7ac246bc51f28aeaeb42f571313389f8fec Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Tue, 5 May 2026 10:06:07 -0600 Subject: [PATCH 2/9] turn on linters we already pass --- .yard-lint.yml | 33 +++++++++++++++------------------ 1 file changed, 15 insertions(+), 18 deletions(-) diff --git a/.yard-lint.yml b/.yard-lint.yml index cdc08c1aa..8b5e080fe 100644 --- a/.yard-lint.yml +++ b/.yard-lint.yml @@ -1,8 +1,5 @@ # YARD-Lint Configuration # See https://github.com/mensfeld/yard-lint for documentation -# -# Starting with minimal enforcement (Warnings/UnknownTag only). -# Additional validators can be enabled in subsequent PRs. AllValidators: YardOptions: @@ -24,7 +21,7 @@ Documentation/UndocumentedMethodArguments: Enabled: false Documentation/UndocumentedBooleanMethods: - Enabled: false + Enabled: true Documentation/UndocumentedOptions: Enabled: false @@ -33,7 +30,7 @@ Documentation/MissingReturn: Enabled: false Documentation/MarkdownSyntax: - Enabled: false + Enabled: true Documentation/EmptyCommentLine: Enabled: false @@ -51,10 +48,10 @@ Tags/TypeSyntax: Enabled: false Tags/MeaninglessTag: - Enabled: false + Enabled: true Tags/CollectionType: - Enabled: false + Enabled: true Tags/TagTypePosition: Enabled: false @@ -66,44 +63,44 @@ Tags/OptionTags: Enabled: false Tags/ExampleSyntax: - Enabled: false + Enabled: true Tags/ExampleStyle: - Enabled: false + Enabled: true Tags/RedundantParamDescription: - Enabled: false + Enabled: true Tags/InformalNotation: Enabled: false Tags/NonAsciiType: - Enabled: false + Enabled: true Tags/TagGroupSeparator: Enabled: false Tags/ForbiddenTags: - Enabled: false + Enabled: true Warnings/UnknownTag: Enabled: true Severity: error Warnings/UnknownDirective: - Enabled: false + Enabled: true Warnings/InvalidTagFormat: - Enabled: false + Enabled: true Warnings/InvalidDirectiveFormat: - Enabled: false + Enabled: true Warnings/DuplicatedParameterName: - Enabled: false + Enabled: true Warnings/UnknownParameterName: - Enabled: false + Enabled: true Semantic/AbstractMethods: - Enabled: false + Enabled: true From 6197687defb127547d17bd37dab0a27302f47aab Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Tue, 5 May 2026 10:09:54 -0600 Subject: [PATCH 3/9] Enable Documentation/EmptyCommentLine yard-lint rule Remove empty trailing comment line in Slot#method_missing docs and enable the validator. --- .yard-lint.yml | 2 +- lib/view_component/slot.rb | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/.yard-lint.yml b/.yard-lint.yml index 8b5e080fe..9d45df529 100644 --- a/.yard-lint.yml +++ b/.yard-lint.yml @@ -33,7 +33,7 @@ Documentation/MarkdownSyntax: Enabled: true Documentation/EmptyCommentLine: - Enabled: false + Enabled: true Documentation/BlankLineBeforeDefinition: Enabled: false diff --git a/lib/view_component/slot.rb b/lib/view_component/slot.rb index e70a421e2..ca90ca804 100644 --- a/lib/view_component/slot.rb +++ b/lib/view_component/slot.rb @@ -96,7 +96,6 @@ def to_s # end # end # end - # def method_missing(symbol, *args, **kwargs, &block) @__vc_component_instance.public_send(symbol, *args, **kwargs, &block) end From f45b2c9ed9853fcacb9bd4dd1aea2337b6065000 Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Tue, 5 May 2026 10:11:20 -0600 Subject: [PATCH 4/9] Enable Tags/InformalNotation yard-lint rule Convert 'Note:' to @note YARD tag in render_preview docs and enable the validator. --- .yard-lint.yml | 2 +- lib/view_component/test_helpers.rb | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.yard-lint.yml b/.yard-lint.yml index 9d45df529..96fa038fd 100644 --- a/.yard-lint.yml +++ b/.yard-lint.yml @@ -72,7 +72,7 @@ Tags/RedundantParamDescription: Enabled: true Tags/InformalNotation: - Enabled: false + Enabled: true Tags/NonAsciiType: Enabled: true diff --git a/lib/view_component/test_helpers.rb b/lib/view_component/test_helpers.rb index f6763e91e..9839af54f 100644 --- a/lib/view_component/test_helpers.rb +++ b/lib/view_component/test_helpers.rb @@ -71,12 +71,12 @@ def rendered_json # assert_text("Hello, World!") # ``` # - # Note: `#rendered_preview` expects a preview to be defined with the same class - # name as the calling test, but with `Test` replaced with `Preview`: + # @note `#rendered_preview` expects a preview to be defined with the same class + # name as the calling test, but with `Test` replaced with `Preview`: # - # MyComponentTest -> MyComponentPreview etc. + # MyComponentTest -> MyComponentPreview etc. # - # In RSpec, `Preview` is appended to `described_class`. + # In RSpec, `Preview` is appended to `described_class`. # # @param name [String] The name of the preview to be rendered. # @param from [ViewComponent::Preview] The class of the preview to be rendered. From eef2271c7455bcb2920f249afa687538167b254b Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Tue, 5 May 2026 10:12:27 -0600 Subject: [PATCH 5/9] Enable Tags/Order yard-lint rule Fix YARD tag ordering: @param before @return in Compiler, @note after @return in TestHelpers, and enable the validator. --- .yard-lint.yml | 2 +- lib/view_component/compiler.rb | 3 +-- lib/view_component/test_helpers.rb | 9 ++++----- 3 files changed, 6 insertions(+), 8 deletions(-) diff --git a/.yard-lint.yml b/.yard-lint.yml index 96fa038fd..7a18823e9 100644 --- a/.yard-lint.yml +++ b/.yard-lint.yml @@ -39,7 +39,7 @@ Documentation/BlankLineBeforeDefinition: Enabled: false Tags/Order: - Enabled: false + Enabled: true Tags/InvalidTypes: Enabled: false diff --git a/lib/view_component/compiler.rb b/lib/view_component/compiler.rb index 69b555046..28fee11b1 100644 --- a/lib/view_component/compiler.rb +++ b/lib/view_component/compiler.rb @@ -57,9 +57,8 @@ def compile(raise_errors: false, force: false) end end - # @return all matching compiled templates, in priority order based on the requested details from LookupContext - # # @param [ActionView::TemplateDetails::Requested] requested_details i.e. locales, formats, variants + # @return all matching compiled templates, in priority order based on the requested details from LookupContext def find_templates_for(requested_details) filtered_templates = @templates.select do |template| template.details.matches?(requested_details) diff --git a/lib/view_component/test_helpers.rb b/lib/view_component/test_helpers.rb index 9839af54f..e4a30061b 100644 --- a/lib/view_component/test_helpers.rb +++ b/lib/view_component/test_helpers.rb @@ -71,17 +71,16 @@ def rendered_json # assert_text("Hello, World!") # ``` # + # @param name [String] The name of the preview to be rendered. + # @param from [ViewComponent::Preview] The class of the preview to be rendered. + # @param params [Hash] Parameters to be passed to the preview. + # @return [Nokogiri::HTML5] # @note `#rendered_preview` expects a preview to be defined with the same class # name as the calling test, but with `Test` replaced with `Preview`: # # MyComponentTest -> MyComponentPreview etc. # # In RSpec, `Preview` is appended to `described_class`. - # - # @param name [String] The name of the preview to be rendered. - # @param from [ViewComponent::Preview] The class of the preview to be rendered. - # @param params [Hash] Parameters to be passed to the preview. - # @return [Nokogiri::HTML5] def render_preview(name, from: __vc_test_helpers_preview_class, params: {}) previews_controller = __vc_test_helpers_build_controller(Rails.application.config.view_component.previews.controller.constantize) From 3a8f2aa11627518049ae0c6cdfac33ac15f43da9 Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Tue, 5 May 2026 10:13:36 -0600 Subject: [PATCH 6/9] Enable Tags/TagTypePosition yard-lint rule Fix @param type position in Compiler#find_templates_for to use '@param name [Type]' instead of '@param [Type] name', and enable the validator. --- .yard-lint.yml | 2 +- lib/view_component/compiler.rb | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.yard-lint.yml b/.yard-lint.yml index 7a18823e9..0ae852c09 100644 --- a/.yard-lint.yml +++ b/.yard-lint.yml @@ -54,7 +54,7 @@ Tags/CollectionType: Enabled: true Tags/TagTypePosition: - Enabled: false + Enabled: true Tags/ApiTags: Enabled: false diff --git a/lib/view_component/compiler.rb b/lib/view_component/compiler.rb index 28fee11b1..9a4eecd47 100644 --- a/lib/view_component/compiler.rb +++ b/lib/view_component/compiler.rb @@ -57,7 +57,7 @@ def compile(raise_errors: false, force: false) end end - # @param [ActionView::TemplateDetails::Requested] requested_details i.e. locales, formats, variants + # @param requested_details [ActionView::TemplateDetails::Requested] i.e. locales, formats, variants # @return all matching compiled templates, in priority order based on the requested details from LookupContext def find_templates_for(requested_details) filtered_templates = @templates.select do |template| From 674b1354d6496dd6e954bbcae2ca07df81738ae3 Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Tue, 5 May 2026 10:15:12 -0600 Subject: [PATCH 7/9] Enable Tags/InvalidTypes yard-lint rule Fix invalid Symbol[] type annotations to Array in TestHelpers#with_variant and #with_format, and enable the validator. --- .yard-lint.yml | 2 +- lib/view_component/test_helpers.rb | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.yard-lint.yml b/.yard-lint.yml index 0ae852c09..3f3fed4c9 100644 --- a/.yard-lint.yml +++ b/.yard-lint.yml @@ -42,7 +42,7 @@ Tags/Order: Enabled: true Tags/InvalidTypes: - Enabled: false + Enabled: true Tags/TypeSyntax: Enabled: false diff --git a/lib/view_component/test_helpers.rb b/lib/view_component/test_helpers.rb index e4a30061b..dcf8b0619 100644 --- a/lib/view_component/test_helpers.rb +++ b/lib/view_component/test_helpers.rb @@ -124,7 +124,7 @@ def render_in_view_context(...) # end # ``` # - # @param variants [Symbol[]] The variants to be set for the provided block. + # @param variants [Array] The variants to be set for the provided block. def with_variant(*variants) old_variants = vc_test_controller.view_context.lookup_context.variants @@ -161,7 +161,7 @@ def with_controller_class(klass) # end # ``` # - # @param formats [Symbol[]] The format(s) to be set for the provided block. + # @param formats [Array] The format(s) to be set for the provided block. def with_format(*formats) old_formats = vc_test_controller.view_context.lookup_context.formats From 605ff2a56c3a68a179099c6db1f018219e278a30 Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Tue, 5 May 2026 10:15:53 -0600 Subject: [PATCH 8/9] Enable Tags/TypeSyntax yard-lint rule Already passes after Symbol[] -> Array fix in previous commit. --- .yard-lint.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.yard-lint.yml b/.yard-lint.yml index 3f3fed4c9..9578a58c1 100644 --- a/.yard-lint.yml +++ b/.yard-lint.yml @@ -45,7 +45,7 @@ Tags/InvalidTypes: Enabled: true Tags/TypeSyntax: - Enabled: false + Enabled: true Tags/MeaninglessTag: Enabled: true From a59a5ae4e2f0b08440019aa692ebcf137e39b26e Mon Sep 17 00:00:00 2001 From: Joel Hawksley Date: Tue, 5 May 2026 10:30:36 -0600 Subject: [PATCH 9/9] cleanup --- .github/workflows/lint.yml | 2 -- docs/CHANGELOG.md | 4 ++++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 0fb580015..8622f5c33 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -104,5 +104,3 @@ jobs: bundler-cache: true - name: YARD Lint run: bundle exec yard-lint lib/ - env: - RAILS_VERSION: '~> 8' diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 33b31ae91..a489804d7 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -10,6 +10,10 @@ nav_order: 6 ## main +* Add `yard-lint` to CI. + + *Joel Hawksley* + ## 4.8.0 * Add `compile.view_component` ActiveSupport::Notifications event for eager compilation at boot time.