This adds a new ERB comment syntax linter to catch ERB comments that could trip up the Ruby parser in latest versions of Ruby.
The ERB documentation[1] says that Ruby comments are not valid in ERB, and that comments in ERB should be of the form <%# comment here %> and not <% # comment here %>. That is, no space between the opening <% and the # character.
This documentation is only a guideline usually, because in most cases Ruby-style comments work just fine. However, using the Ruby 3.1 parser, RuboCop's Lint/Syntax cop started failing on ERB files that included comments with semicolons in them.
Take an example ERB file:
<%# This is the correct comment syntax. %>
<%# Recommending the "proper" ERB comment syntax seems like the safest way to go; even with semicolons it will parse. %>
<% # This is technically incorrect comment syntax but it generally parses. %>
<% # Until someone puts a ; in. %>
This led to output from RuboCop's Lint/Syntax cop (RuboCop v1.36, TargetRubyVersion: 3.1) where it failed to parse the file, but its code snippets and offense locations were not very useful. (Admittedly it's less visible in this contrived example, you'll have to trust me!)
app/views/proof_of_concept.html.erb:7:2: E: Lint/Syntax: unexpected token kIN
(Using Ruby 3.1 parser; configure using TargetRubyVersion parameter, under AllCops)
in.
^^
1 file inspected, 1 offense detected
After lots of being confused, because the code looked like valid Ruby and the editor was syntax highlighting it if it were a valid comment, we realised that it was the semicolon in the comment in the ERB that was tripping the Ruby 3.1 parser up.
Doing some digging, it turns out that this could have all been avoided if our codebase had respected ERB's "Ruby comments are not valid" guideline[1]. I went hunting for a RuboCop rule for this, then remembered that ERBLint existed and is way better suited to linting ERB. There wasn't an existing rule for ERB comment syntax that I could find, hence this addition, because I feel like individual developers shouldn't have to know this quirk of ERB off the top of their heads!
<%# erb comment here %>
<%= # bad erb comment here %>
<%
# apparently this comment syntax is valid?
%>
<% # very; bad erb comment here %>
Example behaviour of this new linter:
❯ exe/erblint --enable-linters=comment_syntax test_comment_syntax.html.erb
.erb-lint.yml not found: using default config
Linting 1 files with 1 linters...
Bad ERB comment syntax. Should be <%#= without a space between.
Leaving a space between ERB tags and the Ruby comment character can cause parser errors.
In file: test_comment_syntax.html.erb:2
Bad ERB comment syntax. Should be <%# without a space between.
Leaving a space between ERB tags and the Ruby comment character can cause parser errors.
In file: test_comment_syntax.html.erb:6
2 error(s) were found in ERB files
Thanks for building ERBLint, and thanks in advance for the review here! ✨
This adds a new ERB comment syntax linter to catch ERB comments that could trip up the Ruby parser in latest versions of Ruby.
The ERB documentation[1] says that Ruby comments are not valid in ERB, and that comments in ERB should be of the form
<%# comment here %>
and not<% # comment here %>
. That is, no space between the opening<%
and the#
character.This documentation is only a guideline usually, because in most cases Ruby-style comments work just fine. However, using the Ruby 3.1 parser, RuboCop's
Lint/Syntax
cop started failing on ERB files that included comments with semicolons in them.Take an example ERB file:
Lint/Syntax
cop (RuboCop v1.36,TargetRubyVersion: 3.1
) where it failed to parse the file, but its code snippets and offense locations were not very useful. (Admittedly it's less visible in this contrived example, you'll have to trust me!)After lots of being confused, because the code looked like valid Ruby and the editor was syntax highlighting it if it were a valid comment, we realised that it was the semicolon in the comment in the ERB that was tripping the Ruby 3.1 parser up.
Doing some digging, it turns out that this could have all been avoided if our codebase had respected ERB's "Ruby comments are not valid" guideline[1]. I went hunting for a RuboCop rule for this, then remembered that ERBLint existed and is way better suited to linting ERB. There wasn't an existing rule for ERB comment syntax that I could find, hence this addition, because I feel like individual developers shouldn't have to know this quirk of ERB off the top of their heads!
[1] - https://github.com/ruby/erb/tree/a3492c4bd1061071814cca085544ce259a9d8d56#recognized-tags
Example ERB file:
Example behaviour of this new linter:
Thanks for building ERBLint, and thanks in advance for the review here! ✨