@herb-tools/linter 0.4.0

package/docs/rules/erb-require-whitespace-inside-tags.md

@@ -0,0 +1,43 @@
+# Linter Rule: Enforce whitespace around ERB tag contents
+
+**Rule:** `erb-require-whitespace-inside-tags`
+
+## Description
+
+Require a single space before and after Ruby code inside ERB tags (`<% ... %>` and `<%= ... %>`). This improves readability and keeps ERB code visually consistent with Ruby style guides.
+
+## Rationale
+
+Without spacing, ERB tags can become hard to read and visually cramped:
+
+* difficult to scan: `<%=user.name%>`
+* harder to read: `<%if admin%><%end%>`
+
+By enforcing consistent spacing around Ruby expressions, templates become easier to read, review, and maintain. It also aligns with standard Ruby formatting conventions, where spaces are used around control keywords and operators.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<%= user.name %>
+
+<% if admin %>
+  Hello, admin.
+<% end %>
+```
+
+### 🚫 Bad
+
+```erb
+<%=user.name %>
+
+<%if admin %>
+
+  Hello, admin.
+<% end%>
+```
+
+## References
+
+\-

package/docs/rules/html-anchor-require-href.md

@@ -0,0 +1,32 @@
+# Linter Rule: Require `href` attribute on `<a>` tags
+
+**Rule:** `html-anchor-require-href`
+
+## Description
+
+Disallow the use of anchor tags without anhref attribute in HTML templates. Use if you want to perform an action without having the user navigated to a new URL.
+
+## Rationale
+
+Anchor tags without href are unfocusable if user is using keyboard navigation, or is unseen by screen readers.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<a href="https://alink.com">I'm a real link</a>
+```
+
+### 🚫 Bad
+
+```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

package/docs/rules/html-aria-role-heading-requires-level.md

@@ -0,0 +1,34 @@
+# Linter Rule: ARIA role with heading requires level
+
+**Rule:** `html-aria-role-heading-requires-level`
+
+## Description
+
+Ensure that any element with `role="heading"` also has a valid `aria-level` attribute. The `aria-level` defines the heading level (1–6) and is required for assistive technologies to properly interpret the document structure.
+
+## Rationale
+
+In HTML, semantic heading elements like `<h1>` through `<h6>` implicitly define their level. When using `role="heading"` on non-semantic elements (e.g., `<div>`, `<span>`), the level must be explicitly declared using `aria-level`, otherwise screen readers and accessibility tools may not understand the document hierarchy.
+
+## Examples
+
+### ✅ Good
+
+```html
+<div role="heading" aria-level="2">Section Title</div>
+
+<span role="heading" aria-level="1">Main Title</span>
+```
+
+### 🚫 Bad
+
+```html
+<div role="heading">Section Title</div>
+
+<span role="heading">Main Title</span>
+```
+
+## References
+
+* [ARIA: `heading` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role)
+* [ARIA: `aria-level` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level)

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

@@ -0,0 +1,43 @@
+# Linter Rule: Prefer double quotes for HTML Attribute values
+
+**Rule:** `html-attribute-double-quotes`
+
+## Description
+
+Prefer using double quotes (`"`) around HTML attribute values instead of single quotes (`'`).
+
+**Exception:** Single quotes are allowed when the attribute value contains double quotes, as this avoids the need for escaping.
+
+## Rationale
+
+Double quotes are the most widely used and expected style for HTML attributes. Consistent use of double quotes improves readability, reduces visual noise when mixing with embedded Ruby (which often uses single quotes), and avoids escaping conflicts when embedding attribute values that contain single quotes.
+
+## Examples
+
+### ✅ Good
+
+```html
+<input type="text">
+
+<a href="/profile">Profile</a>
+
+<div data-action="click->dropdown#toggle"></div>
+
+<!-- Exception: Single quotes allowed when value contains double quotes -->
+<div id='"hello"' title='Say "Hello" to the world'></div>
+```
+
+
+### 🚫 Bad
+
+```html
+<input type='text'>
+
+<a href='/profile'>Profile</a>
+
+<div data-action='click->dropdown#toggle'></div>
+```
+
+## References
+
+* [HTML Living Standard - Attributes](https://html.spec.whatwg.org/multipage/syntax.html#attributes-2)

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

@@ -0,0 +1,43 @@
+# Linter Rule: Always quote attribute values
+
+**Rule:** `html-attribute-values-require-quotes`
+
+## Description
+
+Always wrap HTML attribute values in quotes, even when they are technically optional according to the HTML specification.
+
+## Rationale
+
+While some attribute values can be written without quotes if they don't contain spaces or special characters, omitting quotes makes the code harder to read, more error-prone, and inconsistent. Always quoting attribute values ensures:
+
+- consistent appearance across all attributes,
+- fewer surprises when attribute values contain special characters,
+- easier editing and maintenance.
+
+Additionally, always quoting is the common convention in most HTML formatters, linters, and developer tools.
+
+## Examples
+
+### ✅ Good
+
+```html
+<div id="hello"></div>
+
+<input type="text">
+
+<a href="/profile">Profile</a>
+```
+
+### 🚫 Bad
+
+```html
+<div id=hello></div>
+
+<input type=text>
+
+<a href=/profile></a>
+```
+
+## References
+
+* [HTML Living Standard - Attributes](https://html.spec.whatwg.org/multipage/syntax.html#attributes-2)

package/docs/rules/html-boolean-attributes-no-value.md

@@ -0,0 +1,39 @@
+# Linter Rule: Omit values for boolean attributes
+
+**Rule:** `html-boolean-attributes-no-value`
+
+## Description
+
+Omit attribute values for boolean HTML attributes. For boolean attributes, their presence alone represents `true`, and their absence represents `false`. There is no need to assign a value or use quotes.
+
+## Rationale
+
+Using the canonical form for boolean attributes improves readability, keeps HTML concise, and avoids unnecessary characters. This also matches HTML specifications and the output of many HTML formatters.
+
+For example, instead of writing `disabled="disabled"` or `disabled="true"`, simply write `disabled`.
+
+## Examples
+
+### ✅ Good
+
+```html
+<input type="checkbox" checked>
+
+<button disabled>Submit</button>
+
+<select multiple>
+```
+
+### 🚫 Bad
+
+```html
+<input type="checkbox" checked="checked">
+
+<button disabled="true">Submit</button>
+
+<select multiple="multiple">
+```
+
+## References
+
+* [HTML Living Standard - Boolean Attributes](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#boolean-attributes)

package/docs/rules/html-img-require-alt.md

@@ -0,0 +1,44 @@
+# Linter Rule: Require `alt` attribute on `<img>` tags
+
+**Rule:** `html-img-require-alt`
+
+## Description
+
+Enforce that all `<img>` elements include an `alt` attribute.
+
+## Rationale
+
+The `alt` attribute provides alternative text for images, which is essential for accessibility (screen readers, assistive technologies), SEO, and proper fallback behavior when images fail to load. Even if the image is purely decorative, an empty `alt=""` should be provided to indicate that the image should be ignored by assistive technologies.
+
+Omitting the `alt` attribute entirely leads to poor accessibility and can negatively affect user experience.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<img src="/logo.png" alt="Company logo">
+
+<img src="/avatar.jpg" alt="<%= user.name %>'s profile picture">
+
+<img src="/divider.png" alt="">
+
+<%= image_tag image_path("logo.png"), alt: "Company logo" %>
+```
+
+### 🚫 Bad
+
+```erb
+<img src="/logo.png">
+
+<img src="/avatar.jpg" alt> <!-- TODO -->
+
+<img src="/divider.png" alt=> <!-- TODO -->
+
+<%= 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)

package/docs/rules/html-no-block-inside-inline.md

@@ -0,0 +1,66 @@
+# Linter Rule: No block elements inside inline elements
+
+**Rule:** `html-no-block-inside-inline`
+
+## Description
+
+Prevent block-level elements from being placed inside inline elements.
+
+## Rationale
+
+Placing block-level elements (like `<div>`, `<p>`, `<section>`) inside inline elements (like `<span>`, `<a>`, `<strong>`) violates HTML content model rules and may lead to unpredictable rendering behavior across browsers.
+
+This practice can cause:
+- Invalid HTML that fails validation
+- Inconsistent rendering across different browsers
+- Layout issues and unexpected visual results
+- Accessibility problems with screen readers
+
+## Examples
+
+
+### ✅ Good
+
+```erb
+<span>
+  Hello <strong>World</strong>
+</span>
+
+<div>
+  <p>Paragraph inside div (valid)</p>
+</div>
+
+<a href="#">
+  <img src="icon.png" alt="Icon">
+  <span>Link text</span>
+</a>
+```
+
+### 🚫 Bad
+
+```erb
+<span>
+  <div>Invalid block inside span</div>
+</span>
+
+<span>
+  <p>Paragraph inside span (invalid)</p>
+</span>
+
+<a href="#">
+  <div class="card">
+    <h2>Card title</h2>
+    <p>Card content</p>
+  </div>
+</a>
+
+<strong>
+  <section>Section inside strong</section>
+</strong>
+```
+
+## References
+
+* [HTML Living Standard - Content models](https://html.spec.whatwg.org/multipage/dom.html#content-models)
+* [MDN - Block-level elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements)
+* [MDN - Inline elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements)

package/docs/rules/html-no-duplicate-attributes.md

@@ -0,0 +1,35 @@
+# Linter Rule: Disallow duplicate attributes on the same tag
+
+**Rule:** `html-no-duplicate-attributes`
+
+## Description
+
+Disallow having multiple attributes with the same name on a single HTML tag.
+
+## Rationale
+
+Duplicate attributes on an HTML element are invalid and may lead to undefined or unexpected behavior across browsers. When duplicate attributes exist, the browser typically uses the last occurrence, but this behavior is not guaranteed to be consistent across all engines or future specifications.
+
+Catching duplicates early helps prevent subtle bugs, improves code correctness, and avoids accidental overwrites of attribute values.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<input type="text" name="username" id="user-id">
+
+<button type="submit" disabled>Submit</button>
+```
+
+### 🚫 Bad
+
+```erb
+<input type="text" type="password" name="username">
+
+<button type="submit" type="button" disabled>Submit</button>
+```
+
+## References
+
+* [HTML Living Standard - Attributes](https://html.spec.whatwg.org/multipage/syntax.html#attributes-2)

package/docs/rules/html-no-empty-headings.md

@@ -0,0 +1,78 @@
+# Linter Rule: Disallow empty headings
+
+**Rule:** `html-no-empty-headings`
+
+## Description
+
+Disallow headings (`h1`, `h2`, etc.) with no accessible text content.
+
+## Rationale
+
+Headings relay the structure of a webpage and provide a meaningful, hierarchical order of its content. If headings are empty or its text contents are inaccessible, this could confuse users or prevent them accessing sections of interest.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<h*>Heading Content</h*>
+```
+
+```erb
+<h*><span>Text</span><h*>
+```
+
+```erb
+<div role="heading" aria-level="1">Heading Content</div>
+```
+
+```erb
+<h* aria-hidden="true">Heading Content</h*>
+```
+
+```erb
+<h* hidden>Heading Content</h*>
+```
+
+### 🚫 Bad
+
+```erb
+<h1></h1>
+```
+
+```erb
+<h2></h2>
+```
+
+```erb
+<h3></h3>
+```
+
+```erb
+<h4></h4>
+```
+
+```erb
+<h5></h5>
+```
+
+```erb
+<h6></h6>
+```
+
+```erb
+<div role="heading" aria-level="1"></div>
+```
+
+```erb
+<h1><span aria-hidden="true">Inaccessible text</span></h1>
+```
+
+## References
+
+- [`<h1>`–`<h6>`: The HTML Section Heading elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements)
+- [ARIA: `heading` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role)
+- [ARIA: `aria-hidden` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden)
+- [ARIA: `aria-level` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level)
+
+Inspired by [ember-template-lint](https://github.com/ember-template-lint/ember-template-lint/blob/master/docs/rule/no-empty-headings.md)

package/docs/rules/html-no-nested-links.md

@@ -0,0 +1,44 @@
+# Linter Rule: Disallow nested links
+
+**Rule:** `html-no-nested-links`
+
+## Description
+
+Disallow placing one `<a>` element inside another `<a>` element. Links must not contain other links as descendants.
+
+## Rationale
+
+The HTML specification forbids nesting one anchor (`<a>`) inside another. Nested links result in invalid HTML, unpredictable click behavior, and inconsistent rendering across browsers.
+
+Browsers may attempt error recovery when encountering nested links, but behavior varies and cannot be relied upon. This rule ensures strictly valid document structure and avoids subtle user interaction issues.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<a href="/products">View products</a>
+<a href="/about">About us</a>
+
+<%= link_to "View products", products_path %>
+<%= link_to about_path do %>
+  About us
+<% end %>
+```
+
+### 🚫 Bad
+
+```erb
+<a href="/products">
+  View <a href="/special-offer">special offer</a>
+</a>
+
+<%= link_to "Products", products_path do %>
+  <%= link_to "Special offer", offer_path %> <!-- TODO -->
+<% end %>
+```
+
+## References
+
+* [HTML Living Standard - The a element](https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element)
+* [Rails `link_to` helper](https://api.rubyonrails.org/classes/ActionView/Helpers/UrlHelper.html#method-i-link_to)

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

@@ -0,0 +1,44 @@
+# Linter Rule: Enforce lowercase tag names
+
+**Rule:** `html-tag-name-lowercase`
+
+## Description
+
+Enforce that all HTML tag names are written in lowercase.
+
+## Rationale
+
+HTML is case-insensitive for tag names, but lowercase is the widely accepted convention for writing HTML. Consistent lowercase tag names improve readability, maintain consistency across codebases, and align with the output of most HTML formatters and validators.
+
+Writing tags in uppercase or mixed case can lead to inconsistent code and unnecessary diffs during reviews and merges.
+
+## Examples
+
+
+### ✅ Good
+
+```erb
+<div class="container"></div>
+
+<input type="text" name="username" />
+
+<span>Label</span>
+
+<%= content_tag(:div, "Hello world!") %>
+```
+
+### 🚫 Bad
+
+```erb
+<DIV class="container"></DIV>
+
+<Input type="text" name="username" />
+
+<Span>Label</Span>
+
+<%= content_tag(:DiV, "Hello world!") %> <!-- TODO -->
+```
+
+## References
+
+* [HTML Living Standard - Tag Syntax](https://html.spec.whatwg.org/multipage/syntax.html#syntax-tags)

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@herb-tools/linter",
+  "version": "0.4.0",
+  "description": "HTML+ERB linter for validating HTML structure and enforcing best practices",
+  "license": "MIT",
+  "homepage": "https://herb-tools.dev",
+  "bugs": "https://github.com/marcoroth/herb/issues/new?title=Package%20%60@herb-tools/linter%60:%20",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marcoroth/herb.git",
+    "directory": "javascript/packages/linter"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "bin": {
+    "herb-lint": "./bin/herb-lint"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "yarn clean && tsc -b && rollup -c",
+    "watch": "tsc -b -w",
+    "test": "vitest run",
+    "prepublishOnly": "yarn clean && yarn build && yarn test"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@herb-tools/core": "0.4.0",
+    "@herb-tools/highlighter": "0.4.0",
+    "@herb-tools/node-wasm": "0.4.0",
+    "glob": "^11.0.3"
+  },
+  "files": [
+    "package.json",
+    "README.md",
+    "docs/",
+    "src/",
+    "bin/",
+    "dist/"
+  ]
+}