@herb-tools/linter 0.8.10 → 0.9.1

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)

package/docs/rules/html-require-closing-tags.md

@@ -0,0 +1,142 @@
+# Linter Rule: Require explicit closing tags
+
+**Rule:** `html-require-closing-tags`
+
+## Description
+
+Disallow the omission of optional closing tags for HTML elements where the closing tag is technically optional according to the HTML specification. This rule flags elements that have an `HTMLOmittedCloseTagNode` as their close tag.
+
+## Rationale
+
+While HTML allows certain closing tags to be omitted (implicitly closed by sibling elements or parent closing), explicit closing tags improve code readability and maintainability. They make the document structure clear at a glance and reduce ambiguity about where elements end.
+
+Explicit closing tags also:
+
+- Make templates easier to understand for developers unfamiliar with HTML's implicit closing rules
+- Reduce potential for subtle bugs when refactoring or moving code
+- Improve consistency across the codebase
+- Make diffs cleaner when adding content to elements
+
+## Elements with Optional Closing Tags
+
+This rule would flag elements that have omitted closing tags:
+
+- `<li>` - list items
+- `<dt>`, `<dd>` - definition list terms and descriptions
+- `<p>` - paragraphs
+- `<option>`, `<optgroup>` - select options and groups
+- `<thead>`, `<tbody>`, `<tfoot>` - table sections
+- `<tr>` - table rows
+- `<td>`, `<th>` - table cells
+- `<colgroup>` - table column groups
+- `<rt>`, `<rp>` - ruby annotations
+
+## Examples
+
+### ✅ Good
+
+Explicit closing tags:
+
+```erb
+<ul>
+  <li>Item 1</li>
+  <li>Item 2</li>
+  <li>Item 3</li>
+</ul>
+```
+
+```erb
+<dl>
+  <dt>Term 1</dt>
+  <dd>Definition 1</dd>
+  <dt>Term 2</dt>
+  <dd>Definition 2</dd>
+</dl>
+```
+
+```erb
+<table>
+  <thead>
+    <tr>
+      <th>Header 1</th>
+      <th>Header 2</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Cell 1</td>
+      <td>Cell 2</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+```erb
+<select>
+  <option>Option 1</option>
+  <option>Option 2</option>
+  <option>Option 3</option>
+</select>
+```
+
+```erb
+<div>
+  <p>Paragraph 1</p>
+  <p>Paragraph 2</p>
+</div>
+```
+
+### 🚫 Bad
+
+Omitted closing tags (implicitly closed):
+
+```erb
+<ul>
+  <li>Item 1
+  <li>Item 2
+  <li>Item 3
+</ul>
+```
+
+```erb
+<dl>
+  <dt>Term 1
+  <dd>Definition 1
+  <dt>Term 2
+  <dd>Definition 2
+</dl>
+```
+
+```erb
+<table>
+  <thead>
+    <tr>
+      <th>Header 1
+      <th>Header 2
+  <tbody>
+    <tr>
+      <td>Cell 1
+      <td>Cell 2
+</table>
+```
+
+```erb
+<select>
+  <option>Option 1
+  <option>Option 2
+  <option>Option 3
+</select>
+```
+
+```erb
+<div>
+  <p>Paragraph 1
+  <p>Paragraph 2
+</div>
+```
+
+## References
+
+- [HTML Spec: Optional Tags](https://html.spec.whatwg.org/multipage/syntax.html#optional-tags)
+- [HTML Spec: Tag Omission](https://html.spec.whatwg.org/multipage/dom.html#concept-element-tag-omission)
+- [CSS-Tricks: Fighting the Space Between Inline Block Elements](https://css-tricks.com/fighting-the-space-between-inline-block-elements/)

package/docs/rules/parser-no-errors.md

@@ -39,15 +39,16 @@ By surfacing parser errors through the linter, developers can catch these critic
 ### 🚫 Bad
 
 ```html
-<!-- Mismatched closing tag -->
 <h2>Welcome to our site</h3>
+```
 
-<!-- Unclosed element -->
+```html
 <div>
   <p>This paragraph is never closed
 </div>
+```
 
-<!-- Missing opening tag -->
+```html
 Some content
 </div>
 ```
@@ -63,20 +64,6 @@ Some content
 <img src="image.jpg" alt="Description"></img>
 ```
 
-## Error Types
-
-This rule reports various parser error types:
-
-- **`UNCLOSED_ELEMENT_ERROR`**: Elements that are opened but never closed
-- **`MISSING_CLOSING_TAG_ERROR`**: Opening tags without matching closing tags
-- **`MISSING_OPENING_TAG_ERROR`**: Closing tags without matching opening tags
-- **`TAG_NAMES_MISMATCH_ERROR`**: Opening and closing tags with different names
-- **`QUOTES_MISMATCH_ERROR`**: Mismatched quotation marks in attributes
-- **`VOID_ELEMENT_CLOSING_TAG_ERROR`**: Void elements (like `<img>`) with closing tags
-- **`RUBY_PARSE_ERROR`**: Invalid Ruby syntax within ERB tags
-- **`UNEXPECTED_TOKEN_ERROR`**: Unexpected tokens during parsing
-- **`UNEXPECTED_ERROR`**: Other unexpected parsing issues
-
 ## References
 
 * [HTML Living Standard - Parsing](https://html.spec.whatwg.org/multipage/parsing.html)

package/docs/rules/turbo-permanent-require-id.md

@@ -0,0 +1,41 @@
+# Linter Rule: Require `id` attribute on elements with `data-turbo-permanent`
+
+**Rule:** `turbo-permanent-require-id`
+
+## Description
+
+Ensure that all HTML elements with the `data-turbo-permanent` attribute also have an `id` attribute. Without an `id`, Turbo can't track the element across page changes and the permanent behavior won't work as expected.
+
+## Rationale
+
+Turbo's `data-turbo-permanent` attribute marks an element to be persisted across page navigations. Turbo uses the element's `id` to match it between the current page and the new page. If no `id` is present, Turbo has no way to identify and preserve the element, so the `data-turbo-permanent` attribute has no effect.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<div id="player" data-turbo-permanent>
+  <!-- This element will persist across page navigations -->
+</div>
+
+<audio id="background-music" data-turbo-permanent>
+  <source src="/music.mp3" type="audio/mpeg">
+</audio>
+```
+
+### 🚫 Bad
+
+```erb
+<div data-turbo-permanent>
+  <!-- Missing id: Turbo can't track this element -->
+</div>
+
+<audio data-turbo-permanent>
+  <source src="/music.mp3" type="audio/mpeg">
+</audio>
+```
+
+## References
+
+- [Turbo Handbook: Persisting Elements Across Page Loads](https://turbo.hotwired.dev/handbook/building#persisting-elements-across-page-loads)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herb-tools/linter",
-  "version": "0.8.10",
+  "version": "0.9.1",
   "description": "HTML+ERB linter for validating HTML structure and enforcing best practices",
   "license": "MIT",
   "homepage": "https://herb-tools.dev",
@@ -33,9 +33,10 @@
       "default": "./dist/index.js"
     },
     "./cli": {
-      "types": "./dist/types/src/cli.d.ts",
-      "require": "./dist/src/cli.js",
-      "default": "./dist/src/cli.js"
+      "types": "./dist/types/cli.d.ts",
+      "import": "./dist/cli.js",
+      "require": "./dist/cli.js",
+      "default": "./dist/cli.js"
     },
     "./loader": {
       "types": "./dist/types/loader.d.ts",
@@ -45,12 +46,12 @@
     }
   },
   "dependencies": {
-    "@herb-tools/config": "0.8.10",
-    "@herb-tools/core": "0.8.10",
-    "@herb-tools/highlighter": "0.8.10",
-    "@herb-tools/node-wasm": "0.8.10",
-    "@herb-tools/printer": "0.8.10",
-    "@herb-tools/rewriter": "0.8.10",
+    "@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/cli/argument-parser.ts

@@ -1,5 +1,6 @@
 import dedent from "dedent"
 
+import { availableParallelism } from "node:os"
 import { parseArgs } from "util"
 import { Herb } from "@herb-tools/node-wasm"
 
@@ -27,6 +28,7 @@ export interface ParsedArguments {
   init: boolean
   loadCustomRules: boolean
   failLevel?: DiagnosticSeverity
+  jobs: number
 }
 
 export class ArgumentParser {
@@ -53,6 +55,8 @@ export class ArgumentParser {
       --github                      enable GitHub Actions annotations (combines with --format)
       --no-github                   disable GitHub Actions annotations (even in GitHub Actions environment)
       --no-custom-rules             disable loading custom rules from project (custom rules are loaded by default from .herb/rules/**/*.{mjs,js})
+      -j, --jobs <n>                number of parallel workers for linting files [default: auto]
+                                    use "auto" to detect based on available CPU cores
       --theme                       syntax highlighting theme (${THEME_NAMES.join("|")}) or path to custom theme file [default: ${DEFAULT_THEME}]
       --no-color                    disable colored output
       --no-timing                   hide timing information
@@ -83,7 +87,8 @@ export class ArgumentParser {
         "no-timing": { type: "boolean" },
         "no-wrap-lines": { type: "boolean" },
         "truncate-lines": { type: "boolean" },
-        "no-custom-rules": { type: "boolean" }
+        "no-custom-rules": { type: "boolean" },
+        jobs: { type: "string", short: "j" }
       },
       allowPositionals: true
     })
@@ -163,7 +168,20 @@ export class ArgumentParser {
       }
     }
 
-    return { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, fixUnsafe, ignoreDisableComments, force, init, loadCustomRules, failLevel }
+    let jobs = availableParallelism()
+
+    if (values.jobs && values.jobs !== "auto") {
+      const parsed = parseInt(values.jobs, 10)
+
+      if (isNaN(parsed) || parsed < 1) {
+        console.error(`Error: Invalid --jobs value "${values.jobs}". Must be a positive integer or "auto".`)
+        process.exit(1)
+      }
+
+      jobs = parsed
+    }
+
+    return { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, fixUnsafe, ignoreDisableComments, force, init, loadCustomRules, failLevel, jobs }
   }
 
   private getFilePatterns(positionals: string[]): string[] {