@herb-tools/linter 0.5.0 → 0.6.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herb-tools/linter",
-  "version": "0.5.0",
+  "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.5.0",
-    "@herb-tools/highlighter": "0.5.0",
-    "@herb-tools/node-wasm": "0.5.0",
+    "@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

@@ -114,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 }
   }
 

package/src/default-rules.ts

@@ -2,23 +2,33 @@ import type { RuleClass } from "./types.js"
 
 import { ERBNoEmptyTagsRule } from "./rules/erb-no-empty-tags.js"
 import { ERBNoOutputControlFlowRule } from "./rules/erb-no-output-control-flow.js"
+import { ERBNoSilentTagInAttributeNameRule } from "./rules/erb-no-silent-tag-in-attribute-name.js"
 import { ERBPreferImageTagHelperRule } from "./rules/erb-prefer-image-tag-helper.js"
 import { ERBRequiresTrailingNewlineRule } from "./rules/erb-requires-trailing-newline.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 { HTMLAriaLabelIsWellFormattedRule } from "./rules/html-aria-label-is-well-formatted.js"
 import { HTMLAriaLevelMustBeValidRule } from "./rules/html-aria-level-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 { HTMLAttributeEqualsSpacingRule } from "./rules/html-attribute-equals-spacing.js"
 import { HTMLAttributeValuesRequireQuotesRule } from "./rules/html-attribute-values-require-quotes.js"
+import { HTMLAvoidBothDisabledAndAriaDisabledRule } from "./rules/html-avoid-both-disabled-and-aria-disabled.js"
 import { HTMLBooleanAttributesNoValueRule } from "./rules/html-boolean-attributes-no-value.js"
+import { HTMLIframeHasTitleRule } from "./rules/html-iframe-has-title.js"
 import { HTMLImgRequireAltRule } from "./rules/html-img-require-alt.js"
+import { HTMLNavigationHasLabelRule } from "./rules/html-navigation-has-label.js"
+import { HTMLNoAriaHiddenOnFocusableRule } from "./rules/html-no-aria-hidden-on-focusable.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 { HTMLNoPositiveTabIndexRule } from "./rules/html-no-positive-tab-index.js"
+import { HTMLNoSelfClosingRule } from "./rules/html-no-self-closing.js"
+import { HTMLNoTitleAttributeRule } from "./rules/html-no-title-attribute.js"
 import { HTMLTagNameLowercaseRule } from "./rules/html-tag-name-lowercase.js"
 import { ParserNoErrorsRule } from "./rules/parser-no-errors.js"
 import { SVGTagNameCapitalizationRule } from "./rules/svg-tag-name-capitalization.js"
@@ -26,23 +36,33 @@ import { SVGTagNameCapitalizationRule } from "./rules/svg-tag-name-capitalizatio
 export const defaultRules: RuleClass[] = [
   ERBNoEmptyTagsRule,
   ERBNoOutputControlFlowRule,
+  ERBNoSilentTagInAttributeNameRule,
   ERBPreferImageTagHelperRule,
   ERBRequiresTrailingNewlineRule,
   ERBRequireWhitespaceRule,
   HTMLAnchorRequireHrefRule,
   HTMLAriaAttributeMustBeValid,
+  HTMLAriaLabelIsWellFormattedRule,
   HTMLAriaLevelMustBeValidRule,
   HTMLAriaRoleHeadingRequiresLevelRule,
   HTMLAriaRoleMustBeValidRule,
   HTMLAttributeDoubleQuotesRule,
+  HTMLAttributeEqualsSpacingRule,
   HTMLAttributeValuesRequireQuotesRule,
+  HTMLAvoidBothDisabledAndAriaDisabledRule,
   HTMLBooleanAttributesNoValueRule,
+  HTMLIframeHasTitleRule,
   HTMLImgRequireAltRule,
+  HTMLNavigationHasLabelRule,
+  HTMLNoAriaHiddenOnFocusableRule,
   // HTMLNoBlockInsideInlineRule,
   HTMLNoDuplicateAttributesRule,
   HTMLNoDuplicateIdsRule,
   HTMLNoEmptyHeadingsRule,
   HTMLNoNestedLinksRule,
+  HTMLNoPositiveTabIndexRule,
+  HTMLNoSelfClosingRule,
+  HTMLNoTitleAttributeRule,
   HTMLTagNameLowercaseRule,
   ParserNoErrorsRule,
   SVGTagNameCapitalizationRule,

package/src/linter.ts

@@ -53,20 +53,46 @@ export class Linter {
   lint(source: string, context?: Partial<LintContext>): LintResult {
     this.offenses = []
 
-    const parseResult = this.herb.parse(source)
+    const parseResult = this.herb.parse(source, { track_whitespace: true })
     const lexResult = this.herb.lex(source)
 
     for (const RuleClass of this.rules) {
       const rule = new RuleClass()
 
+      let isEnabled = true
       let ruleOffenses: LintOffense[]
 
       if (this.isLexerRule(rule)) {
-        ruleOffenses = (rule as LexerRule).check(lexResult, context)
+        if (rule.isEnabled) {
+          isEnabled = rule.isEnabled(lexResult, context)
+        }
+
+        if (isEnabled) {
+          ruleOffenses = (rule as LexerRule).check(lexResult, context)
+        } else {
+          ruleOffenses = []
+        }
+
       } else if (this.isSourceRule(rule)) {
-        ruleOffenses = (rule as SourceRule).check(source, context)
+        if (rule.isEnabled) {
+          isEnabled = rule.isEnabled(source, context)
+        }
+
+        if (isEnabled) {
+          ruleOffenses = (rule as SourceRule).check(source, context)
+        } else {
+          ruleOffenses = []
+        }
       } else {
-        ruleOffenses = (rule as ParserRule).check(parseResult, context)
+        if (rule.isEnabled) {
+          isEnabled = rule.isEnabled(parseResult, context)
+        }
+
+        if (isEnabled) {
+          ruleOffenses = (rule as ParserRule).check(parseResult, context)
+        } else {
+          ruleOffenses = []
+        }
       }
 
       this.offenses.push(...ruleOffenses)

package/src/rules/erb-no-silent-tag-in-attribute-name.ts

@@ -0,0 +1,40 @@
+import { ParserRule } from "../types.js"
+import { BaseRuleVisitor } from "./rule-utils.js"
+import { filterERBContentNodes } from "@herb-tools/core"
+
+import type { LintOffense, LintContext } from "../types.js"
+import type { ParseResult, HTMLAttributeNameNode, ERBContentNode } from "@herb-tools/core"
+
+class ERBNoSilentTagInAttributeNameVisitor extends BaseRuleVisitor {
+  visitHTMLAttributeNameNode(node: HTMLAttributeNameNode): void {
+    const erbNodes = filterERBContentNodes(node.children)
+    const silentNodes = erbNodes.filter(this.isSilentERBTag)
+
+    for (const node of silentNodes) {
+      this.addOffense(
+        `Remove silent ERB tag from HTML attribute name. Silent ERB tags (\`${node.tag_opening?.value}\`) do not output content and should not be used in attribute names.`,
+        node.location,
+        "error"
+      )
+    }
+  }
+
+  // TODO: might be worth to extract
+  private isSilentERBTag(node: ERBContentNode): boolean {
+    const silentTags = ["<%", "<%-", "<%#"]
+
+    return silentTags.includes(node.tag_opening?.value || "")
+  }
+}
+
+export class ERBNoSilentTagInAttributeNameRule extends ParserRule {
+  name = "erb-no-silent-tag-in-attribute-name"
+
+  check(result: ParseResult, context?: Partial<LintContext>): LintOffense[] {
+    const visitor = new ERBNoSilentTagInAttributeNameVisitor(this.name, context)
+
+    visitor.visit(result.value)
+
+    return visitor.offenses
+  }
+}

package/src/rules/erb-prefer-image-tag-helper.ts

@@ -2,7 +2,7 @@ import { BaseRuleVisitor, getTagName, findAttributeByName, getAttributes } from
 
 import { ParserRule } from "../types.js"
 import type { LintOffense, LintContext } from "../types.js"
-import type { HTMLOpenTagNode, HTMLSelfCloseTagNode, HTMLAttributeValueNode, ERBContentNode, LiteralNode, ParseResult } from "@herb-tools/core"
+import type { HTMLOpenTagNode, HTMLAttributeValueNode, ERBContentNode, LiteralNode, ParseResult } from "@herb-tools/core"
 
 class ERBPreferImageTagHelperVisitor extends BaseRuleVisitor {
   visitHTMLOpenTagNode(node: HTMLOpenTagNode): void {
@@ -10,12 +10,7 @@ class ERBPreferImageTagHelperVisitor extends BaseRuleVisitor {
     super.visitHTMLOpenTagNode(node)
   }
 
-  visitHTMLSelfCloseTagNode(node: HTMLSelfCloseTagNode): void {
-    this.checkImgTag(node)
-    super.visitHTMLSelfCloseTagNode(node)
-  }
-
-  private checkImgTag(node: HTMLOpenTagNode | HTMLSelfCloseTagNode): void {
+  private checkImgTag(node: HTMLOpenTagNode): void {
     const tagName = getTagName(node)
 
     if (tagName !== "img") {

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

@@ -1,42 +1,38 @@
-import {
-  ARIA_ATTRIBUTES,
-  AttributeVisitorMixin,
-} from "./rule-utils.js";
-import { ParserRule } from "../types.js";
-import type { LintOffense, LintContext } from "../types.js";
-import type {
-  HTMLAttributeNode,
-  HTMLOpenTagNode,
-  HTMLSelfCloseTagNode,
-  ParseResult,
-} from "@herb-tools/core";
+import { ParserRule } from "../types.js"
+import { ARIA_ATTRIBUTES, AttributeVisitorMixin, StaticAttributeStaticValueParams, StaticAttributeDynamicValueParams } from "./rule-utils.js"
+
+import type { LintOffense, LintContext } from "../types.js"
+import type { ParseResult, HTMLAttributeNode } 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,
-      });
-    }
+  protected checkStaticAttributeStaticValue({ attributeName, attributeNode }: StaticAttributeStaticValueParams) {
+    this.check(attributeName, attributeNode)
+  }
+
+  protected checkStaticAttributeDynamicValue({ attributeName, attributeNode }: StaticAttributeDynamicValueParams) {
+    this.check(attributeName, attributeNode)
+  }
+
+  private check(attributeName: string, attributeNode: HTMLAttributeNode) {
+    if (!attributeName.startsWith("aria-")) return
+    if (ARIA_ATTRIBUTES.has(attributeName)) return
+
+    this.addOffense(
+      `The attribute \`${attributeName}\` is not a valid ARIA attribute. ARIA attributes must match the WAI-ARIA specification.`,
+      attributeNode.location,
+      "error"
+    )
   }
 }
 
 export class HTMLAriaAttributeMustBeValid extends ParserRule {
-  name = "html-aria-attribute-must-be-valid";
+  name = "html-aria-attribute-must-be-valid"
 
   check(result: ParseResult, context?: Partial<LintContext>): LintOffense[] {
-    const visitor = new AriaAttributeMustBeValid(this.name, context);
-    visitor.visit(result.value);
-    return visitor.offenses;
+    const visitor = new AriaAttributeMustBeValid(this.name, context)
+
+    visitor.visit(result.value)
+
+    return visitor.offenses
   }
 }

package/src/rules/html-aria-label-is-well-formatted.ts

@@ -0,0 +1,59 @@
+import { ParserRule } from "../types.js"
+import { AttributeVisitorMixin, StaticAttributeStaticValueParams } from "./rule-utils.js"
+
+import type { LintOffense, LintContext } from "../types.js"
+import type { ParseResult } from "@herb-tools/core"
+
+class AriaLabelIsWellFormattedVisitor extends AttributeVisitorMixin {
+  protected checkStaticAttributeStaticValue({ attributeName, attributeValue, attributeNode }: StaticAttributeStaticValueParams): void {
+    if (attributeName !== "aria-label") return
+
+    if (attributeValue.match(/[\r\n]+/) || attributeValue.match(/
|
|
|
/i)) {
+      this.addOffense(
+        "The `aria-label` attribute value text should not contain line breaks. Use concise, single-line descriptions.",
+        attributeNode.location,
+        "error"
+      )
+
+      return
+    }
+
+    if (this.looksLikeId(attributeValue)) {
+      this.addOffense(
+        "The `aria-label` attribute value should not be formatted like an ID. Use natural, sentence-case text instead.",
+        attributeNode.location,
+        "error"
+      )
+
+      return
+    }
+
+    if (attributeValue.match(/^[a-z]/)) {
+      this.addOffense(
+        "The `aria-label` attribute value text should be formatted like visual text. Use sentence case (capitalize the first letter).",
+        attributeNode.location,
+        "error"
+      )
+    }
+  }
+
+  private looksLikeId(text: string): boolean {
+    return (
+      text.includes('_') ||
+      text.includes('-') ||
+      /^[a-z]+([A-Z][a-z]*)*$/.test(text)
+    ) && !text.includes(' ')
+  }
+}
+
+export class HTMLAriaLabelIsWellFormattedRule extends ParserRule {
+  name = "html-aria-label-is-well-formatted"
+
+  check(result: ParseResult, context?: Partial<LintContext>): LintOffense[] {
+    const visitor = new AriaLabelIsWellFormattedVisitor(this.name, context)
+
+    visitor.visit(result.value)
+
+    return visitor.offenses
+  }
+}

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

@@ -1,15 +1,48 @@
-import { AttributeVisitorMixin } from "./rule-utils.js"
 import { ParserRule } from "../types.js"
+import { AttributeVisitorMixin, StaticAttributeStaticValueParams, StaticAttributeDynamicValueParams } from "./rule-utils.js"
+import { getValidatableStaticContent, hasERBOutput, filterLiteralNodes, filterERBContentNodes, isERBOutputNode } from "@herb-tools/core"
 
 import type { LintOffense, LintContext } from "../types.js"
-import type { ParseResult, HTMLAttributeNode, HTMLOpenTagNode, HTMLSelfCloseTagNode } from "@herb-tools/core"
+import type { ParseResult, HTMLAttributeNode } from "@herb-tools/core"
 
 class HTMLAriaLevelMustBeValidVisitor extends AttributeVisitorMixin {
-  protected checkAttribute(attributeName: string, attributeValue: string | null, attributeNode: HTMLAttributeNode, _parentNode: HTMLOpenTagNode | HTMLSelfCloseTagNode): void {
+  protected checkStaticAttributeStaticValue({ attributeName, attributeValue, attributeNode }: StaticAttributeStaticValueParams) {
     if (attributeName !== "aria-level") return
-    if (attributeValue !== null && attributeValue.includes("<%")) return
 
-    if (attributeValue === null || attributeValue === "") {
+    this.validateAriaLevel(attributeValue, attributeNode)
+  }
+
+  protected checkStaticAttributeDynamicValue({ attributeName, valueNodes, attributeNode }: StaticAttributeDynamicValueParams) {
+    if (attributeName !== "aria-level") return
+
+    const validatableContent = getValidatableStaticContent(valueNodes)
+
+    if (validatableContent !== null) {
+      this.validateAriaLevel(validatableContent, attributeNode)
+      return
+    }
+
+    if (!hasERBOutput(valueNodes)) return
+
+    const literalNodes = filterLiteralNodes(valueNodes)
+    const erbOutputNodes = filterERBContentNodes(valueNodes).filter(isERBOutputNode)
+
+    if (literalNodes.length > 0 && erbOutputNodes.length > 0) {
+      const staticPart = literalNodes.map(node => node.content).join("")
+
+      // TODO: this can be cleaned up using @herb-tools/printer
+      const erbPart = erbOutputNodes[0]
+      const erbText = `${erbPart.tag_opening?.value || ""}${erbPart.content?.value || ""}${erbPart.tag_closing?.value || ""}`
+
+      this.addOffense(
+        `The \`aria-level\` attribute must be an integer between 1 and 6, got \`${staticPart}\` and the ERB expression \`${erbText}\`.`,
+        attributeNode.location,
+      )
+    }
+  }
+
+  private validateAriaLevel(attributeValue: string, attributeNode: HTMLAttributeNode): void {
+    if (!attributeValue || attributeValue === "") {
       this.addOffense(
         `The \`aria-level\` attribute must be an integer between 1 and 6, got an empty value.`,
         attributeNode.location,