erb-lint is a tool to help lint your ERB or HTML files using the included linters or by writing your own.

• Ruby 2.2.0+ (Runtime)
• Ruby 2.3.0+ (Development)

• This is due to the use of the tilde-heredoc <<~ syntax in some tests.

gem install erb_lint

...or add the following to your Gemfile and run bundle install:

gem 'erb_lint'

Create a .erb-lint.yml file in your project, with the following structure:

---
linters:
  ErbSafety:
    enabled: true
    better_html_config: .better-html.yml
  Rubocop:
    enabled: true
    rubocop_config:
      inherit_from:
        - .rubocop.yml

See below for linter-specific configuration options.

This gem provides a command-line interface which can be run like so:

1. Run erblint [options] if the gem is installed standalone.
2. Run bundle exec erblint [options] if the gem is installed as a Gemfile dependency for your app.

For example, erblint --lint-all --enable-all-linters will run all available linters on all ERB files in the current directory or its descendants (**/*.html{+*,}.erb).

erb-lint comes with linters on-board:

• DeprecatedClasses: warn about deprecated css classes.
• FinalNewline: warn about missing newline at the end of a ERB template.
• ErbSafety: detects unsafe interpolation of ruby data into various javascript contexts and enforce usage of safe helpers like .to_json. See better-html's readme for more information.
• Rubocop: runs RuboCop rules on ruby statements found in ERB templates.

DeprecatedClasses will find all classes used on HTML elements and report any classes that violate the rule set that you provide.

A rule_set is specified as a list, each with a set of deprecated classes and a corresponding suggestion to use as an alternative.

Example configuration:

---
linters:
  DeprecatedClasses:
    enabled: true
    exclude:
      - 'app/views/shared/deprecated/**'
    addendum: "See UX wiki for help."
    rule_set:
      - deprecated: ['badge[-_\w]*']
        suggestion: "Use the ui_badge() component instead."

You can specify an addendum to be added to the end of each violation. The error message format is: "Deprecated class ... #{suggestion}" or "Deprecated class ... #{suggestion} #{addendum}" if an addendum is present.

Files must have a final newline. This results in better diffs when adding lines to the file, since SCM systems such as git won't think that you touched the last line.

You can customize whether or not a final newline exists with the present option.

Example configuration:

---
linters:
  FinalNewline:
    enabled: true

Runs the checks provided by better-html's erb safety test helper.

When using ERB interpolations in javascript contexts, this linter enforces the usage of safe helpers such as .to_json. Any ERB statement that does not call a safe helper is deemed unsafe and a violation is shown.

For example:

Not allowed ❌
<a onclick="alert(<%= some_data %>)">

Allowed ✅
<a onclick="alert(<%= some_data.to_json %>)">

Not allowed ❌
<script>var myData = <%= some_data %>;</script>

Allowed ✅
<script>var myData = <%= some_data.to_json %>;</script>

Example configuration:

---
linters:
  ErbSafety:
    enabled: true
    better_html_config: .better-html.yml

Runs RuboCop on all ruby statements found in ERB templates. The RuboCop configuration that erb-lint uses can inherit from the configuration that the rest of your application uses. erb-lint can be configured independently however, as it will often be necessary to disable specific RuboCop rules that do not apply to ERB files.

Example configuration:

---
linters:
  Rubocop:
    enabled: true
    rubocop_config:
      inherit_from:
        - .rubocop.yml
      Layout/InitialIndentation:
        Enabled: false
      Layout/TrailingBlankLines:
        Enabled: false
      Layout/TrailingWhitespace:
        Enabled: false
      Naming/FileName:
        Enabled: false
      Style/FrozenStringLiteralComment:
        Enabled: false
      Metrics/LineLength:
        Enabled: false
      Lint/UselessAssignment:
        Enabled: false
      Rails/OutputSafety:
        Enabled: false

The cops disabled in the example configuration above provide a good starting point.

Trimming at the right of an ERB tag can be done with either =%> or -%>, this linter enforces one of these two styles.

Example configuration:

---
linters:
  RightTrim:
    enabled: true
    enforced_style: '-'

Enforce a single space after <% and before %> in the ERB source. This linter ignores opening ERB tags (<%) that are followed by a newline, and closing ERB tags (%>) that are preceded by a newline.

Bad ❌
<%foo%>
<%=foo-%>

Good ✅
<% foo %>

<%
  foo
%>

Example configuration:

---
linters:
  SpaceAroundErbTag:
    enabled: true

This linter prevents the usage of Rails' javascript_tag helper in ERB templates.

The html parser used in this gem knows not to look for html tags within certain other tags like script, style, and others. The html parser does this to avoid confusing javascript expressions like if (1<a || b>1) for a malformed html tag. Using the javascript_tag in a ERB template prevents the parser from recognizing the change of parsing context and may fail or produce erroneous output as a result.

Bad ❌
<%= javascript_tag(content, defer: true) %>
Good ✅
<script defer="true"><%== content %></script>

Bad ❌
<%= javascript_tag do %>
  alert(1)
<% end %>
Good ✅
<script>
  alert(1)
</script>

The autocorrection rule adds //<![CDATA[ and //]]> markers to the existing script, as this is the default behavior for javascript_tag. This can be disabled by changing the correction_style linter option from cdata to plain.

Example configuration:

---
linters:
  NoJavascriptTagHelper:
    enabled: true
    correction_style: 'plain'

This linter prevent the addition of <script> tags that have type attributes that are not in a white-list of allowed values.

It is common practice for web developers to use <script> tags with non-executable type attributes, such as application/json or text/html to pass arbitrary data into an html page. Despite not being executable, these tags are subject to the same parsing quirks as executable script tags, and it is therefore more difficult to prevent security issues from creeping in. Consider for instance an application where it is possible to inject the string </script><script> unescaped into a text/html tag, the application would be vulnerable to XSS.

This pattern can easily be replaced by <div> tags with data attributes that can just as easily be read from javascript, and have the added benefit of being safer. When content_tag(:div) or tag.div() is used to pass arbitrary user data into the html document, it becomes much harder to inadvertently introduce a security issue.

It may also be desirable to avoid typos in type attributes.

Bad ❌
<script type="text/javacsrïpt"></script>
Good ✅
<script type="text/javascript"></script>

By default, this linter allows the type attribute to be omitted, as the behavior in browsers is to consider <script> to be the same as <script type="text/javascript">. When the linter is configured with allow_blank: false, instances of <script> tags without a type will be auto-corrected to <script type="text/javascript">.

It may also be desirable to disallow <script> tags from appearing anywhere in your application. For instance, Rails applications can benefit from serving static javascript code from the asset pipeline, as well as other security benefits. The disallow_inline_scripts: true config option may be used for that purpose.

Example configuration:

---
linters:
  AllowedScriptType:
    enabled: true
    allowed_types:
      - 'application/json'
      - 'text/javascript'
      - 'text/html'
    allow_blank: false
    disallow_inline_scripts: false

erb-lint allows you to create custom linters specific to your project. It will load linters from the .erb-linters directory in the root of your repository. See the linters directory for examples of how to write linters.

# .erb-linters/custom_linter.rb

module ERBLint
  module Linters
    class CustomLinter < Linter
      include LinterRegistry

      class ConfigSchema < LinterConfig
        property :custom_message, accepts: String
      end
      self.config_schema = ConfigSchema

      def offenses(processed_source)
        errors = []
        unless processed_source.file_content.include?('this file is fine')
          errors << Offense.new(
            self,
            processed_source.to_source_range(0 ... processed_source.file_content.size),
            "This file isn't fine. #{@config.custom_message}"
          )
        end
        errors
      end
    end
  end
end

By default, this linter would be disabled. You can enable it by adding an entry to .erb-lint.yml:

---
linters:
  CustomLinter:
    enabled: true
    custom_message: We suggest you change this file.

Test your linter by running erblint's command-line interface:

bundle exec erblint --enable-linters custom_linter --lint-all

Running this on a random project might yield this output:

Linting 15 files with 1 linters...

This file isn't fine. We suggest you change this file.
In file: app/views/layouts/application.html.erb:1

Errors were found in ERB files

To write a linter that can autocorrect offenses it detects, simply add an autocorrect method that returns a callable. The callable is called with an instance of RuboCop::Cop::Corrector as argument, and therefore erb-lint correctors work exactly as RuboCop correctors do.

def autocorrect(_processed_source, offense)
  lambda do |corrector|
    corrector.insert_after(offense.source_range, "this file is fine")
  end
end

This project is released under the MIT license.