Ruby: Add RuboCop support for Ruby in ERB templates

.github/labeler.yml

@@ -266,6 +266,7 @@ rubygem:
   - changed-files:
     - any-glob-to-any-file:
       - 'herb.gemspec'
+      - 'gems/**/*'
       - 'lib/**/*'
       - 'templates/lib/**/*'
 

.github/workflows/build-gems.yml

@@ -10,6 +10,7 @@ on:
     paths:
       - "src/**"
       - "lib/**"
+      - "gems/**"
       - "ext/**"
       - "Gemfile"
       - "Gemfile.lock"
@@ -22,6 +23,7 @@ on:
     paths:
       - "src/**"
       - "lib/**"
+      - "gems/**"
       - "ext/**"
       - "Gemfile"
       - "Gemfile.lock"
@@ -89,6 +91,9 @@ jobs:
         run: |
           if [ "${{ matrix.target }}" = "default" ]; then
             bundle exec rake build
+            mkdir -p pkg
+            cd gems/rubocop-herb
+            gem build rubocop-herb.gemspec --output ../../pkg/rubocop-herb.gem
           else
             bundle exec rake gem:${{ matrix.target }}
           fi

.github/workflows/build.yml

@@ -83,7 +83,12 @@ jobs:
         run: bundle exec rake compile
 
       - name: Run Ruby Tests
-        run: bundle exec rake test:all
+        run: bundle exec rake test:all test:rubocop_herb
+
+      - name: Test minimum supported RuboCop
+        run: |
+          bundle add rubocop --version 1.92.0
+          bundle exec rake test:rubocop_herb
 
       - name: Run C tests
         run: ./run_herb_tests

.rubocop.yml

@@ -158,6 +158,7 @@ Metrics/ClassLength:
     - lib/herb/visitor/stack.rb
     - templates/template.rb
     - test/**/*_test.rb
+    - gems/**/test/**/*_test.rb
 
 Metrics/ModuleLength:
   Exclude:

Gemfile

@@ -4,6 +4,8 @@ source "https://rubygems.org"
 
 gemspec
 
+gem "rubocop-herb", path: "gems/rubocop-herb"
+
 gem "prism", github: "ruby/prism", tag: "v1.9.0"
 
 gem "actionview", "~> 8.1", require: "action_view"

Gemfile.lock

@@ -21,6 +21,14 @@ PATH
   specs:
     herb (0.11.1)
 
+PATH
+  remote: gems/rubocop-herb
+  specs:
+    rubocop-herb (0.11.1)
+      herb (= 0.11.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.92.0, < 2)
+
 GEM
   remote: https://rubygems.org/
   specs:
@@ -368,6 +376,7 @@ DEPENDENCIES
   reline (~> 0.7)
   rolldown (~> 1.2)
   rubocop (~> 1.72)
+  rubocop-herb!
   rubocop-performance (~> 1.26.0)
   sorbet
   steep (~> 2.1)

README.md

@@ -53,6 +53,27 @@ Run the linter and the formatter:
 
 ```sh
 npx @herb-tools/linter
+```
+
+Run your project's configured RuboCop rules against Ruby in `.erb` and `.herb` templates with the `rubocop-herb` plugin:
+
+```sh
+bundle add rubocop-herb
+```
+
+```yaml
+# .rubocop.yml
+plugins:
+  - rubocop-herb
+```
+
+```sh
+bundle exec rubocop app/views
+```
+
+Format your HTML+ERB templates:
+
+```sh
 npx @herb-tools/formatter
 ```
 

Rakefile

@@ -28,6 +28,14 @@ Rake::TestTask.new("test:all") do |t|
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
+Rake::TestTask.new("test:rubocop_herb") do |t|
+  t.libs << "gems/rubocop-herb/test"
+  t.libs << "gems/rubocop-herb/lib"
+  t.test_files = FileList["gems/rubocop-herb/test/**/*_test.rb"]
+end
+
+task test: "test:rubocop_herb"
+
 task "make" do
   puts "Running make..."
   IO.popen("make") do |output|

gems/rubocop-herb/README.md

@@ -0,0 +1,44 @@
+# rubocop-herb
+
+`rubocop-herb` runs a project's configured RuboCop rules against Ruby embedded in `.erb` and `.herb` templates. Herb builds a position-preserving Ruby representation of the entire template so RuboCop can understand control flow and variable usage across ERB tags while reporting offenses at their original template locations.
+
+Requires RuboCop 1.92 or newer. Add the gem to your bundle:
+
+```sh
+bundle add rubocop-herb
+```
+
+Then enable the plugin in `.rubocop.yml`:
+
+```yaml
+plugins:
+  - rubocop-herb
+```
+
+Then use RuboCop normally:
+
+```sh
+bundle exec rubocop app/views
+bundle exec rubocop -a app/views
+bundle exec rubocop -A app/views
+```
+
+The plugin honors the project's RuboCop configuration, including custom cops, inherited configuration, target Ruby versions, file exclusions, and autocorrection. Cops that depend on physical Ruby file contents or layout, or that misread template control flow, are [excluded for template files by default](config/default.yml).
+
+Template-local `rubocop:disable`, `rubocop:enable`, and `rubocop:todo` directives work inside ERB comments:
+
+```erb
+<%# rubocop:disable Layout/SpaceAroundOperators %>
+<%= x=1 %>
+<%# rubocop:enable Layout/SpaceAroundOperators %>
+```
+
+Offenses are only reported for Ruby inside ERB tags, and autocorrections that would touch markup are discarded, so `rubocop -a` and `rubocop -A` never rewrite HTML or ERB delimiters.
+
+Every `.erb` and `.herb` file is inspected, including non-HTML templates. To skip some of them, exclude them in `.rubocop.yml`:
+
+```yaml
+AllCops:
+  Exclude:
+    - "**/*.yml.erb"
+```

gems/rubocop-herb/config/default.yml

@@ -0,0 +1,146 @@
+inherit_mode:
+  merge:
+    - Exclude
+    - Include
+
+AllCops:
+  Include: &template_files
+    - '**/*.erb'
+    - '**/*.herb'
+
+# These cops depend on physical Ruby file contents or layout that is obscured by the
+# position-preserving template representation, or misread markup between ERB tags as
+# empty or missing Ruby, such as the markup inside a `do` block. Redundancy cops
+# can also mistake implicit template output for unused expressions or unreachable code.
+Layout/ArgumentAlignment:
+  Exclude: *template_files
+Layout/ArrayAlignment:
+  Exclude: *template_files
+Layout/BlockAlignment:
+  Exclude: *template_files
+Layout/CaseIndentation:
+  Exclude: *template_files
+Layout/ClosingParenthesisIndentation:
+  Exclude: *template_files
+Layout/CommentIndentation:
+  Exclude: *template_files
+Layout/ElseAlignment:
+  Exclude: *template_files
+Layout/EmptyLineAfterGuardClause:
+  Exclude: *template_files
+Layout/EndAlignment:
+  Exclude: *template_files
+Layout/FirstArgumentIndentation:
+  Exclude: *template_files
+Layout/FirstArrayElementIndentation:
+  Exclude: *template_files
+Layout/FirstArrayElementLineBreak:
+  Exclude: *template_files
+Layout/FirstHashElementIndentation:
+  Exclude: *template_files
+Layout/FirstHashElementLineBreak:
+  Exclude: *template_files
+Layout/FirstMethodArgumentLineBreak:
+  Exclude: *template_files
+Layout/FirstParameterIndentation:
+  Exclude: *template_files
+Layout/HashAlignment:
+  Exclude: *template_files
+Layout/IndentationConsistency:
+  Exclude: *template_files
+Layout/IndentationWidth:
+  Exclude: *template_files
+Layout/InitialIndentation:
+  Exclude: *template_files
+Layout/LeadingEmptyLines:
+  Exclude: *template_files
+Layout/LineEndStringConcatenationIndentation:
+  Exclude: *template_files
+Layout/LineLength:
+  Exclude: *template_files
+Layout/MultilineArrayBraceLayout:
+  Exclude: *template_files
+Layout/MultilineAssignmentLayout:
+  Exclude: *template_files
+Layout/MultilineHashBraceLayout:
+  Exclude: *template_files
+Layout/MultilineMethodCallBraceLayout:
+  Exclude: *template_files
+Layout/MultilineMethodCallIndentation:
+  Exclude: *template_files
+Layout/MultilineMethodDefinitionBraceLayout:
+  Exclude: *template_files
+Layout/MultilineOperationIndentation:
+  Exclude: *template_files
+Layout/ParameterAlignment:
+  Exclude: *template_files
+Layout/SpaceBeforeSemicolon:
+  Exclude: *template_files
+Layout/TrailingEmptyLines:
+  Exclude: *template_files
+Layout/TrailingWhitespace:
+  Exclude: *template_files
+Lint/DuplicateBranch:
+  Exclude: *template_files
+Lint/EmptyBlock:
+  Exclude: *template_files
+Lint/EmptyConditionalBody:
+  Exclude: *template_files
+Lint/EmptyEnsure:
+  Exclude: *template_files
+Lint/EmptyFile:
+  Exclude: *template_files
+Lint/EmptyInPattern:
+  Exclude: *template_files
+Lint/EmptyWhen:
+  Exclude: *template_files
+Lint/SuppressedException:
+  Exclude: *template_files
+Lint/Void:
+  Exclude: *template_files
+Metrics/BlockLength:
+  Exclude: *template_files
+Naming/FileName:
+  Exclude: *template_files
+Rails/Presence:
+  Exclude: *template_files
+Style/BlockDelimiters:
+  Exclude: *template_files
+Style/CombinableLoops:
+  Exclude: *template_files
+Style/EmptyElse:
+  Exclude: *template_files
+Style/FrozenStringLiteralComment:
+  Exclude: *template_files
+Style/IdenticalConditionalBranches:
+  Exclude: *template_files
+Style/IfUnlessModifier:
+  Exclude: *template_files
+Style/IfWithSemicolon:
+  Exclude: *template_files
+Style/MultilineIfModifier:
+  Exclude: *template_files
+Style/MultilineTernaryOperator:
+  Exclude: *template_files
+Style/NestedTernaryOperator:
+  Exclude: *template_files
+Style/Next:
+  Exclude: *template_files
+Style/RedundantAssignment:
+  Exclude: *template_files
+Style/RedundantBegin:
+  Exclude: *template_files
+Style/RedundantCondition:
+  Exclude: *template_files
+Style/RedundantReturn:
+  Exclude: *template_files
+Style/SafeNavigation:
+  Exclude: *template_files
+Style/Semicolon:
+  Exclude: *template_files
+Style/SingleLineDoEndBlock:
+  Exclude: *template_files
+Style/SoleNestedConditional:
+  Exclude: *template_files
+Style/WhileUntilModifier:
+  Exclude: *template_files

gems/rubocop-herb/lib/rubocop/herb.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "herb"
+require "rubocop"
+
+require_relative "herb/directive_source"
+require_relative "herb/template_source"
+require_relative "herb/offense_guard"
+require_relative "herb/plugin"
+
+RuboCop::Cop::Base.prepend(RuboCop::Herb::OffenseGuard)

gems/rubocop-herb/lib/rubocop/herb/directive_source.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "delegate"
+require "prism"
+
+module RuboCop
+  module Herb
+    # Keep directives separate from parsed Ruby so a comment cannot hide a later tag.
+    class DirectiveSource < SimpleDelegator
+      RUBY_OPENERS = ["<%", "<%=", "<%==", "<%-", "<%#"].freeze
+
+      attr_reader :raw_source, :comments
+
+      def initialize(source, original)
+        super(source)
+        @raw_source = original.raw_source
+        @comments = source.comments.reject { |comment| comment.text.include?("rubocop:") }
+        @comments.concat(directive_comments(original))
+        @comments.sort_by! { |comment| comment.loc.expression.begin_pos }
+      end
+
+      private
+
+      def directive_comments(original)
+        opener = nil
+
+        ::Herb.lex(raw_source).value.flat_map do |token|
+          case token.type
+          when "TOKEN_ERB_START"
+            opener = token.value
+            []
+          when "TOKEN_ERB_CONTENT"
+            next [] unless token.value.include?("rubocop:")
+
+            comments_for(token, opener, original.buffer)
+          else
+            []
+          end
+        end
+      end
+
+      def comments_for(token, opener, buffer)
+        return [] unless RUBY_OPENERS.include?(opener)
+
+        comment_tag = opener == "<%#"
+        content = comment_tag ? "##{token.value}" : token.value
+        offset = token.range.from - (comment_tag ? 1 : 0)
+
+        Prism.parse_comments(content).filter_map do |comment|
+          next unless comment.location.slice.include?("rubocop:")
+
+          comment_from_location(buffer, offset, comment.location)
+        end
+      end
+
+      def comment_from_location(buffer, offset, location)
+        first = raw_source.byteslice(0, offset + location.start_offset).length
+        last = raw_source.byteslice(0, offset + location.end_offset).length
+        ::Parser::Source::Comment.new(::Parser::Source::Range.new(buffer, first, last))
+      end
+    end
+  end
+end