@herb-tools/linter 0.4.0 → 0.4.2

package/dist/types/src/rules/rule-utils.d.ts

@@ -56,6 +56,17 @@ export declare const HTML_INLINE_ELEMENTS: Set<string>;
 export declare const HTML_BLOCK_ELEMENTS: Set<string>;
 export declare const HTML_BOOLEAN_ATTRIBUTES: Set<string>;
 export declare const HEADING_TAGS: Set<string>;
+/**
+ * SVG elements that use camelCase naming
+ */
+export declare const SVG_CAMEL_CASE_ELEMENTS: Set<string>;
+/**
+ * Mapping from lowercase SVG element names to their correct camelCase versions
+ * Generated dynamically from SVG_CAMEL_CASE_ELEMENTS
+ */
+export declare const SVG_LOWERCASE_TO_CAMELCASE: Map<string, string>;
+export declare const VALID_ARIA_ROLES: Set<string>;
+export declare const ARIA_ATTRIBUTES: Set<string>;
 /**
  * Checks if an element is inline
  */

package/dist/types/src/rules/svg-tag-name-capitalization.d.ts

@@ -0,0 +1,6 @@
+import type { Rule, LintOffense } from "../types.js";
+import type { Node } from "@herb-tools/core";
+export declare class SVGTagNameCapitalizationRule implements Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}

package/docs/rules/README.md

@@ -7,15 +7,20 @@ This page contains documentation for all Herb Linter rules.
 - [`erb-no-empty-tags`](./erb-no-empty-tags.md) - Disallow empty ERB tags
 - [`erb-no-output-control-flow`](./erb-no-output-control-flow.md) - Prevents outputting control flow blocks
 - [`erb-require-whitespace-inside-tags`](./erb-require-whitespace-inside-tags.md) - Requires whitespace around erb tags
+- [`html-anchor-require-href`](./html-anchor-require-href.md) - Requires an href attribute on anchor tags
+- [`html-aria-attribute-must-be-valid`](./html-aria-attribute-must-be-valid.md) - Disallow invalid or unknown `aria-*` attributes.
 - [`html-aria-role-heading-requires-level`](./html-aria-role-heading-requires-level.md) - Requires `aria-level` when supplying a `role`
+- [`html-aria-role-must-be-valid`](./html-aria-role-must-be-valid.md) - The `role` attribute must have a valid WAI-ARIA Role.
 - [`html-attribute-double-quotes`](./html-attribute-double-quotes.md) - Enforces double quotes for attribute values
 - [`html-attribute-values-require-quotes`](./html-attribute-values-require-quotes.md) - Requires quotes around attribute values
 - [`html-boolean-attributes-no-value`](./html-boolean-attributes-no-value.md) - Prevents values on boolean attributes
 - [`html-img-require-alt`](./html-img-require-alt.md) - Requires alt attributes on img tags
 - [`html-no-block-inside-inline`](./html-no-block-inside-inline.md) - Prevents block-level elements inside inline elements
+- [`html-no-duplicate-ids`](./html-no-duplicate-ids.md) - Prevents duplicate IDs within a document
 - [`html-no-duplicate-attributes`](./html-no-duplicate-attributes.md) - Prevents duplicate attributes on HTML elements
 - [`html-no-nested-links`](./html-no-nested-links.md) - Prevents nested anchor tags
 - [`html-tag-name-lowercase`](./html-tag-name-lowercase.md) - Enforces lowercase tag names in HTML
+- [`svg-tag-name-capitalization`](./svg-tag-name-capitalization.md) - Enforces proper camelCase capitalization for SVG elements
 
 ## Contributing
 

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

@@ -0,0 +1,45 @@
+# Linter Rule: Disallow invalid or unknown `aria-*` attributes.
+
+**Rule:** `html-aria-attribute-must-be-valid`
+
+## Description
+
+Disallow unknown or invalid `aria-*` attributes. Only attributes defined in the WAI-ARIA specification should be used. This rule helps catch typos (e.g. `aria-lable`), misuse, or outdated attribute names that won't be interpreted by assistive technologies.
+
+## Rationale
+
+ARIA attributes are powerful accessibility tools, but **only if used correctly**. Mistyped or unsupported attributes:
+
+- Are silently ignored by browsers and screen readers
+- Fail to communicate intent
+- Give a false sense of accessibility
+
+Validating against a known list ensures you're using correct and effective ARIA patterns.
+
+## Examples
+
+### ✅ Good
+
+```html
+<div role="button" aria-pressed="false">Toggle</div>
+<input type="text" aria-label="Search" />
+<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" />
+
+<!-- invalid -->
+<span aria-size="large" role="heading" aria-level="2">Title</span>
+```
+
+## References
+
+- [ARIA states and properties (attributes)](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes)
+- [NPM Package: `aria-attributes`](https://github.com/wooorm/aria-attributes)

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

@@ -0,0 +1,45 @@
+# Linter Rule: Disallow invalid values for the `role` attribute
+
+**Rule:** `html-aria-role-must-be-valid`
+
+## Description
+
+Disallow invalid or unknown values for the `role` attribute. The `role` attribute must match one of the recognized ARIA role values as defined by the [WAI-ARIA specification](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles).
+
+## Rationale
+
+ARIA `role` attributes are used to define the purpose of an element to assistive technologies. Using invalid, misspelled, or non-standard roles results in:
+
+* Screen readers ignoring the role
+* Broken accessibility semantics
+* False sense of correctness
+
+Validating against the official list of ARIA roles prevents silent accessibility failures.
+
+## Examples
+
+### ✅ Good
+
+```html
+<div role="button">Click me</div>
+<nav role="navigation">...</nav>
+<section role="region">...</section>
+```
+
+### 🚫 Bad
+
+```html
+<!-- typo -->
+<div role="buton">Click me</div>
+
+<!-- not a valid role -->
+<nav role="nav">...</nav>
+
+<!-- not in the ARIA spec -->
+<section role="header">...</section>
+```
+
+## References
+
+* [ARIA 1.2 Specification - Roles](https://www.w3.org/TR/wai-aria/#roles)
+* [MDN: ARIA roles](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles)

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

@@ -0,0 +1,49 @@
+# Linter Rule: Disallow duplicate IDs in the same document
+
+**Rule:** `html-no-duplicate-ids`
+
+## Description
+
+Ensure that `id` attribute is unique within a document.
+
+## Rationale
+
+Duplicate IDs in an HTML document can lead to unexpected behavior, especially when using JavaScript or CSS that relies on unique identifiers. Browsers may not handle duplicate IDs consistently, which can cause issues with element selection, styling, and event handling.
+
+## Examples
+
+### ✅ Good
+
+```html
+<div id="header">Header</div>
+<div id="main-content">Main Content</div>
+<div id="footer">Footer</div>
+```
+
+```erb
+<div id="<%= dom_id("header") %>">Header</div>
+<div id="<%= dom_id("main_content") %>">Main Content</div>
+<div id="<%= dom_id("footer") %>">Footer</div>
+```
+
+### 🚫 Bad
+
+```html
+<div id="header">Header</div>
+
+<div id="header">Duplicate Header</div>
+
+<div id="footer">Footer</div>
+```
+
+```erb
+<div id="<%= dom_id("header") %>">Header</div>
+
+<div id="<%= dom_id("header") %>">Duplicate Header</div>
+
+<div id="<%= dom_id("footer") %>">Footer</div>
+```
+
+## References
+* [W3 org - The id attribute](https://www.w3.org/TR/2011/WD-html5-20110525/elements.html#the-id-attribute)
+* [Rails `ActionView::RecordIdentifier#dom_id`](https://api.rubyonrails.org/classes/ActionView/RecordIdentifier.html#method-i-dom_id)

package/docs/rules/svg-tag-name-capitalization.md

@@ -0,0 +1,57 @@
+# Linter Rule: SVG tag name capitalization
+
+**Rule:** `svg-tag-name-capitalization`
+
+## Description
+
+Enforces proper camelCase capitalization for SVG element names within SVG contexts.
+
+## Rationale
+
+SVG elements use camelCase naming conventions (e.g., `linearGradient`, `clipPath`, `feGaussianBlur`) rather than the lowercase conventions used in HTML. This rule ensures that SVG elements within `<svg>` tags use the correct capitalization for proper rendering and standards compliance.
+
+This rule only applies to elements within SVG contexts and does not check the `<svg>` tag itself (that's handled by the `html-tag-name-lowercase` rule).
+
+## Examples
+
+### ✅ Good
+
+```html
+<svg>
+  <linearGradient id="grad1">
+    <stop offset="0%" stop-color="rgb(255,255,0)" />
+  </linearGradient>
+</svg>
+```
+
+```html
+<svg>
+  <clipPath id="clip">
+    <rect width="100" height="100" />
+  </clipPath>
+  <feGaussianBlur stdDeviation="5" />
+</svg>
+```
+
+### 🚫 Bad
+
+```html
+<svg>
+  <lineargradient id="grad1">
+    <stop offset="0%" stop-color="rgb(255,255,0)" />
+  </lineargradient>
+</svg>
+```
+
+```html
+<svg>
+  <CLIPPATH id="clip">
+    <rect width="100" height="100" />
+  </CLIPPATH>
+</svg>
+```
+
+## References
+
+* [SVG Element Reference](https://developer.mozilla.org/en-US/docs/Web/SVG/Element)
+* [SVG Naming Conventions](https://www.w3.org/TR/SVG2/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herb-tools/linter",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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.0",
-    "@herb-tools/highlighter": "0.4.0",
-    "@herb-tools/node-wasm": "0.4.0",
+    "@herb-tools/core": "0.4.2",
+    "@herb-tools/highlighter": "0.4.2",
+    "@herb-tools/node-wasm": "0.4.2",
     "glob": "^11.0.3"
   },
   "files": [

package/src/default-rules.ts

@@ -4,30 +4,38 @@ import { ERBNoEmptyTagsRule } from "./rules/erb-no-empty-tags.js"
 import { ERBNoOutputControlFlowRule } from "./rules/erb-no-output-control-flow.js"
 import { ERBRequireWhitespaceRule } from "./rules/erb-require-whitespace-inside-tags.js"
 import { HTMLAnchorRequireHrefRule } from "./rules/html-anchor-require-href.js"
+import { HTMLAriaAttributeMustBeValid } from "./rules/html-aria-attribute-must-be-valid.js"
 import { HTMLAriaRoleHeadingRequiresLevelRule } from "./rules/html-aria-role-heading-requires-level.js"
+import { HTMLAriaRoleMustBeValidRule } from "./rules/html-aria-role-must-be-valid.js"
 import { HTMLAttributeDoubleQuotesRule } from "./rules/html-attribute-double-quotes.js"
 import { HTMLAttributeValuesRequireQuotesRule } from "./rules/html-attribute-values-require-quotes.js"
 import { HTMLBooleanAttributesNoValueRule } from "./rules/html-boolean-attributes-no-value.js"
 import { HTMLImgRequireAltRule } from "./rules/html-img-require-alt.js"
-import { HTMLNoBlockInsideInlineRule } from "./rules/html-no-block-inside-inline.js"
+// import { HTMLNoBlockInsideInlineRule } from "./rules/html-no-block-inside-inline.js"
 import { HTMLNoDuplicateAttributesRule } from "./rules/html-no-duplicate-attributes.js"
+import { HTMLNoDuplicateIdsRule } from "./rules/html-no-duplicate-ids.js"
 import { HTMLNoEmptyHeadingsRule } from "./rules/html-no-empty-headings.js"
 import { HTMLNoNestedLinksRule } from "./rules/html-no-nested-links.js"
 import { HTMLTagNameLowercaseRule } from "./rules/html-tag-name-lowercase.js"
+import { SVGTagNameCapitalizationRule } from "./rules/svg-tag-name-capitalization.js"
 
 export const defaultRules: RuleClass[] = [
   ERBNoEmptyTagsRule,
   ERBNoOutputControlFlowRule,
   ERBRequireWhitespaceRule,
   HTMLAnchorRequireHrefRule,
+  HTMLAriaAttributeMustBeValid,
   HTMLAriaRoleHeadingRequiresLevelRule,
+  HTMLAriaRoleMustBeValidRule,
   HTMLAttributeDoubleQuotesRule,
   HTMLAttributeValuesRequireQuotesRule,
   HTMLBooleanAttributesNoValueRule,
   HTMLImgRequireAltRule,
-  HTMLNoBlockInsideInlineRule,
+  // HTMLNoBlockInsideInlineRule,
   HTMLNoDuplicateAttributesRule,
+  HTMLNoDuplicateIdsRule,
   HTMLNoEmptyHeadingsRule,
   HTMLNoNestedLinksRule,
   HTMLTagNameLowercaseRule,
+  SVGTagNameCapitalizationRule,
 ]

package/src/rules/erb-require-whitespace-inside-tags.ts

@@ -24,14 +24,43 @@ class RequireWhitespaceInsideTags extends BaseRuleVisitor {
 
     const value = content.value
 
-    this.checkOpenTagWhitespace(openTag, value)
-    this.checkCloseTagWhitespace(closeTag, value)
+    if (openTag.value === "<%#") {
+      this.checkCommentTagWhitespace(openTag, closeTag, value)
+    } else {
+      this.checkOpenTagWhitespace(openTag, value)
+      this.checkCloseTagWhitespace(closeTag, value)
+    }
+  }
+
+  private checkCommentTagWhitespace(openTag: Token, closeTag: Token, content: string): void {
+    if (!content.startsWith(" ") && !content.startsWith("\n") && !content.startsWith("=")) {
+      this.addOffense(
+        `Add whitespace after \`${openTag.value}\`.`,
+        openTag.location,
+        "error"
+      )
+    } else if (content.startsWith("=") && content.length > 1 && !content[1].match(/\s/)) {
+      this.addOffense(
+        `Add whitespace after \`<%#=\`.`,
+        openTag.location,
+        "error"
+      )
+    }
+
+    if (!content.endsWith(" ") && !content.endsWith("\n")) {
+      this.addOffense(
+        `Add whitespace before \`${closeTag.value}\`.`,
+        closeTag.location,
+        "error"
+      )
+    }
   }
 
   private checkOpenTagWhitespace(openTag: Token, content:string):void {
     if (content.startsWith(" ") || content.startsWith("\n")) {
       return
     }
+
     this.addOffense(
       `Add whitespace after \`${openTag.value}\`.`,
       openTag.location,
@@ -43,6 +72,7 @@ class RequireWhitespaceInsideTags extends BaseRuleVisitor {
     if (content.endsWith(" ") || content.endsWith("\n")) {
       return
     }
+
     this.addOffense(
       `Add whitespace before \`${closeTag.value}\`.`,
       closeTag.location,
@@ -53,6 +83,7 @@ class RequireWhitespaceInsideTags extends BaseRuleVisitor {
 
 export class ERBRequireWhitespaceRule implements Rule {
   name = "erb-require-whitespace-inside-tags"
+
   check(node: Node): LintOffense[] {
     const visitor = new RequireWhitespaceInsideTags(this.name)
     visitor.visit(node)

package/src/rules/html-aria-attribute-must-be-valid.ts

@@ -0,0 +1,42 @@
+import {
+  ARIA_ATTRIBUTES,
+  AttributeVisitorMixin,
+} from "./rule-utils.js";
+
+import type { LintOffense, Rule } from "../types.js";
+import type {
+  HTMLAttributeNode,
+  HTMLOpenTagNode,
+  HTMLSelfCloseTagNode,
+  Node,
+} from "@herb-tools/core";
+
+class AriaAttributeMustBeValid extends AttributeVisitorMixin {
+  checkAttribute(
+    attributeName: string,
+    _attributeValue: string | null,
+    attributeNode: HTMLAttributeNode,
+    _parentNode: HTMLOpenTagNode | HTMLSelfCloseTagNode,
+  ): void {
+    if (!attributeName.startsWith("aria-")) return;
+
+    if (!ARIA_ATTRIBUTES.has(attributeName)){
+      this.offenses.push({
+        message: `The attribute \`${attributeName}\` is not a valid ARIA attribute. ARIA attributes must match the WAI-ARIA specification.`,
+        severity: "error",
+        location: attributeNode.location,
+        rule: this.ruleName,
+      });
+    }
+  }
+}
+
+export class HTMLAriaAttributeMustBeValid implements Rule {
+  name = "html-aria-attribute-must-be-valid";
+
+  check(node: Node): LintOffense[] {
+    const visitor = new AriaAttributeMustBeValid(this.name);
+    visitor.visit(node);
+    return visitor.offenses;
+  }
+}

package/src/rules/html-aria-role-must-be-valid.ts

@@ -0,0 +1,30 @@
+import { AttributeVisitorMixin, VALID_ARIA_ROLES } from "./rule-utils.js"
+
+import type { Rule, LintOffense } from "../types.js"
+import type { Node, HTMLAttributeNode } from "@herb-tools/core"
+
+class AriaRoleMustBeValid extends AttributeVisitorMixin {
+  checkAttribute(attributeName: string, attributeValue: string | null, attributeNode: HTMLAttributeNode,): void {
+    if (attributeName !== "role") return
+    if (attributeValue === null) return
+    if (VALID_ARIA_ROLES.has(attributeValue)) return
+
+    this.addOffense(
+      `The \`role\` attribute must be a valid ARIA role. Role \`${attributeValue}\` is not recognized.`,
+      attributeNode.location,
+      "error"
+    )
+  }
+}
+
+export class HTMLAriaRoleMustBeValidRule implements Rule {
+  name = "html-aria-role-must-be-valid"
+
+  check(node: Node): LintOffense[] {
+    const visitor = new AriaRoleMustBeValid(this.name)
+
+    visitor.visit(node)
+
+    return visitor.offenses
+  }
+}

package/src/rules/html-no-duplicate-ids.ts

@@ -0,0 +1,39 @@
+import { AttributeVisitorMixin } from "./rule-utils"
+
+import type { Node } from "@herb-tools/core"
+import type { LintOffense, Rule } from "../types"
+
+class NoDuplicateIdsVisitor extends AttributeVisitorMixin {
+  private documentIds: Set<string> = new Set<string>()
+
+  protected checkAttribute(attributeName: string, attributeValue: string | null, attributeNode: Node): void {
+    if (attributeName.toLowerCase() !== "id") return
+    if (!attributeValue) return
+
+    const id = attributeValue.trim()
+
+    if (this.documentIds.has(id)) {
+      this.addOffense(
+        `Duplicate ID \`${id}\` found. IDs must be unique within a document.`,
+        attributeNode.location,
+        "error"
+      )
+
+      return
+    }
+
+    this.documentIds.add(id)
+  }
+}
+
+export class HTMLNoDuplicateIdsRule implements Rule {
+  name = "html-no-duplicate-ids"
+
+  check(node: Node): LintOffense[] {
+    const visitor = new NoDuplicateIdsVisitor(this.name)
+
+    visitor.visit(node)
+
+    return visitor.offenses
+  }
+}

package/src/rules/html-tag-name-lowercase.ts

@@ -1,17 +1,29 @@
 import { BaseRuleVisitor } from "./rule-utils.js"
 
 import type { Rule, LintOffense } from "../types.js"
-import type { HTMLOpenTagNode, HTMLCloseTagNode, HTMLSelfCloseTagNode, Node } from "@herb-tools/core"
+import type { HTMLElementNode, HTMLOpenTagNode, HTMLCloseTagNode, HTMLSelfCloseTagNode, Node } from "@herb-tools/core"
 
 class TagNameLowercaseVisitor extends BaseRuleVisitor {
-  visitHTMLOpenTagNode(node: HTMLOpenTagNode): void {
-    this.checkTagName(node)
-    this.visitChildNodes(node)
-  }
+  visitHTMLElementNode(node: HTMLElementNode): void {
+    const tagName = node.tag_name?.value
+
+    if (node.open_tag) {
+      this.checkTagName(node.open_tag as HTMLOpenTagNode)
+    }
+
+    if (tagName && ["svg"].includes(tagName.toLowerCase())) {
+      if (node.close_tag) {
+        this.checkTagName(node.close_tag as HTMLCloseTagNode)
+      }
+
+      return
+    }
 
-  visitHTMLCloseTagNode(node: HTMLCloseTagNode): void {
-    this.checkTagName(node)
     this.visitChildNodes(node)
+
+    if (node.close_tag) {
+      this.checkTagName(node.close_tag as HTMLCloseTagNode)
+    }
   }
 
   visitHTMLSelfCloseTagNode(node: HTMLSelfCloseTagNode): void {
@@ -21,9 +33,12 @@ class TagNameLowercaseVisitor extends BaseRuleVisitor {
 
   private checkTagName(node: HTMLOpenTagNode | HTMLCloseTagNode | HTMLSelfCloseTagNode): void {
     const tagName = node.tag_name?.value
+
     if (!tagName) return
 
-    if (tagName !== tagName.toLowerCase()) {
+    const lowercaseTagName = tagName.toLowerCase()
+
+    if (tagName !== lowercaseTagName) {
       let type: string = node.type
 
       if (node.type == "AST_HTML_OPEN_TAG_NODE") type = "Opening"
@@ -31,7 +46,7 @@ class TagNameLowercaseVisitor extends BaseRuleVisitor {
       if (node.type == "AST_HTML_SELF_CLOSE_TAG_NODE") type = "Self-closing"
 
       this.addOffense(
-        `${type} tag name \`${tagName}\` should be lowercase. Use \`${tagName.toLowerCase()}\` instead.`,
+        `${type} tag name \`${tagName}\` should be lowercase. Use \`${lowercaseTagName}\` instead.`,
         node.tag_name!.location,
         "error"
       )

package/src/rules/index.ts

@@ -1,12 +1,16 @@
 export * from "./erb-no-empty-tags.js"
 export * from "./erb-no-output-control-flow.js"
 export * from "./html-anchor-require-href.js"
+export * from "./html-aria-role-heading-requires-level.js"
+export * from "./html-aria-role-must-be-valid.js"
 export * from "./html-attribute-double-quotes.js"
 export * from "./html-attribute-values-require-quotes.js"
 export * from "./html-boolean-attributes-no-value.js"
 export * from "./html-img-require-alt.js"
 export * from "./html-no-block-inside-inline.js"
 export * from "./html-no-duplicate-attributes.js"
+export * from "./html-no-duplicate-ids.js"
 export * from "./html-no-empty-headings.js"
 export * from "./html-no-nested-links.js"
 export * from "./html-tag-name-lowercase.js"
+export * from "./svg-tag-name-capitalization.js"