@herb-tools/linter 0.8.9 → 0.9.0

package/docs/rules/erb-no-conditional-open-tag.md

@@ -0,0 +1,130 @@
+# Linter Rule: Disallow conditional open tags
+
+**Rule:** `erb-no-conditional-open-tag`
+
+## Description
+
+Disallow the pattern of using ERB conditionals to vary only the open tag of an element (typically to conditionally change attributes) while sharing the same tag name, body content, and close tag.
+
+## Rationale
+
+This pattern can be difficult to read and maintain. The conditional logic is split from the element's body and closing tag, making it harder to understand the full structure at a glance.
+
+Prefer using:
+
+- `content_tag` with conditional attributes
+- A ternary or conditional for the class/attribute value directly
+- Separate complete elements in each branch if the differences are significant
+
+## Examples
+
+### ✅ Good
+
+Using conditional attributes directly:
+
+```erb
+<div class="<%= @condition ? 'a' : 'b' %>">
+  Content
+</div>
+```
+
+Using `content_tag` with conditional options:
+
+```erb
+<%= content_tag :div, class: (@condition ? 'a' : 'b') do %>
+  Content
+<% end %>
+```
+
+Using `class_names` helper:
+
+```erb
+<div class="<%= class_names('base', 'a': @condition, 'b': !@condition) %>">
+  Content
+</div>
+```
+
+Complete separate elements when differences are significant:
+
+```erb
+<% if @condition %>
+  <div class="a" data-foo="bar">Content</div>
+<% else %>
+  <div class="b" data-baz="qux">Content</div>
+<% end %>
+```
+
+Self-closing/void elements in conditionals (each branch is complete):
+
+```erb
+<% if @large %>
+  <img src="photo.jpg" width="800" height="600">
+<% else %>
+  <img src="photo.jpg" width="400" height="300">
+<% end %>
+```
+
+### 🚫 Bad
+
+Conditional open tags with shared body and close tag:
+
+```erb
+<% if @condition %>
+  <div class="a">
+<% else %>
+  <div class="b">
+<% end %>
+  Content
+</div>
+```
+
+```erb
+<% if @with_icon %>
+  <button class="btn btn-icon" aria-label="Action">
+<% else %>
+  <button class="btn">
+<% end %>
+  Click me
+</button>
+```
+
+Open tag in conditional without else branch:
+
+```erb
+<% if @wrap %>
+  <div class="wrapper">
+<% end %>
+  Content
+</div>
+```
+
+Missing open tag in else branch:
+
+```erb
+<% if @style == "a" %>
+  <div class="a">
+<% elsif @style == "b" %>
+  <div class="b">
+<% else %>
+<% end %>
+  Content
+</div>
+```
+
+Missing open tag in elsif branch:
+
+```erb
+<% if @style == "a" %>
+  <div class="a">
+<% elsif @style == "b" %>
+  <%# no-open-tag %>
+<% else %>
+  <div class="c">
+<% end %>
+  Content
+</div>
+```
+
+## References
+
+\-

package/docs/rules/erb-no-duplicate-branch-elements.md

@@ -0,0 +1,98 @@
+# Linter Rule: Disallow duplicate elements across conditional branches
+
+**Rule:** `erb-no-duplicate-branch-elements`
+
+## Description
+
+Disallow the same HTML elements wrapping content in every branch of an ERB conditional (`if/elsif/else`, `unless/else`, `case/when/else`). When all branches share identical wrapper elements, those elements should be hoisted outside the conditional. Only flags when all branches are covered (i.e., an `else` clause is present).
+
+## Rationale
+
+Duplicated wrapper elements across all branches of a conditional are unnecessary repetition. Moving them outside the conditional reduces template size, makes the structure clearer, and avoids the risk of branches getting out of sync when one is updated but others are forgotten.
+
+## Examples
+
+### ✅ Good
+
+Elements hoisted outside the conditional:
+
+```erb
+<div class="wrapper">
+  <% if condition %>
+    Hello World
+  <% else %>
+    Goodbye World
+  <% end %>
+</div>
+```
+
+Branches with different elements:
+
+```erb
+<% if condition %>
+  <div>Hello World</div>
+<% else %>
+  <span>World</span>
+<% end %>
+```
+
+Same tag name but different attributes:
+
+```erb
+<% if condition %>
+  <div class="a">Hello World</div>
+<% else %>
+  <div class="b">World</div>
+<% end %>
+```
+
+Incomplete branch coverage:
+
+```erb
+<% if condition %>
+  <div>Hello World</div>
+<% end %>
+```
+
+### 🚫 Bad
+
+```erb
+<% if condition %>
+  <div>Hello World</div>
+<% else %>
+  <div>Goodbye World</div>
+<% end %>
+```
+
+```erb
+<% if condition %>
+  <div>Hello World</div>
+<% elsif other %>
+  <div>Goodbye World</div>
+<% else %>
+  <div>Default</div>
+<% end %>
+```
+
+```erb
+<% case value %>
+<% when "a" %>
+  <div>Hello World</div>
+<% when "b" %>
+  <div>Goodbye World</div>
+<% else %>
+  <div>Default</div>
+<% end %>
+```
+
+```erb
+<% if condition %>
+  <div><p>Hello World</p></div>
+<% else %>
+  <div><p>Goodbye World</p></div>
+<% end %>
+```
+
+## References
+
+\-

package/docs/rules/erb-no-inline-case-conditions.md

@@ -0,0 +1,85 @@
+# Linter Rule: Disallow inline case conditions
+
+**Rule:** `erb-no-inline-case-conditions`
+
+## Description
+
+Disallow placing `case` and its first `when`/`in` condition in the same ERB tag. When a `case` statement and its condition appear in a single ERB tag (e.g., `<% case x when y %>`), the parser cannot reliably process, compile, or format the template. This rule flags such patterns and guides users toward separate ERB tags.
+
+## Rationale
+
+ERB templates that combine `case` with a `when` or `in` condition in a single tag create parsing ambiguity. The parser creates synthetic condition nodes to handle this pattern in non-strict mode, but the resulting AST cannot be reliably formatted or compiled.
+
+Using separate ERB tags for `case` and its conditions:
+
+- Makes the template structure unambiguous for the parser
+- Enables proper formatting and compilation
+- Improves readability by clearly separating the case expression from its branches
+- Follows the conventional ERB style used across the Ruby on Rails ecosystem
+
+## Examples
+
+### ✅ Good
+
+`case`/`when` in separate ERB tags:
+
+```erb
+<% case variable %>
+<% when "a" %>
+  A
+<% when "b" %>
+  B
+<% else %>
+  Other
+<% end %>
+```
+
+`case`/`in` (pattern matching) in separate ERB tags:
+
+```erb
+<% case value %>
+<% in 1 %>
+  One
+<% in 2 %>
+  Two
+<% else %>
+  Other
+<% end %>
+```
+
+### 🚫 Bad
+
+Inline `case`/`when` in a single ERB tag:
+
+```erb
+<% case variable when "a" %>
+  A
+<% when "b" %>
+  B
+<% end %>
+```
+
+Inline `case`/`in` in a single ERB tag:
+
+```erb
+<% case value in 1 %>
+  One
+<% in 2 %>
+  Two
+<% end %>
+```
+
+`case`/`when` on separate lines but still in the same ERB tag:
+
+```erb
+<% case variable
+   when "a" %>
+  A
+<% when "b" %>
+  B
+<% end %>
+```
+
+## References
+
+\-

package/docs/rules/erb-no-instance-variables-in-partials.md

@@ -0,0 +1,43 @@
+# Linter Rule: Disallow instance variables in partials
+
+**Rule:** `erb-no-instance-variables-in-partials`
+
+## Description
+
+Prevent usage of instance variables inside ERB partials. Using instance variables inside partials can cause issues as their dependency is defined outside of the partial itself. This makes partials more fragile and less reusable. Local variables should be passed directly to partial renders.
+
+A partial is any template whose filename begins with an underscore (e.g. `_card.html.erb`).
+
+Instance variables in partials create implicit dependencies on the controller or parent view, making partials harder to reuse, test, and reason about. Passing data as local variables makes the partial's interface explicit and self-documenting.
+
+## Examples
+
+### ✅ Good
+
+```erb [app/views/posts/index.html.erb]
+<%= render partial: "posts/card", locals: { post: @post } %>
+```
+
+```erb [app/views/posts/_card.html.erb]
+<div>
+  <%= post.title %>
+</div>
+```
+
+### 🚫 Bad
+
+```erb [app/views/posts/index.html.erb]
+<%= render partial: "posts/card" %>
+```
+
+```erb [app/views/posts/_card.html.erb]
+<div>
+  <%= @post.title %>
+</div>
+```
+
+## References
+
+- [Rails Guide: Using Partials](https://guides.rubyonrails.org/layouts_and_rendering.html#using-partials)
+- [Rails Guide: Passing Local Variables](https://guides.rubyonrails.org/layouts_and_rendering.html#passing-local-variables)
+- [Inspiration: ERB Lint `PartialInstanceVariable` rule](https://github.com/Shopify/erb_lint?tab=readme-ov-file#partialinstancevariable)

package/docs/rules/erb-no-interpolated-class-names.md

@@ -0,0 +1,57 @@
+# Linter Rule: Disallow ERB interpolation inside CSS class names
+
+**Rule:** `erb-no-interpolated-class-names`
+
+## Description
+
+Disallow ERB expressions that are embedded within CSS class names (e.g., `bg-<%= color %>-400`). Standalone ERB expressions that output complete class names are allowed.
+
+## Rationale
+
+Since tools like Tailwind CSS and [Herb's Tailwind class sorter](https://herb-tools.dev/projects/rewriter#tailwind-class-sorter) scan your source files as plain text, they have no way of understanding string interpolation. A class like `bg-<%= color %>-400` doesn't exist as a complete string anywhere in the source, so Tailwind won't generate it and the class sorter can't recognize or reorder it.
+
+Beyond tooling, interpolated class names are also impossible to search for in editors. Searching for `bg-red-400` will never match `bg-<%= color %>-400`, making it difficult to find all usages of a class name across the codebase. Static analysis tools face the same problem since they can't determine which class names a template produces without evaluating the Ruby expression at runtime.
+
+Instead, always use complete class names in your templates. This keeps each class name searchable, sortable, and statically analyzable.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<div class="bg-blue-400 <%= dynamic_classes %> text-green-400"></div>
+```
+
+```erb
+<div class="<%= classes %>"></div>
+```
+
+```erb
+<div class="<%= a %> bg-blue-500 <%= b %>"></div>
+```
+
+```erb
+<div class="<%= class_names('bg-blue-400': blue?, 'bg-red-400': red?) %>"></div>
+```
+
+```erb
+<div class="<%= error? ? 'text-red-600' : 'text-green-600' %>"></div>
+```
+
+### 🚫 Bad
+
+```erb
+<div class="bg-<%= color %>-400"></div>
+```
+
+```erb
+<div class="bg-<%= suffix %>"></div>
+```
+
+```erb
+<div class="<%= prefix %>-blue-500"></div>
+```
+
+## References
+
+- [Tailwind CSS: Dynamic class names](https://tailwindcss.com/docs/detecting-classes-in-source-files#dynamic-class-names)

package/docs/rules/erb-no-javascript-tag-helper.md

@@ -0,0 +1,33 @@
+# Linter Rule: Disallow `javascript_tag` helper
+
+**Rule:** `erb-no-javascript-tag-helper`
+
+## Description
+
+The `javascript_tag do` helper syntax is deprecated. Use inline `<script>` tags instead, which allows the linter to properly analyze ERB output within JavaScript.
+
+## Rationale
+
+The `javascript_tag` helper renders its block as raw text, which means unsafe ERB interpolation inside it cannot be detected by other safety rules like `erb-no-unsafe-script-interpolation` or `erb-no-statement-in-script`. By using inline `<script>` tags instead, the linter can properly parse and validate that Ruby data is safely serialized with `.to_json` before being interpolated into JavaScript.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<script>
+  if (a < 1) { alert("hello") }
+</script>
+```
+
+### 🚫 Bad
+
+```erb
+<%= javascript_tag do %>
+  if (a < 1) { <%= unsafe %> }
+<% end %>
+```
+
+## References
+
+- [Shopify/better-html — `NoJavascriptTagHelper`](https://github.com/Shopify/better-html/blob/main/lib/better_html/test_helper/safe_erb/no_javascript_tag_helper.rb)

package/docs/rules/erb-no-output-in-attribute-name.md

@@ -0,0 +1,38 @@
+# Linter Rule: Disallow ERB output in attribute names
+
+**Rule:** `erb-no-output-in-attribute-name`
+
+## Description
+
+ERB output tags (`<%= %>`) are not allowed in HTML attribute names. Use static attribute names with dynamic values instead.
+
+## Rationale
+
+ERB output in attribute names (e.g., `<div data-<%= key %>="value">`) allows dynamic control over which attributes are rendered. When such a value is user-controlled, an attacker can inject arbitrary attributes including JavaScript event handlers, achieving cross-site scripting (XSS).
+
+## Examples
+
+### Good
+
+```erb
+<div class="<%= css_class %>"></div>
+```
+
+```erb
+<input type="text" data-target="value">
+```
+
+### Bad
+
+```erb
+<div data-<%= key %>="value"></div>
+```
+
+```erb
+<div data-<%= key1 %>="value1" data-<%= key2 %>="value2"></div>
+```
+
+## References
+
+- [Shopify/erb_lint: `ErbSafety`](https://github.com/Shopify/erb_lint/tree/main?tab=readme-ov-file#erbsafety)
+- [Shopify/better_html](https://github.com/Shopify/better_html)

package/docs/rules/erb-no-output-in-attribute-position.md

@@ -0,0 +1,60 @@
+# Linter Rule: Disallow ERB output in attribute position
+
+**Rule:** `erb-no-output-in-attribute-position`
+
+## Description
+
+ERB output tags (`<%= %>` or `<%== %>`) are not allowed in attribute position. Use ERB control flow (`<% %>`) with static attribute names instead.
+
+## Rationale
+
+ERB output tags in attribute positions (e.g., `<div <%= attributes %>>`) allow arbitrary attribute injection at runtime. An attacker could inject event handler attributes like `onmouseover` or `onfocus` to execute JavaScript.
+
+For example, a common pattern like:
+
+```erb
+<div <%= "hidden" if index != 0 %>>...</div>
+```
+
+should be rewritten to use control flow with static attributes:
+
+```erb
+<div <% if index != 0 %> hidden <% end %>>...</div>
+```
+
+This ensures attribute names are always statically defined and prevents arbitrary attribute injection.
+
+## Examples
+
+### Good
+
+```erb
+<div class="<%= css_class %>"></div>
+```
+
+```erb
+<input value="<%= user.name %>">
+```
+
+```erb
+<div <% if active? %> class="active" <% end %>></div>
+```
+
+### Bad
+
+```erb
+<div <%= data_attributes %>></div>
+```
+
+```erb
+<div <%== raw_attributes %>></div>
+```
+
+```erb
+<div <%= first_attrs %> <%= second_attrs %>></div>
+```
+
+## References
+
+- [Shopify/erb_lint: `ErbSafety`](https://github.com/Shopify/erb_lint/tree/main?tab=readme-ov-file#erbsafety)
+- [Shopify/better_html](https://github.com/Shopify/better_html)

package/docs/rules/erb-no-raw-output-in-attribute-value.md

@@ -0,0 +1,37 @@
+# Linter Rule: Disallow `<%==` in attribute values
+
+**Rule:** `erb-no-raw-output-in-attribute-value`
+
+## Description
+
+ERB interpolation with `<%==` inside HTML attribute values is never safe. The `<%==` syntax bypasses HTML escaping entirely, allowing arbitrary attribute injection and XSS attacks. Use `<%=` instead to ensure proper escaping.
+
+## Rationale
+
+The `<%==` syntax outputs content without any HTML escaping. In an attribute value context, this means an attacker can inject a quote character to terminate the attribute, then inject arbitrary attributes including JavaScript event handlers. Even when combined with `.to_json`, using `<%==` in attributes is unsafe because it bypasses the template engine's built-in escaping that prevents attribute breakout.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<div class="<%= user_input %>"></div>
+```
+
+### 🚫 Bad
+
+```erb
+<div class="<%== user_input %>"></div>
+```
+
+```erb
+<a href="<%== unsafe %>">Link</a>
+```
+
+```erb
+<a onclick="method(<%== unsafe.to_json %>)"></a>
+```
+
+## 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-statement-in-script.md

@@ -0,0 +1,68 @@
+# Linter Rule: Disallow ERB statements inside `<script>` tags
+
+**Rule:** `erb-no-statement-in-script`
+
+## Description
+
+Only insert expressions (`<%=` or `<%==`) inside `<script>` tags, never statements (`<% %>`). Statement tags inside `<script>` are likely a mistake, the author probably meant to use `<%= %>` to output a value.
+
+## Rationale
+
+ERB statement tags inside `<script>` tags execute Ruby code but produce no output into the JavaScript context, which is rarely intentional. If you need to interpolate a value into JavaScript, use expression tags (`<%= %>`) with `.to_json` for safe serialization. If you need conditional logic, restructure the template to keep control flow outside the `<script>` tag.
+
+Exceptions: `<% end %>` is allowed (for closing blocks), ERB comments (`<%# %>`) are allowed, and `<script type="text/html">` allows statement tags since it contains HTML templates, not JavaScript.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<script>
+  var myValue = <%== value.to_json %>;
+  if (myValue) doSomething();
+</script>
+```
+
+```erb
+<script type="text/template">
+  <%= ui_form do %>
+    <div></div>
+  <% end %>
+</script>
+```
+
+```erb
+<script type="text/javascript">
+  <%# comment %>
+</script>
+```
+
+```erb
+<script type="text/html">
+  <% if condition %>
+    <p>Content</p>
+  <% end %>
+</script>
+```
+
+### 🚫 Bad
+
+```erb
+<script>
+  <% if value %>
+    doSomething();
+  <% end %>
+</script>
+```
+
+```erb
+<script type="text/javascript">
+  <% if foo? %>
+    bla
+  <% end %>
+</script>
+```
+
+## References
+
+- [Shopify/better-html - `NoStatements`](https://github.com/Shopify/better-html/blob/main/lib/better_html/test_helper/safe_erb/no_statements.rb)