@herb-tools/linter 0.8.9 → 0.9.0

package/docs/rules/erb-no-then-in-control-flow.md

@@ -0,0 +1,86 @@
+**Rule:** `erb-no-then-in-control-flow`
+
+## Description
+
+Disallow the use of the Ruby `then` keyword in control flow expressions inside ERB templates. This applies to:
+
+- `if … then`
+- `elsif … then`
+- `unless … then`
+- `case … when … then`
+- `case … in … then`
+
+## Rationale
+
+While Ruby allows the `then` keyword, its use inside ERB templates significantly reduces readability and adds confusion/ambiguity.
+
+In templates, clarity matters more than terseness. The multiline form:
+
+- Is easier to read and review
+- Works better with indentation and formatting rules
+- Avoids subtle parsing confusion in mixed HTML/Ruby contexts
+- Matches idiomatic Rails view style
+
+This rule enforces a consistent, block-oriented style for control flow in ERB.
+
+## Examples
+
+### Good
+
+```erb
+<% if condition %>
+  yes
+<% end %>
+```
+
+```erb
+<% unless logged_in? %>
+  please log in
+<% end %>
+```
+
+```erb
+<% case status %>
+<% when :ok %>
+  success
+<% when :error %>
+  failure
+<% else %>
+  unknown
+<% end %>
+```
+
+```erb
+<% case value %>
+<% in Integer %>
+  number
+<% in String %>
+  string
+<% end %>
+```
+
+### Bad
+
+```erb
+<% if condition then %>
+  yes
+<% end %>
+```
+
+```erb
+<% case status %>
+<% when :ok then %>
+  success
+<% end %>
+```
+
+```erb
+<% case value %>
+<% in Integer then "number" %>
+<% in String then "text" %>
+<% end %>
+```
+
+## References
+
+- [GitHub Issue #1077](https://github.com/marcoroth/herb/issues/1077)

package/docs/rules/erb-no-trailing-whitespace.md

@@ -0,0 +1,69 @@
+# Linter Rule: Disallow trailing whitespace at end of lines
+
+**Rule:** `erb-no-trailing-whitespace`
+
+## Description
+
+Disallow trailing whitespace (spaces, tabs, carriage returns, and other whitespace characters) at the end of lines in ERB templates.
+
+## Skipped Content
+
+This rule does **not** flag trailing whitespace inside:
+
+* `<pre>` - Preformatted text where whitespace is significant
+* `<textarea>` - User input where whitespace may be intentional
+* `<script>` - Treated as foreign content
+* `<style>` - Treated as foreign content
+* ERB tags (`<% %>`, `<%= %>`, `<%# %>`) - Ruby code where trailing whitespace could be significant (heredocs, string literals)
+
+## Rationale
+
+Trailing whitespace is invisible and serves no purpose, but it can cause several issues:
+
+* Creates unnecessary noise in diffs and pull requests
+* Can trigger merge conflicts when different editors handle trailing whitespace differently
+* Increases file size with characters that have no visual or functional effect
+* Many editor configurations and linters in other languages flag trailing whitespace, so keeping templates clean maintains consistency across the project
+
+## Examples
+
+### ✅ Good
+
+```erb
+<div>
+  <p>Hello</p>
+</div>
+```
+
+```erb
+<%= content %>
+```
+
+```erb
+<div>
+  <h1>Title</h1>
+</div>
+```
+
+### 🚫 Bad
+
+```erb
+<div>···
+  <p>Hello</p>
+</div>
+```
+
+```erb
+<%= content %>·
+```
+
+```erb
+Hello→→
+World···
+```
+
+> `·` represents a trailing space, `→` represents a trailing tab.
+
+## References
+
+- [Inspiration: ERB Lint `TrailingWhitespace` rule](https://github.com/Shopify/erb_lint/blob/main/README.md)

package/docs/rules/erb-no-unsafe-js-attribute.md

@@ -0,0 +1,41 @@
+# Linter Rule: Disallow unsafe ERB output in JavaScript attributes
+
+**Rule:** `erb-no-unsafe-js-attribute`
+
+## Description
+
+ERB interpolation in JavaScript event handler attributes (`onclick`, `onmouseover`, etc.) must be wrapped in a safe helper such as `.to_json`, `j()`, or `escape_javascript()`. Without proper encoding, user-controlled values can break out of string literals and execute arbitrary JavaScript.
+
+## Rationale
+
+HTML attributes that start with `on` (like `onclick`, `onmouseover`, `onfocus`) are evaluated as JavaScript by the browser. When ERB output is interpolated into these attributes without proper encoding, it creates a JavaScript injection vector. The `.to_json` method properly serializes Ruby values into safe JavaScript literals, while `j()` and `escape_javascript()` escape values for safe embedding in JavaScript string contexts.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<a onclick="method(<%= unsafe.to_json %>)"></a>
+```
+
+```erb
+<a onclick="method('<%= j(unsafe) %>')"></a>
+```
+
+```erb
+<a onclick="method(<%= escape_javascript(unsafe) %>)"></a>
+```
+
+### 🚫 Bad
+
+```erb
+<a onclick="method(<%= unsafe %>)"></a>
+```
+
+```erb
+<div onmouseover="highlight('<%= element_id %>')"></div>
+```
+
+## References
+
+- [Shopify/better-html — TagInterpolation](https://github.com/Shopify/better-html/blob/main/lib/better_html/test_helper/safe_erb/tag_interpolation.rb)

package/docs/rules/erb-no-unsafe-raw.md

@@ -0,0 +1,47 @@
+# Linter Rule: Disallow `raw()` and `.html_safe` in ERB output
+
+**Rule:** `erb-no-unsafe-raw`
+
+## Description
+
+Disallow the use of `raw()` and `.html_safe` in ERB output tags. These methods bypass Rails' automatic HTML escaping, which is the primary defense against cross-site scripting (XSS) vulnerabilities.
+
+## Rationale
+
+Rails automatically escapes ERB output to prevent XSS. Using `raw()` or `.html_safe` disables this protection, allowing arbitrary HTML and JavaScript injection. Even when combined with other safe methods like `.to_json`, using `raw()` or `.html_safe` is still unsafe because the escaping bypass applies to the final output.
+
+For example, `<%= raw unsafe.to_json %>` is flagged because `raw()` disables escaping on the entire expression, even though `.to_json` serializes the value safely. The `raw()` wrapper means any future changes to the expression could silently introduce a vulnerability.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<div class="<%= user_input %>"></div>
+```
+
+```erb
+<p><%= user_input %></p>
+```
+
+### 🚫 Bad
+
+```erb
+<div class="<%= raw(user_input) %>"></div>
+```
+
+```erb
+<div class="<%= user_input.html_safe %>"></div>
+```
+
+```erb
+<p><%= raw(user_input) %></p>
+```
+
+```erb
+<p><%= user_input.html_safe %></p>
+```
+
+## References
+
+- [Shopify/better-html — TagInterpolation](https://github.com/Shopify/better-html/blob/main/lib/better_html/test_helper/safe_erb/tag_interpolation.rb)

package/docs/rules/erb-no-unsafe-script-interpolation.md

@@ -0,0 +1,73 @@
+# Linter Rule: Disallow unsafe ERB output inside `<script>` tags
+
+**Rule:** `erb-no-unsafe-script-interpolation`
+
+## Description
+
+ERB interpolation in `<script>` tags must call `.to_json` to safely serialize Ruby data into JavaScript. Without `.to_json`, user-controlled values can break out of string literals and execute arbitrary JavaScript.
+
+## Rationale
+
+The main goal of this rule is to assert that Ruby data translates into JavaScript data, but never becomes JavaScript code. ERB output inside `<script>` tags is interpolated directly into the JavaScript context. Without proper serialization via `.to_json`, an attacker can inject arbitrary JavaScript by manipulating the interpolated value.
+
+For example, consider:
+
+```erb
+<script>
+  var name = "<%= user.name %>";
+</script>
+```
+
+If `user.name` contains `"; alert(1); "`, the resulting JavaScript would execute arbitrary code. Using `.to_json` properly escapes the value and wraps it in quotes:
+
+```erb
+<script>
+  var name = <%= user.name.to_json %>;
+</script>
+```
+
+## Examples
+
+### ✅ Good
+
+```erb
+<script>
+  var name = <%= user.name.to_json %>;
+</script>
+```
+
+```erb
+<script>
+  var data = <%== config.to_json %>;
+</script>
+```
+
+```erb
+<script>
+  <%= raw unsafe.to_json %>
+</script>
+```
+
+### 🚫 Bad
+
+```erb
+<script>
+  var name = "<%= user.name %>";
+</script>
+```
+
+```erb
+<script>
+  if (a < 1) { <%= unsafe %> }
+</script>
+```
+
+```erb
+<script>
+  <%= @feature.html_safe %>
+</script>
+```
+
+## References
+
+- [Shopify/better-html — ScriptInterpolation](https://github.com/Shopify/better-html/blob/main/lib/better_html/test_helper/safe_erb/script_interpolation.rb)

package/docs/rules/html-allowed-script-type.md

@@ -0,0 +1,59 @@
+# Linter Rule: Restrict allowed `type` attributes for `<script>` tags
+
+**Rule:** `html-allowed-script-type`
+
+## Description
+
+Restricts which `type` attribute values are permitted on `<script>` tags. Only approved types are allowed: `text/javascript`. An empty or valueless `type` attribute is reported.
+
+## Rationale
+
+Developers frequently use `<script>` tags with non-executable type attributes (like `application/json` or `text/html`) to embed data in pages. However, these tags share parsing quirks with executable scripts and can create security risks. For example, unescaped `</script><script>` sequences inside a `text/html` script tag could enable XSS attacks.
+
+By restricting the allowed `type` values and requiring the `type` attribute to be present, this rule helps catch typos and discourages unsafe or unintended script usage patterns.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<script type="text/javascript">
+  console.log("Hello")
+</script>
+```
+
+```erb
+<script>
+  console.log("Hello")
+</script>
+```
+
+### 🚫 Bad
+
+```erb
+<script type="text/coffeescript">
+  console.log "Hello"
+</script>
+```
+
+```erb
+<script type="application/ecmascript">
+  console.log("Hello")
+</script>
+```
+
+```erb
+<script type="">
+  console.log("Hello")
+</script>
+```
+
+```erb
+<script type>
+  console.log("Hello")
+</script>
+```
+
+## References
+
+- [Inspiration: ERB Lint `AllowedScriptType` rule](https://github.com/Shopify/erb_lint/tree/main?tab=readme-ov-file#allowedscripttype)

package/docs/rules/html-anchor-require-href.md

@@ -4,11 +4,11 @@
 
 ## Description
 
-Disallow the use of anchor tags without an `href` attribute in HTML templates. Use if you want to perform an action without having the user navigated to a new URL.
+An `<a>` element that has an `href` attribute represents a hyperlink (a hypertext anchor) labeled by its contents. Links should go somewhere. If you want to perform an action without navigating the user to a new URL, use a `<button>` instead.
 
 ## Rationale
 
-Anchor tags without href are unfocusable if user is using keyboard navigation, or is unseen by screen readers.
+Anchor tags without an `href` attribute are not focusable via keyboard navigation and are not visible to screen readers. This makes them inaccessible to users who rely on assistive technologies.
 
 ## Examples
 
@@ -20,13 +20,26 @@ Anchor tags without href are unfocusable if user is using keyboard navigation, o
 
 ### 🚫 Bad
 
+```erb
+<a>Go to Page</a>
+```
+
+```erb
+<a href="#">Go to Page</a>
+```
+
 ```erb
 <a data-action="click->doSomething">I'm a fake link</a>
 ```
 
 ## References
 
-* https://marcysutton.com/links-vs-buttons-in-modern-web-applications
-* https://a11y-101.com/design/button-vs-link
-* https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role
-* https://www.scottohara.me/blog/2021/05/28/disabled-links.html#w3c/html-aria#305
+* [MDN: The Anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a)
+* [HTML Spec: The `a` element](https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element)
+* [WAI-ARIA 1.2: `link` role](https://www.w3.org/TR/wai-aria-1.2/#link)
+* [Primer: Links](https://primer.style/design/accessibility/links)
+* [Links vs. Buttons in Modern Web Applications](https://marcysutton.com/links-vs-buttons-in-modern-web-applications)
+* [Button vs. Link](https://a11y-101.com/design/button-vs-link)
+* [MDN: ARIA button role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role)
+* [Disabled Links](https://www.scottohara.me/blog/2021/05/28/disabled-links.html)
+* [`erblint-github`: `LinkHasHref`](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/link-has-href.md)

package/docs/rules/html-details-has-summary.md

@@ -0,0 +1,46 @@
+# Linter Rule: `<details>` elements must have a `<summary>` child
+
+**Rule:** `html-details-has-summary`
+
+## Description
+
+Ensure that all `<details>` elements have a direct `<summary>` child element that describes what the disclosure widget will expand.
+
+## Rationale
+
+The `<summary>` element provides a visible label for the `<details>` disclosure widget, hinting to the user what they'll be expanding. Screen reader users rely on `<summary>` elements to understand the purpose of the expandable content. If a developer omits the `<summary>`, the user agent adds a default one with no meaningful context. The `<summary>` must be a direct child of `<details>` to function correctly — nesting it inside another element will not work as intended.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<details>
+  <summary>Expand me!</summary>
+  I do have a summary tag!
+</details>
+
+<details>
+  I do have a summary tag!
+  <summary>Expand me!</summary>
+</details>
+```
+
+### 🚫 Bad
+
+```erb
+<details>
+  I don't have a summary tag!
+</details>
+
+<details>
+  <div><summary>Expand me!</summary></div>
+  The summary tag needs to be a direct child of the details tag.
+</details>
+```
+
+## References
+
+- [HTML: `details` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details)
+- [HTML: `summary` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary)
+- [erblint-github: GitHub::Accessibility::DetailsHasSummary](https://github.com/github/erblint-github/pull/23)

package/docs/rules/html-img-require-alt.md

@@ -31,12 +31,14 @@ Omitting the `alt` attribute entirely leads to poor accessibility and can negati
 ```erb
 <img src="/logo.png">
 
-<img src="/avatar.jpg" alt> <!-- TODO -->
+<img src="/avatar.jpg" alt>
 
 <%= image_tag image_path("logo.png") %> <!-- TODO -->
 ```
 
 ## References
 
-* [W3C: Alternative Text](https://www.w3.org/WAI/tutorials/images/)
-* [WCAG 2.1: Non-text Content](https://www.w3.org/WAI/WCAG22/quickref/?versions=2.1#non-text-content)
+- [W3C WAI Images Tutorial](https://www.w3.org/WAI/tutorials/images/)
+- [WCAG 2.1: Non-text Content](https://www.w3.org/WAI/WCAG22/quickref/?versions=2.1#non-text-content)
+- [Primer: Alternative text for images](https://primer.style/accessibility/design-guidance/alternative-text-for-images/)
+- [erblint-github: `GitHub::Accessibility::ImageHasAlt`](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/image-has-alt.md)

package/docs/rules/html-no-abstract-roles.md

@@ -0,0 +1,74 @@
+# Linter Rule: No abstract ARIA roles
+
+**Rule:** `html-no-abstract-roles`
+
+## Description
+
+Prevent usage of WAI-ARIA abstract roles in the `role` attribute.
+
+## Rationale
+
+The WAI-ARIA specification defines a set of abstract roles that are used to support the ARIA Roles Model for the purpose of defining general role concepts.
+
+Abstract roles are used for the ontology only. They exist to help organize the hierarchy of roles and define shared characteristics, but they are not meant to be used by authors directly. Using abstract roles in content provides no semantic meaning to assistive technologies and can lead to accessibility issues.
+
+Authors **MUST NOT** use abstract roles in content. Instead, use one of the concrete roles that inherit from these abstract roles. For example, use `button` instead of `command`, or `navigation` instead of `landmark`.
+
+The following abstract roles must not be used:
+
+- `command`
+- `composite`
+- `input`
+- `landmark`
+- `range`
+- `roletype`
+- `section`
+- `sectionhead`
+- `select`
+- `structure`
+- `widget`
+- `window`
+
+## Examples
+
+### ✅ Good
+
+```erb
+<div role="button">Push it</div>
+```
+
+```erb
+<nav role="navigation">Menu</nav>
+```
+
+```erb
+<div role="alert">Warning!</div>
+```
+
+```erb
+<div role="slider" aria-valuenow="50">Volume</div>
+```
+
+### 🚫 Bad
+
+```erb
+<div role="window">Hello, world!</div>
+```
+
+```erb
+<div role="widget">Content</div>
+```
+
+```erb
+<div role="command">Action</div>
+```
+
+```erb
+<div role="landmark">Navigation</div>
+```
+
+## References
+
+- [WAI-ARIA 1.0: Abstract Roles](https://www.w3.org/TR/wai-aria-1.0/roles#abstract_roles)
+- [WAI-ARIA 1.2: Abstract Roles](https://www.w3.org/TR/wai-aria-1.2/#abstract_roles)
+- [ember-template-lint: no-abstract-roles](https://github.com/ember-template-lint/ember-template-lint/blob/main/docs/rule/no-abstract-roles.md)

package/docs/rules/html-no-aria-hidden-on-body.md

@@ -0,0 +1,44 @@
+# Linter Rule: No `aria-hidden` on `<body>`
+
+**Rule:** `html-no-aria-hidden-on-body`
+
+## Description
+
+Prevent usage of `aria-hidden` on `<body>` tags.
+
+## Rationale
+
+The `aria-hidden` attribute should never be present on the `<body>` element, as it hides the entire document from assistive technology users. This makes the entire page completely inaccessible to screen reader users, which is a critical accessibility violation.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<body>
+  <main>Content</main>
+</body>
+
+<body class="app" id="main">
+  <main>Content</main>
+</body>
+```
+
+### 🚫 Bad
+
+```erb
+<body aria-hidden>
+  <main>Content</main>
+</body>
+
+<body aria-hidden="true">
+  <main>Content</main>
+</body>
+```
+
+## References
+
+- [Using the aria-hidden attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-hidden_attribute)
+- [How Lighthouse identifies hidden body elements](https://web.dev/aria-hidden-body/)
+- [WCAG 4.1.2 - Name, Role, Value (Level A)](https://www.w3.org/TR/WCAG21/#name-role-value)
+- [ember-template-lint: no-aria-hidden-body](https://github.com/ember-template-lint/ember-template-lint/blob/main/docs/rule/no-aria-hidden-body.md)