@herb-tools/linter 0.7.5 → 0.8.0

package/docs/rules/erb-no-extra-newline.md

@@ -0,0 +1,74 @@
+# Linter Rule: Disallow extra newlines
+
+**Rule:** `erb-no-extra-newline`
+
+## Description
+
+Disallow more than two consecutive blank lines in ERB templates. This rule enforces a maximum of two blank lines between content to maintain consistent vertical spacing throughout your templates.
+
+## Rationale
+
+Excessive blank lines can make templates harder to read and maintain. While some vertical spacing improves readability by visually separating logical sections, too many blank lines create unnecessary whitespace that:
+
+* Makes it harder to see related code on the same screen
+* Creates inconsistent visual rhythm in the codebase
+* Can accidentally accumulate through merge conflicts or refactoring
+* Provides no additional clarity beyond what 1-2 blank lines already achieve
+
+Limiting to two consecutive blank lines strikes a balance between allowing clear section separation while maintaining code density and readability.
+
+## Examples
+
+### ✅ Good
+
+```html
+line 1
+
+line 3
+
+<div>
+  <h1>Title</h1>
+</div>
+
+<div>
+  <h1>Section 1</h1>
+
+  <p>Content here</p>
+</div>
+
+<div>
+  <h1>Section 1</h1>
+
+
+  <h1>Section 2</h1>
+</div>
+```
+
+### 🚫 Bad
+
+```erb
+line 1
+
+
+
+line 3
+
+<div>
+  <h1>Title</h1>
+
+
+
+  <p>Content</p>
+</div>
+
+<%= user.name %>
+
+
+
+
+<%= user.email %>
+```
+
+## References
+
+- [Inspiration: ERB Lint `ExtraNewline` rule](https://github.com/Shopify/erb_lint/blob/main/README.md)

package/docs/rules/erb-no-extra-whitespace-inside-tags.md

@@ -0,0 +1,39 @@
+# Linter Rule: Avoid extra whitespace inside ERB tags
+
+**Rule:** `erb-no-extra-whitespace-inside-tags`
+
+## Description
+
+This rule disallows **multiple consecutive spaces** immediately inside ERB tags (`<%`, `<%=`) or before the closing delimiter (`%>`). It ensures that ERB code is consistently and cleanly formatted, with exactly one space after the opening tag and one space before the closing tag (when appropriate).
+
+## Rationale
+
+Excess whitespace inside ERB tags can lead to inconsistent formatting and untidy templates. By enforcing a consistent amount of whitespace inside ERB tags, this rule improves code readability, aligns with the formatter and style guide expectations, and avoids unnecessary visual noise.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<%= output %>
+
+<% if condition %>
+  True
+<% end %>
+```
+
+### 🚫 Bad
+
+```erb
+<%=  output %>
+
+<%= output  %>
+
+<%  if condition  %>
+  True
+<% end %>
+```
+
+## References
+
+\-

package/docs/rules/{erb-requires-trailing-newline.md → erb-require-trailing-newline.md}

@@ -1,6 +1,6 @@
 # Linter Rule: Enforce trailing newline
 
-**Rule:** `erb-requires-trailing-newline`
+**Rule:** `erb-require-trailing-newline`
 
 ## Description
 

package/docs/rules/erb-right-trim.md

@@ -4,15 +4,13 @@
 
 ## Description
 
-This rule enforces the use of `-%>` for right-trimming ERB output tags (like `<%= %>`) instead of `=%>`. It also warns when right-trimming syntax (`-%>` or `=%>`) is used on non-output ERB tags (like `<% %>`, `<% if %>`, etc.) where it has no effect.
+This rule enforces the use of `-%>` for right-trimming ERB output tags (like `<%= %>`) instead of `=%>`.
 
 ## Rationale
 
-While `=%>` can be used for right-trimming whitespace in some ERB engines (like Erubi), it is an obscure and not well-defined syntax that lacks consistent support across most ERB implementations. The `-%>` syntax is the standard, well-documented approach for right-trimming that is universally supported and consistent with left-trimming syntax (`<%-`).
+While `=%>` can be used for right-trimming whitespace in some ERB engines (like Erubi), it is an obscure and not well-defined syntax that lacks consistent support across most ERB implementations.
 
-Additionally, right-trimming syntax only has an effect on ERB output tags (`<%=` and `<%==`). Using `-%>` or `=%>` on non-output ERB tags (control flow like `<% if %>`, `<% each %>`, etc.) has no effect and is misleading.
-
-Using `-%>` for output tags ensures compatibility across different ERB engines, improves code clarity, and aligns with established Rails and ERB conventions.
+The `-%>` syntax is the standard, well-documented approach for right-trimming that is universally supported and consistent with left-trimming syntax (`<%-`). Using `-%>` ensures compatibility across different ERB engines, improves code clarity, and aligns with established Rails and ERB conventions.
 
 ## Examples
 
@@ -21,7 +19,7 @@ Using `-%>` for output tags ensures compatibility across different ERB engines,
 ```erb
 <%= title -%>
 
-<% if true %>
+<% if condition? %>
   <h1>Content</h1>
 <% end %>
 
@@ -39,10 +37,7 @@ Using `-%>` for output tags ensures compatibility across different ERB engines,
 <% title =%>
 
 
-<% title -%>
-
-
-<% if true -%>
+<% if true =%>
   <h1>Content</h1>
 <% end %>
 

package/docs/rules/herb-disable-comment-malformed.md

@@ -0,0 +1,45 @@
+# Linter Rule: Detect malformed `herb:disable` comments
+
+**Rule:** `herb-disable-comment-malformed`
+
+## Description
+
+Detects malformed `<%# herb:disable ... %>` comments that have syntax errors like trailing commas, leading commas, consecutive commas, or missing spaces after `herb:disable`.
+
+## Rationale
+
+Malformed `<%# herb:disable ... %>` comments can fail to parse correctly, leading to unexpected behavior where rules aren't actually disabled. This rule catches common syntax errors to ensure your disable comments work as intended.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase %>
+
+<DIV class='value'>test</DIV> <%# herb:disable html-tag-name-lowercase, html-attribute-double-quotes %>
+
+<DIV class='value'>test</DIV> <%# herb:disable html-tag-name-lowercase , html-attribute-double-quotes %>
+
+<DIV>test</DIV> <%# herb:disable all %>
+```
+
+### 🚫 Bad
+
+```erb
+<div>test</div> <%# herb:disable html-tag-name-lowercase, %>
+
+<div>test</div> <%# herb:disable , html-tag-name-lowercase %>
+
+<div>test</div> <%# herb:disable html-tag-name-lowercase,, html-attribute-double-quotes %>
+
+<div>test</div> <%# herb:disable html-tag-name-lowercase,, %>
+
+<DIV>test</DIV> <%# herb:disableall %>
+
+<DIV>test</DIV> <%# herb:disablehtml-tag-name-lowercase %>
+```
+
+## References
+
+\-

package/docs/rules/herb-disable-comment-missing-rules.md

@@ -0,0 +1,60 @@
+# Linter Rule: Require rule names in `herb:disable` comments
+
+**Rule:** `herb-disable-comment-missing-rules`
+
+## Description
+
+Requires that `<%# herb:disable %>` comments specify either `all` or at least one specific rule name.
+
+## Rationale
+
+A `<%# herb:disable %>` comment without any rule names serves no purpose and likely indicates an incomplete edit or mistake. The developer either:
+
+- Forgot to specify which rules to disable
+- Intended to use `herb:disable all` but forgot to add `all`
+- Started typing a comment but didn't finish
+
+This rule ensures all `<%# herb:disable %>` comments are complete and functional.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<DIV class='value'>test</DIV> <%# herb:disable all %>
+
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase %>
+
+<DIV class='value'>test</DIV> <%# herb:disable html-tag-name-lowercase, html-attribute-double-quotes %>
+```
+
+### 🚫 Bad
+
+```erb
+<div>test</div> <%# herb:disable %>
+
+<div>test</div> <%# herb:disable   %>
+```
+
+## Fix
+
+Add either `all` or specific rule names:
+
+**Option 1:** Disable all rules
+```erb
+<DIV>test</DIV> <%# herb:disable all %>
+```
+
+**Option 2:** Disable specific rules
+```erb
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase %>
+```
+
+**Option 3:** Remove the comment if it's not needed
+```erb
+<div>test</div>
+```
+
+## References
+
+\-

package/docs/rules/herb-disable-comment-no-duplicate-rules.md

@@ -0,0 +1,49 @@
+# Linter Rule: Disallow duplicate rule names in `herb:disable` comments
+
+**Rule:** `herb-disable-comment-no-duplicate-rules`
+
+## Description
+
+Prevents listing the same rule name multiple times in a `<%# herb:disable ... %>` comment.
+
+## Rationale
+
+Listing a rule name more than once in a `<%# herb:disable ... %>` comment is unnecessary and likely indicates a copy-paste error or mistake. Each rule only needs to be mentioned once to be disabled.
+
+This rule helps keep disable comments clean and prevents confusion about which rules are being disabled.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<DIV class='value'>test</DIV> <%# herb:disable html-tag-name-lowercase, html-attribute-double-quotes %>
+
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase %>
+
+<DIV>test</DIV> <%# herb:disable all %>
+```
+
+### 🚫 Bad
+
+```erb
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase, html-tag-name-lowercase %>
+
+<DIV class='value'>test</DIV> <%# herb:disable html-attribute-double-quotes, html-tag-name-lowercase, html-tag-name-lowercase %>
+
+<DIV class='value'>test</DIV> <%# herb:disable html-tag-name-lowercase, html-tag-name-lowercase, html-attribute-double-quotes, html-attribute-double-quotes %>
+
+<DIV>test</DIV> <%# herb:disable all, all %>
+```
+
+## Fix
+
+Remove the duplicate rule names, keeping only one instance of each:
+
+```erb
+<DIV class='value'>test</DIV> <%# herb:disable html-tag-name-lowercase, html-attribute-double-quotes %>
+```
+
+## References
+
+\-

package/docs/rules/herb-disable-comment-no-redundant-all.md

@@ -0,0 +1,53 @@
+# Linter Rule: Disallow redundant use of `all` in `herb:disable` comments
+
+**Rule:** `herb-disable-comment-no-redundant-all`
+
+## Description
+
+Prevents using `all` together with specific rule names in `<%# herb:disable ... %>` comments, as this is redundant.
+
+## Rationale
+
+When you use `all` in a `<%# herb:disable ... %>` comment, it disables every linter rule for that line. Adding specific rule names alongside `all` is redundant because `all` already covers them.
+
+This rule helps maintain clean, concise disable comments by ensuring you either use `herb:disable all` by itself to disable all rules or lists only the specific rules you want to disable.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<DIV>test</DIV> <%# herb:disable all %>
+
+<DIV class='value'>test</DIV> <%# herb:disable html-tag-name-lowercase, html-attribute-double-quotes %>
+
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase %>
+```
+
+### 🚫 Bad
+
+```erb
+<DIV>test</DIV> <%# herb:disable all, html-tag-name-lowercase %>
+
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase, all, html-attribute-double-quotes %>
+
+<DIV>test</DIV> <%# herb:disable all, all %>
+```
+
+## Fix
+
+Remove either the `all` keyword or the specific rule names:
+
+**Option 1:** Keep only `all`
+```erb
+<DIV class='value'>test</DIV> <%# herb:disable all %>
+```
+
+**Option 2:** Keep only specific rules
+```erb
+<DIV class='value'>test</DIV> <%# herb:disable html-tag-name-lowercase, html-attribute-double-quotes %>
+```
+
+## References
+
+\-

package/docs/rules/herb-disable-comment-unnecessary.md

@@ -0,0 +1,44 @@
+# Linter Rule: Detect unnecessary `herb:disable` comments
+
+**Rule:** `herb-disable-comment-unnecessary`
+
+## Description
+
+Warns when a `<%# herb:disable ... %>` comment doesn't actually suppress any linter offenses on that line, indicating it's unnecessary and should be removed.
+
+## Rationale
+
+Unnecessary `<%# herb:disable ... %>` comments create noise in the codebase and can mislead developers about which rules are being suppressed. These comments often remain after the code has been refactored and no longer triggers the offense.
+
+Removing unnecessary disable comments keeps the codebase clean and ensures that suppression comments accurately reflect actual rule violations being intentionally ignored.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase %>
+
+<DIV id='test-1'>content</DIV> <%# herb:disable html-tag-name-lowercase, html-attribute-double-quotes %>
+
+<DIV id='test-2'>content</DIV> <%# herb:disable all %>
+```
+
+### 🚫 Bad
+
+```erb
+<div>test</div> <%# herb:disable html-tag-name-lowercase %>
+
+<div id="test">content</div> <%# herb:disable html-tag-name-lowercase, html-attribute-double-quotes %>
+
+<div id="test-1">content</div> <%# herb:disable all %>
+
+<DIV id='test-2'>content</DIV> <%# herb:disable html-tag-name-lowercase, html-attribute-double-quotes, html-no-empty-headings %>
+
+<div>test</div> <%# herb:disableall %>
+```
+
+
+## References
+
+\-

package/docs/rules/herb-disable-comment-valid-rule-name.md

@@ -0,0 +1,41 @@
+# Linter Rule: Validate rule names in `herb:disable` comments
+
+**Rule:** `herb-disable-comment-valid-rule-name`
+
+## Description
+
+Ensures that all rule names specified in `<%# herb:disable ... %>` comments are valid and exist in the linter. This catches typos, references to non-existent rules and missing comma between rule names.
+
+## Rationale
+
+Using invalid or misspelled rule names in `<%# herb:disable ... %>` comments can lead to confusion and unexpected behavior. The comment won't disable anything if the rule name doesn't exist, leaving developers wondering why linter warnings persist.
+
+By validating rule names, this rule helps catch typos early, identify removed or renamed rule and provide helpful suggestions for similar rule names using fuzzy matching.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase %>
+
+<DIV class='value'>test</DIV> <%# herb:disable html-tag-name-lowercase, html-attribute-double-quotes %>
+
+<DIV>test</DIV> <%# herb:disable all %>
+```
+
+### 🚫 Bad
+
+```erb
+<div>test</div> <%# herb:disable this-rule-doesnt-exist %>
+
+<div>test</div> <%# herb:disable html-tag-lowercase %>
+
+<DIV>test</DIV> <%# herb:disable html-tag-name-lowercase, invalid-rule-name %>
+
+<div>test</div> <%# herb:disable html-tag-name-lowercase html-attribute-double-quotes %>
+```
+
+## References
+
+\-

package/docs/rules/html-aria-attribute-must-be-valid.md

@@ -22,20 +22,17 @@ Validating against a known list ensures you're using correct and effective ARIA
 
 ```html
 <div role="button" aria-pressed="false">Toggle</div>
-<input type="text" aria-label="Search" />
+<input type="text" aria-label="Search" autocomplete="off">
 <span role="heading" aria-level="2">Title</span>
 ```
 
 ### 🚫 Bad
 
 ```html
-<!-- typo -->
 <div role="button" aria-presed="false">Toggle</div>
 
-<!-- typo -->
-<input type="text" aria-lable="Search" />
+<input type="text" aria-lable="Search" autocomplete="off">
 
-<!-- invalid -->
 <span aria-size="large" role="heading" aria-level="2">Title</span>
 ```
 

package/docs/rules/html-aria-label-is-well-formatted.md

@@ -16,7 +16,7 @@ The `aria-label` attribute provides an accessible name for elements that will be
 
 ```erb
 <button aria-label="Close dialog">X</button>
-<input aria-label="Search products" type="search">
+<input aria-label="Search products" type="search" autocomplete="off">
 <button aria-label="Page 2 of 10">2</button>
 ```
 

package/docs/rules/html-attribute-double-quotes.md

@@ -17,7 +17,7 @@ Double quotes are the most widely used and expected style for HTML attributes. C
 ### ✅ Good
 
 ```html
-<input type="text">
+<input type="text" autocomplete="off">
 
 <a href="/profile">Profile</a>
 
@@ -31,7 +31,7 @@ Double quotes are the most widely used and expected style for HTML attributes. C
 ### 🚫 Bad
 
 ```html
-<input type='text'>
+<input type='text' autocomplete="off">
 
 <a href='/profile'>Profile</a>
 

package/docs/rules/html-attribute-equals-spacing.md

@@ -17,7 +17,7 @@ Extra whitespace around the `=` in HTML attribute assignments is unnecessary, in
 ```erb
 <div class="container"></div>
 <img src="/logo.png" alt="Logo">
-<input type="text" value="<%= @value %>">
+<input type="text" value="<%= @value %>" autocomplete="off">
 ```
 
 ### 🚫 Bad
@@ -27,7 +27,7 @@ Extra whitespace around the `=` in HTML attribute assignments is unnecessary, in
 
 <img src= "/logo.png" alt="Logo">
 
-<input  type  =  "text">
+<input  type  =  "text" autocomplete="off">
 ```
 
 ## References

package/docs/rules/html-attribute-values-require-quotes.md

@@ -23,7 +23,7 @@ Additionally, always quoting is the common convention in most HTML formatters, l
 ```html
 <div id="hello"></div>
 
-<input type="text">
+<input type="text" autocomplete="off">
 
 <a href="/profile">Profile</a>
 ```
@@ -33,9 +33,9 @@ Additionally, always quoting is the common convention in most HTML formatters, l
 ```html
 <div id=hello></div>
 
-<input type=text>
+<input type=text autocomplete="off">
 
-<a href=/profile></a>
+<a href=profile></a>
 ```
 
 ## References

package/docs/rules/html-avoid-both-disabled-and-aria-disabled.md

@@ -19,7 +19,7 @@ Elements that support the native `disabled` attribute include: `button`, `fields
 ```erb
 <!-- Use only the native disabled attribute -->
 <button disabled>Submit</button>
-<input type="text" disabled>
+<input type="text" autocomplete="off" disabled>
 
 <!-- Use only aria-disabled for custom elements -->
 <div role="button" aria-disabled="true">Custom Button</div>
@@ -34,7 +34,7 @@ Elements that support the native `disabled` attribute include: `button`, `fields
 <!-- Both disabled and aria-disabled -->
 <button disabled aria-disabled="true">Submit</button>
 
-<input type="text" disabled aria-disabled="true">
+<input type="text" autocomplete="off" disabled aria-disabled="true">
 
 <select disabled aria-disabled="true">
   <option>Option 1</option>

package/docs/rules/html-body-only-elements.md

@@ -0,0 +1,99 @@
+# Linter Rule: Require content elements inside `<body>`
+
+**Rule:** `html-body-only-elements`
+
+## Description
+
+Enforce that specific HTML elements are only placed within the `<body>` tag.
+
+## Rationale
+
+According to the HTML specification, certain elements are meant to contain content and should only appear within the `<body>` section of an HTML document. Placing content-bearing or interactive elements in the `<head>` section or outside the HTML structure can lead to:
+
+- Unpredictable browser rendering behavior
+- Accessibility issues for screen readers and assistive technologies
+- SEO problems as search engines may not properly index misplaced content
+- Validation errors and non-compliant HTML
+
+This rule enforces proper document structure by ensuring semantic and content elements are correctly placed within the `<body>` element.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<html>
+  <head>
+    <title>Page Title</title>
+    <meta charset="utf-8">
+  </head>
+
+  <body>
+    <header>
+      <h1>Welcome</h1>
+      <nav>
+        <ul>
+          <li>Home</li>
+        </ul>
+      </nav>
+    </header>
+
+    <main>
+      <article>
+        <section>
+          <p>This is valid content.</p>
+          <table>
+            <tr><td>Data</td></tr>
+          </table>
+        </section>
+      </article>
+      <aside>
+        <form>
+          <input type="text" autocomplete="on">
+        </form>
+      </aside>
+    </main>
+
+    <footer>
+      <h2>Footer</h2>
+    </footer>
+  </body>
+</html>
+```
+
+### 🚫 Bad
+
+```erb
+<html>
+  <head>
+    <title>Page Title</title>
+    <h1>Welcome</h1>
+
+    <p>This should not be here.</p>
+
+  </head>
+
+  <body>
+    <main>Valid content</main>
+  </body>
+</html>
+```
+
+```erb
+<html>
+  <head>
+    <nav>Navigation</nav>
+
+    <form>Form</form>
+
+  </head>
+
+  <body>
+  </body>
+</html>
+```
+
+## References
+
+- [HTML Living Standard - The `body` element](https://html.spec.whatwg.org/multipage/sections.html#the-body-element)
+- [MDN: HTML `document` structure](https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/Document_and_website_structure)