@herb-tools/linter 0.4.3 → 0.6.0

package/docs/rules/html-iframe-has-title.md

@@ -0,0 +1,43 @@
+# Linter Rule: `iframe` elements must have a `title` attribute
+
+**Rule:** `html-iframe-has-title`
+
+## Description
+
+Ensure that all `iframe` elements have a meaningful `title` attribute that describes the content of the frame. The title should not be empty or contain only whitespace.
+
+## Rationale
+
+The `title` attribute on `iframe` elements provides essential context for screen reader users about what content the frame contains. Without this information, users of assistive technology cannot understand the purpose or content of the embedded frame, creating significant accessibility barriers.
+
+::: tip Note
+`<iframe>`'s with `aria-hidden="true"` are exempt from this requirement as they are hidden from assistive technologies.
+:::
+
+## Examples
+
+### ✅ Good
+
+```erb
+<iframe src="https://youtube.com/embed/123" title="Product demonstration video"></iframe>
+<iframe src="https://example.com" title="Example website content"></iframe>
+
+<!-- Hidden from screen readers -->
+<iframe aria-hidden="true"></iframe>
+```
+
+### 🚫 Bad
+
+```erb
+<iframe src="https://example.com"></iframe>
+
+<iframe src="https://example.com" title=""></iframe>
+
+<iframe src="https://example.com" title="   "></iframe>
+```
+
+## References
+
+- [HTML: `iframe` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe)
+- [HTML: `title` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title)
+- [erblint-github: GitHub::Accessibility::IframeHasTitle](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/iframe-has-title.md)

package/docs/rules/html-navigation-has-label.md

@@ -0,0 +1,61 @@
+# Linter Rule: Navigation landmarks must have accessible labels
+
+**Rule:** `html-navigation-has-label`
+
+## Description
+
+Ensure that navigation landmarks have a unique accessible name via `aria-label` or `aria-labelledby` attributes. This applies to both `<nav>` elements and elements with `role="navigation"`.
+
+## Rationale
+
+Navigation landmarks help users of assistive technology quickly understand and navigate to different sections of a website. When multiple navigation landmarks exist on a page, each needs a unique accessible name so users can distinguish between them (e.g., "Main navigation", "Footer links", "Breadcrumb navigation").
+
+## Examples
+
+### ✅ Good
+
+```erb
+<nav aria-label="Main navigation">
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+</nav>
+
+<nav aria-labelledby="breadcrumb-title">
+  <h2 id="breadcrumb-title">Breadcrumb</h2>
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li>Current Page</li>
+  </ol>
+</nav>
+
+<div role="navigation" aria-label="Footer links">
+  <a href="/privacy">Privacy</a>
+  <a href="/terms">Terms</a>
+</div>
+```
+
+### 🚫 Bad
+
+```erb
+<nav>
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+</nav>
+
+<div role="navigation">
+  <a href="/privacy">Privacy</a>
+  <a href="/terms">Terms</a>
+</div>
+```
+
+## References
+
+- [ARIA: `navigation` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/navigation_role)
+- [HTML: `nav` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav)
+- [ARIA: `aria-label` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label)
+- [ARIA: `aria-labelledby` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby)
+- [erblint-github: GitHub::Accessibility::NavigationHasLabel](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/navigation-has-label.md)

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

@@ -0,0 +1,54 @@
+# Linter Rule: Focusable elements should not have `aria-hidden="true"`
+
+**Rule:** `html-no-aria-hidden-on-focusable`
+
+## Description
+
+Prevent using `aria-hidden="true"` on elements that can receive keyboard focus. When an element is focusable but hidden from screen readers, it creates a confusing experience where keyboard users can tab to "invisible" elements.
+
+## Rationale
+
+Elements with `aria-hidden="true"` are completely hidden from assistive technologies, but they remain visible and interactive for mouse and keyboard users. If a focusable element is hidden from screen readers, keyboard-only users (especially those using screen readers) will encounter focused elements that provide no accessible information, creating a broken user experience.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<button>Submit</button>
+<a href="/link">Link</a>
+<input type="text">
+<textarea></textarea>
+
+<div aria-hidden="true">Decorative content</div>
+<span aria-hidden="true">🎉</span>
+
+<button tabindex="-1" aria-hidden="true">Hidden button</button>
+```
+
+### 🚫 Bad
+
+```erb
+<button aria-hidden="true">Submit</button>
+
+<a href="/link" aria-hidden="true">Link</a>
+
+<input type="text" aria-hidden="true">
+
+<textarea aria-hidden="true"></textarea>
+
+<select aria-hidden="true">
+  <option>Option</option>
+</select>
+
+<div tabindex="0" aria-hidden="true">Focusable div</div>
+
+<a href="/link" aria-hidden="true">Hidden link</a>
+```
+
+## References
+
+- [ARIA: `aria-hidden` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden)
+- [HTML: `tabindex` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex)
+- [WebAIM: Keyboard Accessibility](https://webaim.org/techniques/keyboard/)
+- [erblint-github: GitHub::Accessibility::NoAriaHiddenOnFocusable](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/no-aria-hidden-on-focusable.md)

package/docs/rules/html-no-positive-tab-index.md

@@ -0,0 +1,55 @@
+# Linter Rule: Avoid positive `tabindex` values
+
+**Rule:** `html-no-positive-tab-index`
+
+## Description
+
+Prevent using positive values for the `tabindex` attribute. Only `tabindex="0"` (to make elements focusable) and `tabindex="-1"` (to remove from tab order) should be used.
+
+## Rationale
+
+Positive `tabindex` values create a custom tab order that can be confusing and unpredictable for keyboard users. They override the natural document flow and can cause elements to be focused in an unexpected sequence. This breaks the logical reading order and creates usability issues, especially for screen reader users who rely on a predictable navigation pattern.
+
+The recommended approach is to structure your HTML in the correct tab order and use `tabindex="0"` only when you need to make non-interactive elements focusable, or `tabindex="-1"` to remove elements from the tab sequence while keeping them programmatically focusable.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<!-- Natural tab order (no tabindex needed) -->
+<button>First</button>
+<button>Second</button>
+<button>Third</button>
+
+<!-- Make non-interactive element focusable -->
+<div tabindex="0" role="button">Custom button</div>
+
+<!-- Remove from tab order but keep programmatically focusable -->
+<button tabindex="-1">Skip this in tab order</button>
+
+<!-- Zero tabindex to ensure focusability -->
+<span tabindex="0" role="button">Focusable span</span>
+```
+
+### 🚫 Bad
+
+```erb
+<button tabindex="3">Third in tab order</button>
+
+<button tabindex="1">First in tab order</button>
+
+<button tabindex="2">Second in tab order</button>
+
+
+<input tabindex="5" type="text">
+
+<button tabindex="10">Submit</button>
+```
+
+## References
+
+- [HTML: `tabindex` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex)
+- [WebAIM: Keyboard Accessibility](https://webaim.org/techniques/keyboard/tabindex)
+- [WCAG: Focus Order](https://www.w3.org/WAI/WCAG21/Understanding/focus-order.html)
+- [erblint-github: GitHub::Accessibility::NoPositiveTabIndex](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/no-positive-tab-index.md)

package/docs/rules/html-no-self-closing.md

@@ -0,0 +1,65 @@
+# Linter Rule: Disallow self-closing tag syntax for void elements
+
+**Rule:** `html-no-self-closing`
+
+## Description
+
+Disallow self-closing syntax (`<tag />`) in HTML for all elements.
+
+In HTML5, the trailing slash in a start tag is obsolete and has no effect.
+Non-void elements require explicit end tags, and void elements are
+self-contained without the slash.
+
+## Rationale
+
+Self-closing syntax is an XHTML artifact. In HTML:
+
+- On **non-void** elements, it’s a parse error and produces invalid markup
+  (`<div />` is invalid).
+- On **void elements**, the slash is ignored and unnecessary (`<input />` is
+  equivalent to `<input>`).
+
+Removing the slash ensures HTML5-compliant, cleaner markup and avoids mixing
+XHTML and HTML styles.
+
+## Examples
+
+### ✅ Good
+
+```html
+<span></span>
+<div></div>
+<section></section>
+<custom-element></custom-element>
+
+<img src="/logo.png" alt="Logo">
+<input type="text">
+<br>
+<hr>
+```
+
+### 🚫 Bad
+
+```html
+<span />
+
+<div />
+
+<section />
+
+<custom-element />
+
+<img src="/logo.png" alt="Logo" />
+
+<input type="text" />
+
+<br />
+
+<hr />
+```
+
+## References
+
+- [HTML Living Standard: Void Elements](https://html.spec.whatwg.org/multipage/syntax.html#void-elements)
+- [MDN: Void element](https://developer.mozilla.org/en-US/docs/Glossary/Void_element)
+- [erb_lint: SelfClosingTag](https://github.com/Shopify/erb_lint#selfclosingtag)

package/docs/rules/html-no-title-attribute.md

@@ -0,0 +1,69 @@
+# Linter Rule: Avoid using the `title` attribute
+
+**Rule:** `html-no-title-attribute`
+
+## Description
+
+Discourage the use of the `title` attribute on most HTML elements, as it provides poor accessibility and user experience. The `title` attribute is only accessible via mouse hover and is not reliably exposed to screen readers or keyboard users.
+
+## Rationale
+
+The `title` attribute has several accessibility problems:
+- It's only visible on mouse hover, making it inaccessible to keyboard and touch users
+- Screen readers don't consistently announce title attributes
+- Mobile devices don't show title tooltips
+- The visual presentation is inconsistent across browsers and operating systems
+
+Instead of relying on `title`, use visible text, `aria-label`, `aria-describedby`, or other accessible alternatives.
+
+::: warning Exceptions
+This rule allows `title` on `<iframe>` and `<link>` elements where it serves specific accessibility purposes.
+:::
+
+## Examples
+
+### ✅ Good
+
+```erb
+<!-- Use visible text instead of title -->
+<button>Save document</button>
+<span class="help-text">Click to save your changes</span>
+
+<!-- Use aria-label for accessible names -->
+<button aria-label="Close dialog">×</button>
+
+<!-- Use aria-describedby for additional context -->
+<input type="password" aria-describedby="pwd-help">
+<div id="pwd-help">Password must be at least 8 characters</div>
+
+<!-- Exceptions: title allowed on iframe and links -->
+<iframe src="https://example.com" title="Example website content"></iframe>
+<link href="default.css" rel="stylesheet" title="Default Style">
+```
+
+### 🚫 Bad
+
+```erb
+<!-- Don't use title for essential information -->
+<button title="Save your changes">Save</button>
+
+<div title="This is important information">Content</div>
+
+<span title="Required field">*</span>
+
+<!-- Don't use title on form elements -->
+<input type="text" title="Enter your name">
+
+<select title="Choose your country">
+  <option>US</option>
+  <option>CA</option>
+</select>
+```
+
+## References
+
+- [HTML: `title` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title)
+- [WebAIM: Accessible Forms](https://webaim.org/techniques/forms/)
+- [ARIA: `aria-label` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label)
+- [ARIA: `aria-describedby` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby)
+- [erblint-github: GitHub::Accessibility::NoTitleAttribute](https://github.com/github/erblint-github/blob/main/docs/rules/accessibility/no-title-attribute.md)

package/docs/rules/html-tag-name-lowercase.md

@@ -12,15 +12,28 @@ HTML is case-insensitive for tag names, but lowercase is the widely accepted con
 
 Writing tags in uppercase or mixed case can lead to inconsistent code and unnecessary diffs during reviews and merges.
 
-## Examples
+### Notes
+
+::: tip XML Documents
+This rule is automatically disabled for XML documents and XML+ERB templates. XML allows uppercase tag names and follows different naming conventions than HTML.
+
+The rule will be disabled when:
+- The document contains an XML declaration (`<?xml version="1.0" ?>`)
+- The file extension is `.xml` or `.xml.erb`
+:::
 
+::: tip SVG Elements
+This rule does not apply to child elements within `<svg>` tags, as SVG element names are case-sensitive and may require specific capitalization (e.g., `linearGradient`, `clipPath`). However, the rule still applies to the `<svg>` element itself.
+:::
+
+## Examples
 
 ### ✅ Good
 
 ```erb
 <div class="container"></div>
 
-<input type="text" name="username" />
+<input type="text" name="username">
 
 <span>Label</span>
 
@@ -32,7 +45,7 @@ Writing tags in uppercase or mixed case can lead to inconsistent code and unnece
 ```erb
 <DIV class="container"></DIV>
 
-<Input type="text" name="username" />
+<Input type="text" name="username">
 
 <Span>Label</Span>
 

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

@@ -0,0 +1,84 @@
+# Linter Rule: Disallow parser errors in HTML+ERB documents
+
+**Rule:** `parser-no-errors`
+
+## Description
+
+Report parser errors as linting offenses. This rule surfaces syntax errors, malformed HTML, and other parsing issues that prevent the document from being correctly parsed.
+
+## Rationale
+
+Parser errors indicate fundamental structural problems in HTML+ERB documents that can lead to unexpected rendering behavior, accessibility issues, and maintenance difficulties. These errors should be fixed before addressing other linting concerns as they represent invalid markup that browsers may interpret inconsistently.
+
+By surfacing parser errors through the linter, developers can catch these critical issues when running lint checks directly, without needing to switch to the language server or other tools.
+
+## Examples
+
+### ✅ Good
+
+```html
+<h2>Welcome to our site</h2>
+<p>This is a paragraph with proper structure.</p>
+
+<div class="container">
+  <img src="image.jpg" alt="Description">
+</div>
+```
+
+```erb
+<h2><%= @page.title %></h2>
+<p><%= @page.description %></p>
+
+<% if user_signed_in? %>
+  <div class="user-section">
+    <%= current_user.name %>
+  </div>
+<% end %>
+```
+
+### 🚫 Bad
+
+```html
+<!-- Mismatched closing tag -->
+<h2>Welcome to our site</h3>
+
+<!-- Unclosed element -->
+<div>
+  <p>This paragraph is never closed
+</div>
+
+<!-- Missing opening tag -->
+Some content
+</div>
+```
+
+```erb
+<!-- Invalid Ruby syntax in ERB -->
+<%= 1 + %>
+
+<!-- Mismatched quotes -->
+<div class="container'>Content</div>
+
+<!-- Void element with closing tag -->
+<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)
+* [W3C HTML Validator](https://validator.w3.org/)
+* [ERB Template Guide](https://guides.rubyonrails.org/layouts_and_rendering.html)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herb-tools/linter",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "description": "HTML+ERB linter for validating HTML structure and enforcing best practices",
   "license": "MIT",
   "homepage": "https://herb-tools.dev",
@@ -33,9 +33,9 @@
     }
   },
   "dependencies": {
-    "@herb-tools/core": "0.4.3",
-    "@herb-tools/highlighter": "0.4.3",
-    "@herb-tools/node-wasm": "0.4.3",
+    "@herb-tools/core": "0.6.0",
+    "@herb-tools/highlighter": "0.6.0",
+    "@herb-tools/node-wasm": "0.6.0",
     "glob": "^11.0.3"
   },
   "files": [

package/src/cli/argument-parser.ts

@@ -11,9 +11,11 @@ import type { ThemeInput } from "@herb-tools/highlighter"
 
 import { name, version } from "../../package.json"
 
+export type FormatOption = "simple" | "detailed" | "json" | "github"
+
 export interface ParsedArguments {
   pattern: string
-  formatOption: 'simple' | 'detailed'
+  formatOption: FormatOption
   showTiming: boolean
   theme: ThemeInput
   wrapLines: boolean
@@ -32,9 +34,11 @@ export class ArgumentParser {
     Options:
       -h, --help       show help
       -v, --version    show version
-      --format         output format (simple|detailed) [default: detailed]
+      --format         output format (simple|detailed|json|github) [default: detailed]
       --simple         use simple output format (shortcut for --format simple)
-      --theme          syntax highlighting theme (${THEME_NAMES.join('|')}) or path to custom theme file [default: ${DEFAULT_THEME}]
+      --json           use JSON output format (shortcut for --format json)
+      --github         use GitHub Actions output format (shortcut for --format github)
+      --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
       --no-wrap-lines  disable line wrapping
@@ -45,15 +49,17 @@ export class ArgumentParser {
     const { values, positionals } = parseArgs({
       args: argv.slice(2),
       options: {
-        help: { type: 'boolean', short: 'h' },
-        version: { type: 'boolean', short: 'v' },
-        format: { type: 'string' },
-        simple: { type: 'boolean' },
-        theme: { type: 'string' },
-        'no-color': { type: 'boolean' },
-        'no-timing': { type: 'boolean' },
-        'no-wrap-lines': { type: 'boolean' },
-        'truncate-lines': { type: 'boolean' }
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+        format: { type: "string" },
+        simple: { type: "boolean" },
+        json: { type: "boolean" },
+        github: { type: "boolean" },
+        theme: { type: "string" },
+        "no-color": { type: "boolean" },
+        "no-timing": { type: "boolean" },
+        "no-wrap-lines": { type: "boolean" },
+        "truncate-lines": { type: "boolean" }
       },
       allowPositionals: true
     })
@@ -69,8 +75,8 @@ export class ArgumentParser {
       process.exit(0)
     }
 
-    let formatOption: 'simple' | 'detailed' = 'detailed'
-    if (values.format && (values.format === "detailed" || values.format === "simple")) {
+    let formatOption: FormatOption = "detailed"
+    if (values.format && (values.format === "detailed" || values.format === "simple" || values.format === "json" || values.format === "github")) {
       formatOption = values.format
     }
 
@@ -78,21 +84,29 @@ export class ArgumentParser {
       formatOption = "simple"
     }
 
-    if (values['no-color']) {
+    if (values.json) {
+      formatOption = "json"
+    }
+
+    if (values.github) {
+      formatOption = "github"
+    }
+
+    if (values["no-color"]) {
       process.env.NO_COLOR = "1"
     }
 
-    const showTiming = !values['no-timing']
+    const showTiming = !values["no-timing"]
 
-    let wrapLines = !values['no-wrap-lines']
+    let wrapLines = !values["no-wrap-lines"]
     let truncateLines = false
 
-    if (values['truncate-lines']) {
+    if (values["truncate-lines"]) {
       truncateLines = true
       wrapLines = false
     }
 
-    if (!values['no-wrap-lines'] && values['truncate-lines']) {
+    if (!values["no-wrap-lines"] && values["truncate-lines"]) {
       console.error("Error: Line wrapping and --truncate-lines cannot be used together. Use --no-wrap-lines with --truncate-lines.")
       process.exit(1)
     }
@@ -100,11 +114,6 @@ export class ArgumentParser {
     const theme = values.theme || DEFAULT_THEME
     const pattern = this.getFilePattern(positionals)
 
-    if (positionals.length === 0) {
-      console.error("Please specify input file.")
-      process.exit(1)
-    }
-
     return { pattern, formatOption, showTiming, theme, wrapLines, truncateLines }
   }