@herb-tools/linter 0.9.0 → 0.9.1

package/docs/rules/README.md

@@ -5,10 +5,12 @@ This page contains documentation for all Herb Linter rules.
 ## Available Rules
 
 - [`actionview-no-silent-helper`](./actionview-no-silent-helper.md) - Disallow silent ERB tags for Action View helpers
+- [`actionview-no-silent-render`](./actionview-no-silent-render.md) - Disallow calling `render` without outputting the result
 - [`erb-comment-syntax`](./erb-comment-syntax.md) - Disallow Ruby comments immediately after ERB tags
 - [`erb-no-case-node-children`](./erb-no-case-node-children.md) - Don't use `children` for `case/when` and `case/in` nodes
 - [`erb-no-conditional-html-element`](./erb-no-conditional-html-element.md) - Disallow conditional HTML elements
 - [`erb-no-duplicate-branch-elements`](./erb-no-duplicate-branch-elements.md) - Disallow duplicate elements across conditional branches
+- [`erb-no-empty-control-flow`](./erb-no-empty-control-flow.md) - Disallow empty ERB control flow blocks
 - [`erb-no-empty-tags`](./erb-no-empty-tags.md) - Disallow empty ERB tags
 - [`erb-no-extra-newline`](./erb-no-extra-newline.md) - Disallow extra newlines.
 - [`erb-no-extra-whitespace-inside-tags`](./erb-no-extra-whitespace-inside-tags.md) - Disallow multiple consecutive spaces inside ERB tags
@@ -20,6 +22,7 @@ This page contains documentation for all Herb Linter rules.
 - [`erb-no-output-in-attribute-name`](./erb-no-output-in-attribute-name.md) - Disallow ERB output in attribute names
 - [`erb-no-output-in-attribute-position`](./erb-no-output-in-attribute-position.md) - Disallow ERB output in attribute position
 - [`erb-no-raw-output-in-attribute-value`](./erb-no-raw-output-in-attribute-value.md) - Disallow `<%==` in attribute values
+- [`erb-no-silent-statement`](./erb-no-silent-statement.md) - Disallow silent ERB statements
 - [`erb-no-silent-tag-in-attribute-name`](./erb-no-silent-tag-in-attribute-name.md) - Disallow ERB silent tags in HTML attribute names
 - [`erb-no-statement-in-script`](./erb-no-statement-in-script.md) - Disallow ERB statements inside `<script>` tags
 - [`erb-no-then-in-control-flow`](./erb-no-then-in-control-flow.md) - Disallow `then` in ERB control flow expressions

package/docs/rules/actionview-no-silent-render.md

@@ -0,0 +1,47 @@
+# Linter Rule: Do not call `render` without rendering the result
+
+**Rule:** `actionview-no-silent-render`
+
+## Description
+
+Require that all `render` calls in ERB appear inside output tags (`<%= ... %>`), not control tags (`<% ... %>`). Otherwise, the call is evaluated but its result is silently discarded.
+
+## Rationale
+
+Rails' `render` method returns HTML-safe strings meant to be included in the final response. If it's placed inside a non-output ERB tag (`<% render(...) %>`), the result is silently ignored. This is almost always a mistake and leads to confusion.
+
+This rule catches these silent rendering issues and enforces that `render` is only used when its result is actually rendered.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<%= render "shared/error" %>
+```
+
+```erb
+<%= render partial: "comment", collection: @comments %>
+```
+
+```erb
+<%= render @product %>
+```
+
+### 🚫 Bad
+
+```erb
+<% render "shared/error" %>
+```
+
+```erb
+<% render partial: "comment", collection: @comments %>
+```
+
+```erb
+<% render @product %>
+```
+
+## References
+
+\-

package/docs/rules/erb-no-empty-control-flow.md

@@ -0,0 +1,83 @@
+# Linter Rule: Disallow empty ERB control flow blocks
+
+**Rule:** `erb-no-empty-control-flow`
+
+## Description
+
+Disallow empty ERB control flow blocks such as `if`, `elsif`, `else`, `unless`, `for`, `while`, `until`, `when`, `in`, `begin`, `rescue`, `ensure`, and `do` blocks.
+
+Empty control flow blocks add unnecessary noise to templates and are often the result of incomplete refactoring, copy/paste errors, or forgotten placeholder code.
+
+## Rationale
+
+An empty control flow block serves no purpose and makes templates harder to read. It often indicates code that was accidentally deleted, an incomplete refactoring where the logic was removed but the structure was left behind, or a placeholder that was never filled in.
+
+This rule helps keep templates clean and intentional. Offenses are reported as hints with the `unnecessary` diagnostic tag, so editors like VS Code will render the empty blocks with faded text.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<% if condition %>
+  <p>Content</p>
+<% end %>
+```
+
+```erb
+<% case status %>
+<% when "active" %>
+  <p>Active</p>
+<% when "inactive" %>
+  <p>Inactive</p>
+<% end %>
+```
+
+```erb
+<% items.each do |item| %>
+  <p><%= item.name %></p>
+<% end %>
+```
+
+### 🚫 Bad
+
+```erb
+<% if condition %>
+<% end %>
+```
+
+```erb
+<% if condition %>
+  <p>Content</p>
+<% else %>
+<% end %>
+```
+
+```erb
+<% case value %>
+<% when "a" %>
+<% when "b" %>
+  <p>B</p>
+<% end %>
+```
+
+```erb
+<% unless condition %>
+<% end %>
+```
+
+```erb
+<% items.each do |item| %>
+<% end %>
+```
+
+```erb
+<% begin %>
+  <p>Try this</p>
+<% rescue %>
+<% end %>
+```
+
+## References
+
+\-

package/docs/rules/erb-no-silent-statement.md

@@ -0,0 +1,53 @@
+# Linter Rule: Disallow silent ERB statements
+
+**Rule:** `erb-no-silent-statement`
+
+## Description
+
+Disallow silent ERB tags (`<% %>`) that execute statements whose return value is discarded. Logic like method calls should live in controllers, helpers, or presenters, not in views. Assignments are allowed since they are pragmatic for DRYing up templates.
+
+## Rationale
+
+Silent ERB tags that aren't control flow or assignments are a code smell. They execute Ruby code whose return value is silently discarded, which usually means the logic belongs in a controller, helper, or presenter rather than the view.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<%= title %>
+<%= render "partial" %>
+```
+
+```erb
+<% x = 1 %>
+<% @title = "Hello" %>
+<% x ||= default_value %>
+<% x += 1 %>
+```
+
+```erb
+<% if user.admin? %>
+  Admin tools
+<% end %>
+```
+
+```erb
+<% users.each do |user| %>
+  <p><%= user.name %></p>
+<% end %>
+```
+
+### 🚫 Bad
+
+```erb
+<% some_method %>
+```
+
+```erb
+<% helper_call(arg) %>
+```
+
+## References
+
+\-

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

@@ -4,11 +4,13 @@
 
 ## 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.
+ERB interpolation in `<script>` tags must use `.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.
+
+This rule also detects usage of `j()` and `escape_javascript()` inside `<script>` tags and recommends `.to_json` instead, because `j()` is only safe when the output is placed inside quoted string literals, a subtle requirement that is easy to get wrong.
 
 ## 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.
+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, an attacker can inject arbitrary JavaScript by manipulating the interpolated value.
 
 For example, consider:
 
@@ -18,7 +20,17 @@ For example, consider:
 </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:
+If `user.name` contains `"; alert(1); "`, it renders as:
+
+```html
+<script>
+  var name = ""; alert(1); "";
+</script>
+```
+
+This is a Cross-Site Scripting (XSS) vulnerability, as the attacker breaks out of the string literal and executes arbitrary JavaScript.
+
+Using `.to_json` properly escapes the value and wraps it in quotes:
 
 ```erb
 <script>
@@ -26,6 +38,47 @@ If `user.name` contains `"; alert(1); "`, the resulting JavaScript would execute
 </script>
 ```
 
+With the same malicious input `"; alert(1); "`, `.to_json` safely renders:
+
+```html
+<script>
+  var name = "\"; alert(1); \"";
+</script>
+```
+
+The value stays contained as a string, and no code is executed.
+
+### Why not `j()` or `escape_javascript()`?
+
+`j()` escapes characters special inside JavaScript string literals (quotes, newlines, etc.), but it does **not** produce a quoted value. This means it's only safe when wrapped in quotes.
+
+This works, but is fragile. In this example safety depends on the surrounding quotes:
+```erb
+<script>
+  var name = '<%= j user.name %>';
+</script>
+```
+
+Without quotes, `j()` provides no protection and is **UNSAFE**, so code can still be injected:
+
+```erb
+<script>
+  var name = <%= j user.name %>;
+</script>
+```
+
+If `user.name` is `alert(1)`, `j()` passes it through unchanged (no special characters to escape), rendering:
+
+```html
+<script>
+  var name = alert(1);
+</script>
+```
+
+This results in a Cross-Site Scripting (XSS) vulnerability, as the attacker-controlled value is interpreted as JavaScript code rather than a string/data.
+
+`.to_json` is safe in any position because it always produces a valid, quoted JavaScript value.
+
 ## Examples
 
 ### ✅ Good
@@ -68,6 +121,20 @@ If `user.name` contains `"; alert(1); "`, the resulting JavaScript would execute
 </script>
 ```
 
+### ⚠️ Prefer `.to_json` over `j()` / `escape_javascript()`
+
+```diff
+- const url = '<%= j @my_path %>';
++ const url = <%= @my_path.to_json %>;
+```
+
+```diff
+- const name = '<%= escape_javascript(user.name) %>';
++ const name = <%= user.name.to_json %>;
+```
+
 ## References
 
 - [Shopify/better-html — ScriptInterpolation](https://github.com/Shopify/better-html/blob/main/lib/better_html/test_helper/safe_erb/script_interpolation.rb)
+- [`escape_javascript` / `j`](https://api.rubyonrails.org/classes/ActionView/Helpers/JavaScriptHelper.html#method-i-escape_javascript)
+- [`json_escape`](https://api.rubyonrails.org/classes/ERB/Util.html#method-c-json_escape)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herb-tools/linter",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "HTML+ERB linter for validating HTML structure and enforcing best practices",
   "license": "MIT",
   "homepage": "https://herb-tools.dev",
@@ -22,7 +22,7 @@
     "watch": "tsc -b -w",
     "test": "vitest run",
     "test:watch": "vitest --watch",
-    "prepublishOnly": "yarn clean && yarn build"
+    "prepublishOnly": "yarn clean && yarn build && yarn test"
   },
   "exports": {
     "./package.json": "./package.json",
@@ -46,12 +46,12 @@
     }
   },
   "dependencies": {
-    "@herb-tools/config": "0.9.0",
-    "@herb-tools/core": "0.9.0",
-    "@herb-tools/highlighter": "0.9.0",
-    "@herb-tools/node-wasm": "0.9.0",
-    "@herb-tools/printer": "0.9.0",
-    "@herb-tools/rewriter": "0.9.0",
+    "@herb-tools/config": "0.9.1",
+    "@herb-tools/core": "0.9.1",
+    "@herb-tools/highlighter": "0.9.1",
+    "@herb-tools/node-wasm": "0.9.1",
+    "@herb-tools/printer": "0.9.1",
+    "@herb-tools/rewriter": "0.9.1",
     "picomatch": "^4.0.2",
     "tinyglobby": "^0.2.15"
   },

package/src/index.ts

@@ -4,3 +4,24 @@ export * from "./types.js"
 
 export { ruleDocumentationUrl } from "./urls.js"
 export { rules } from "./rules.js"
+
+export {
+  findAttributeByName,
+  getAttribute,
+  getAttributeName,
+  getAttributes,
+  getAttributeValue,
+  getAttributeValueNodes,
+  getAttributeValueQuoteType,
+  getCombinedAttributeNameString,
+  getStaticAttributeValue,
+  getStaticAttributeValueContent,
+  getTagName,
+  hasAttribute,
+  hasAttributeValue,
+  hasDynamicAttributeName,
+  hasDynamicAttributeValue,
+  hasStaticAttributeValue,
+  hasStaticAttributeValueContent,
+  isAttributeValueQuoted,
+} from "@herb-tools/core"

package/src/rules/actionview-no-silent-render.ts

@@ -0,0 +1,44 @@
+import { ParserRule } from "../types.js"
+import { BaseRuleVisitor } from "./rule-utils.js"
+import { isERBOutputNode } from "@herb-tools/core"
+
+import type { ERBRenderNode, ParseResult, ParserOptions } from "@herb-tools/core"
+import type { FullRuleConfig, LintContext, UnboundLintOffense } from "../types.js"
+
+class ActionViewNoSilentRenderVisitor extends BaseRuleVisitor {
+  visitERBRenderNode(node: ERBRenderNode): void {
+    if (!isERBOutputNode(node)) {
+      this.addOffense(
+        `Avoid using \`${node.tag_opening?.value} %>\` with \`render\`. Use \`<%= %>\` to ensure the rendered content is output.`,
+        node.location,
+      )
+    }
+
+    this.visitChildNodes(node)
+  }
+}
+
+export class ActionViewNoSilentRenderRule extends ParserRule {
+  static ruleName = "actionview-no-silent-render"
+
+  get defaultConfig(): FullRuleConfig {
+    return {
+      enabled: true,
+      severity: "error"
+    }
+  }
+
+  get parserOptions(): Partial<ParserOptions> {
+    return {
+      render_nodes: true,
+    }
+  }
+
+  check(result: ParseResult, context?: Partial<LintContext>): UnboundLintOffense[] {
+    const visitor = new ActionViewNoSilentRenderVisitor(this.ruleName, context)
+
+    visitor.visit(result.value)
+
+    return visitor.offenses
+  }
+}

package/src/rules/erb-no-case-node-children.ts

@@ -28,10 +28,12 @@ class ERBNoCaseNodeChildrenVisitor extends BaseRuleVisitor {
       if (!this.isAllowedContent(child)) {
         const childCode = IdentityPrinter.print(child).trim()
 
-        this.addOffense(
+        const offense = this.createOffense(
           `Do not place \`${childCode}\` between \`${caseCode}\` and \`${conditionCode}\`. Content here is not part of any branch and will not be rendered.`,
           child.location,
         )
+        offense.tags = ["unnecessary"]
+        this.offenses.push(offense)
       }
     }
   }

package/src/rules/erb-no-duplicate-branch-elements.ts

@@ -4,6 +4,7 @@ import { IdentityPrinter } from "@herb-tools/printer"
 
 import {
   isHTMLElementNode,
+  isHTMLOpenTagNode,
   isERBIfNode,
   isERBElseNode,
   isERBUnlessNode,
@@ -27,12 +28,21 @@ type ConditionalNode = ERBIfNode | ERBUnlessNode | ERBCaseNode
 
 interface DuplicateBranchAutofixContext extends BaseAutofixContext {
   node: Mutable<ConditionalNode>
+  allIdentical?: boolean
 }
 
 function getSignificantNodes(statements: Node[]): Node[] {
   return statements.filter(node => !isPureWhitespaceNode(node))
 }
 
+function trimWhitespaceNodes(nodes: Node[]): Node[] {
+  let start = 0
+  let end = nodes.length
+  while (start < end && isPureWhitespaceNode(nodes[start])) start++
+  while (end > start && isPureWhitespaceNode(nodes[end - 1])) end--
+  return nodes.slice(start, end)
+}
+
 function allEquivalentElements(nodes: Node[]): nodes is HTMLElementNode[] {
   if (nodes.length < 2) return false
   if (!nodes.every(node => isHTMLElementNode(node))) return false
@@ -172,10 +182,31 @@ class ERBNoDuplicateBranchElementsVisitor extends BaseRuleVisitor<DuplicateBranc
       this.markSubsequentIfNodesAsProcessed(node)
     }
 
+    if (this.allBranchesIdentical(branches)) {
+      this.addOffense(
+        "All branches of this conditional have identical content. The conditional can be removed.",
+        node.location,
+        { node: node as Mutable<ConditionalNode>, allIdentical: true },
+        "warning",
+      )
+
+      return
+    }
+
     const state = { isFirstOffense: true }
     this.checkBranches(branches, node, state)
   }
 
+  private allBranchesIdentical(branches: Node[][]): boolean {
+    if (branches.length < 2) return false
+
+    const first = branches[0].map(node => IdentityPrinter.print(node)).join("")
+
+    return branches.slice(1).every(branch =>
+      branch.map(node => IdentityPrinter.print(node)).join("") === first
+    )
+  }
+
   private markSubsequentIfNodesAsProcessed(node: ERBIfNode): void {
     let current: ERBIfNode | ERBElseNode | null = node.subsequent
 
@@ -214,17 +245,37 @@ class ERBNoDuplicateBranchElementsVisitor extends BaseRuleVisitor<DuplicateBranc
 
     for (const element of elements) {
       const printed = IdentityPrinter.print(element.open_tag)
-      const autofixContext = state.isFirstOffense
-        ? { node: conditionalNode as Mutable<ConditionalNode> }
-        : undefined
 
-      this.addOffense(
-        `The \`${printed}\` element is duplicated across all branches of this conditional and can be moved outside.`,
-        bodiesMatch ? element.location : (element?.open_tag?.location || element.location),
-        autofixContext,
-      )
+      if (bodiesMatch) {
+        const autofixContext = state.isFirstOffense
+          ? { node: conditionalNode as Mutable<ConditionalNode> }
+          : undefined
+
+        this.addOffense(
+          `The \`${printed}\` element is duplicated across all branches of this conditional and can be moved outside.`,
+          element.location,
+          autofixContext,
+        )
 
-      state.isFirstOffense = false
+        state.isFirstOffense = false
+      } else {
+        const autofixContext = state.isFirstOffense
+          ? { node: conditionalNode as Mutable<ConditionalNode> }
+          : undefined
+
+        const tagNameLocation = isHTMLOpenTagNode(element.open_tag) && element.open_tag.tag_name?.location
+          ? element.open_tag.tag_name.location
+          : element?.open_tag?.location || element.location
+
+        this.addOffense(
+          `The \`${printed}\` tag is repeated across all branches with different content. Consider extracting the shared tag outside the conditional.`,
+          tagNameLocation,
+          autofixContext,
+          "hint",
+        )
+
+        state.isFirstOffense = false
+      }
     }
 
     if (!bodiesMatch && bodies.every(body => body.length > 0)) {
@@ -260,6 +311,18 @@ export class ERBNoDuplicateBranchElementsRule extends ParserRule<DuplicateBranch
     const branches = collectBranches(conditionalNode as ConditionalNode)
     if (!branches) return null
 
+    if (offense.autofixContext.allIdentical) {
+      const parentInfo = findParentArray(result.value, conditionalNode as unknown as Node)
+      if (!parentInfo) return null
+
+      const { array: parentArray, index: conditionalIndex } = parentInfo
+      const firstBranchContent = trimWhitespaceNodes(branches[0])
+
+      parentArray.splice(conditionalIndex, 1, ...firstBranchContent)
+
+      return result
+    }
+
     const significantBranches = branches.map(getSignificantNodes)
     if (significantBranches.some(branch => branch.length === 0)) return null
 
@@ -274,24 +337,57 @@ export class ERBNoDuplicateBranchElementsRule extends ParserRule<DuplicateBranch
 
     let { array: parentArray, index: conditionalIndex } = parentInfo
     let hasWrapped = false
+    let didMutate = false
+    let failedToHoistPrefix = false
+    let hoistedBefore = false
 
     const hoistElement = (elements: HTMLElementNode[], position: "before" | "after"): void => {
+      const actualPosition = (position === "before" && failedToHoistPrefix) ? "after" : position
       const bodiesMatch = elements.every(element => IdentityPrinter.print(element) === IdentityPrinter.print(elements[0]))
 
       if (bodiesMatch) {
+        if (actualPosition === "after") {
+          const currentLengths = branches.map(b => getSignificantNodes(b as Node[]).length)
+          if (currentLengths.some(l => l !== currentLengths[0])) return
+        }
+
+        if (actualPosition === "after" && position === "before") {
+          const isAtEnd = branches.every((branch, index) => {
+            const nodes = getSignificantNodes(branch as Node[])
+
+            return nodes.length > 0 && nodes[nodes.length - 1] === elements[index]
+          })
+
+          if (!isAtEnd) return
+        }
+
         for (let i = 0; i < branches.length; i++) {
           removeNodeFromArray(branches[i] as Node[], elements[i])
         }
 
-        if (position === "before") {
-          parentArray.splice(conditionalIndex, 0, elements[0])
-          conditionalIndex++
+        if (actualPosition === "before") {
+          parentArray.splice(conditionalIndex, 0, elements[0], createLiteral("\n"))
+          conditionalIndex += 2
+          hoistedBefore = true
         } else {
-          parentArray.splice(conditionalIndex + 1, 0, elements[0])
+          parentArray.splice(conditionalIndex + 1, 0, createLiteral("\n"), elements[0])
         }
+
+        didMutate = true
       } else {
         if (hasWrapped) return
 
+        const canWrap = branches.every((branch, index) => {
+          const remaining = getSignificantNodes(branch)
+
+          return remaining.length === 1 && remaining[0] === elements[index]
+        })
+
+        if (!canWrap) {
+          if (position === "before") failedToHoistPrefix = true
+          return
+        }
+
         for (let i = 0; i < branches.length; i++) {
           replaceNodeWithBody(branches[i] as Node[], elements[i])
         }
@@ -302,6 +398,7 @@ export class ERBNoDuplicateBranchElementsRule extends ParserRule<DuplicateBranch
         parentArray = wrapper.body as Node[]
         conditionalIndex = 1
         hasWrapped = true
+        didMutate = true
       }
     }
 
@@ -315,6 +412,25 @@ export class ERBNoDuplicateBranchElementsRule extends ParserRule<DuplicateBranch
       hoistElement(elements, "after")
     }
 
-    return result
+    if (!hasWrapped && hoistedBefore) {
+      const remaining = branches.map(branch => getSignificantNodes(branch as Node[]))
+
+      if (remaining.every(branch => branch.length === 1) && allEquivalentElements(remaining.map(b => b[0]))) {
+        const elements = remaining.map(b => b[0] as HTMLElementNode)
+        const bodiesMatch = elements.every(el => IdentityPrinter.print(el) === IdentityPrinter.print(elements[0]))
+
+        if (!bodiesMatch && elements.every(el => el.body.length > 0)) {
+          for (let i = 0; i < branches.length; i++) {
+            replaceNodeWithBody(branches[i] as Node[], elements[i])
+          }
+
+          const wrapper = createWrapper(elements[0], [createLiteral("\n"), conditionalNode as unknown as Node, createLiteral("\n")])
+          parentArray[conditionalIndex] = wrapper
+          didMutate = true
+        }
+      }
+    }
+
+    return didMutate ? result : null
   }
 }