@herb-tools/linter 0.5.0 → 0.6.1

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

@@ -1,28 +1,203 @@
-import { AttributeVisitorMixin } from "./rule-utils"
 import { ParserRule } from "../types"
-import type { ParseResult, Node } from "@herb-tools/core"
+import { ControlFlowTrackingVisitor, ControlFlowType } from "./rule-utils"
+import { LiteralNode } from "@herb-tools/core"
+import { Printer, IdentityPrinter } from "@herb-tools/printer"
+
+import { hasERBOutput, getValidatableStaticContent, isEffectivelyStatic, isNode, getStaticAttributeName, isERBOutputNode } from "@herb-tools/core"
+
+import type { ParseResult, HTMLAttributeNode, ERBContentNode } from "@herb-tools/core"
 import type { LintOffense, LintContext } from "../types"
 
-class NoDuplicateIdsVisitor extends AttributeVisitorMixin {
+interface ControlFlowState {
+  previousBranchIds: Set<string>
+  previousControlFlowIds: Set<string>
+}
+
+interface BranchState {
+  previousBranchIds: Set<string>
+}
+
+class OutputPrinter extends Printer {
+  visitLiteralNode(node: LiteralNode) {
+    this.write(IdentityPrinter.print(node))
+  }
+
+  visitERBContentNode(node: ERBContentNode) {
+    if (isERBOutputNode(node)) {
+      this.write(IdentityPrinter.print(node))
+    }
+  }
+}
+
+class NoDuplicateIdsVisitor extends ControlFlowTrackingVisitor<ControlFlowState, BranchState> {
   private documentIds: Set<string> = new Set<string>()
+  private currentBranchIds: Set<string> = new Set<string>()
+  private controlFlowIds: Set<string> = new Set<string>()
+
+  visitHTMLAttributeNode(node: HTMLAttributeNode): void {
+    this.checkAttribute(node)
+  }
+
+  protected onEnterControlFlow(_controlFlowType: ControlFlowType, wasAlreadyInControlFlow: boolean): ControlFlowState {
+    const stateToRestore: ControlFlowState = {
+      previousBranchIds: this.currentBranchIds,
+      previousControlFlowIds: this.controlFlowIds
+    }
+
+    this.currentBranchIds = new Set<string>()
+
+    if (!wasAlreadyInControlFlow) {
+      this.controlFlowIds = new Set<string>()
+    }
+
+    return stateToRestore
+  }
+
+  protected onExitControlFlow(controlFlowType: ControlFlowType, wasAlreadyInControlFlow: boolean, stateToRestore: ControlFlowState): void {
+    if (controlFlowType === ControlFlowType.CONDITIONAL && !wasAlreadyInControlFlow) {
+      this.controlFlowIds.forEach(id => this.documentIds.add(id))
+    }
+
+    this.currentBranchIds = stateToRestore.previousBranchIds
+    this.controlFlowIds = stateToRestore.previousControlFlowIds
+  }
+
+  protected onEnterBranch(): BranchState {
+    const stateToRestore: BranchState = {
+      previousBranchIds: this.currentBranchIds
+    }
+
+    if (this.isInControlFlow) {
+      this.currentBranchIds = new Set<string>()
+    }
+
+    return stateToRestore
+  }
+
+  protected onExitBranch(_stateToRestore: BranchState): void {}
+
+  private checkAttribute(attributeNode: HTMLAttributeNode): void {
+    if (!this.isIdAttribute(attributeNode)) return
+
+    const idValue = this.extractIdValue(attributeNode)
+
+    if (!idValue) return
+    if (this.isWhitespaceOnlyId(idValue.identifier)) return
+
+    this.processIdDuplicate(idValue, attributeNode)
+  }
+
+  private isIdAttribute(attributeNode: HTMLAttributeNode): boolean {
+    if (!attributeNode.name?.children || !attributeNode.value) return false
+
+    return getStaticAttributeName(attributeNode.name) === "id"
+  }
+
+  private extractIdValue(attributeNode: HTMLAttributeNode): { identifier: string; shouldTrackDuplicates: boolean } | null {
+    const valueNodes = attributeNode.value?.children || []
+
+    if (hasERBOutput(valueNodes) && this.isInControlFlow && this.currentControlFlowType === ControlFlowType.LOOP) {
+      return null
+    }
+
+    const identifier = isEffectivelyStatic(valueNodes) ? getValidatableStaticContent(valueNodes) : OutputPrinter.print(valueNodes)
+    if (!identifier) return null
+
+    return { identifier, shouldTrackDuplicates: true }
+  }
+
+  private isWhitespaceOnlyId(identifier: string): boolean {
+    return identifier !== '' && identifier.trim() === ''
+  }
+
+  private processIdDuplicate(idValue: { identifier: string; shouldTrackDuplicates: boolean }, attributeNode: HTMLAttributeNode): void {
+    const { identifier, shouldTrackDuplicates } = idValue
 
-  protected checkAttribute(attributeName: string, attributeValue: string | null, attributeNode: Node): void {
-    if (attributeName.toLowerCase() !== "id") return
-    if (!attributeValue) return
+    if (!shouldTrackDuplicates) return
 
-    const id = attributeValue.trim()
+    if (this.isInControlFlow) {
+      this.handleControlFlowId(identifier, attributeNode)
+    } else {
+      this.handleGlobalId(identifier, attributeNode)
+    }
+  }
+
+  private handleControlFlowId(identifier: string, attributeNode: HTMLAttributeNode): void {
+    if (this.currentControlFlowType === ControlFlowType.LOOP) {
+      this.handleLoopId(identifier, attributeNode)
+    } else {
+      this.handleConditionalId(identifier, attributeNode)
+    }
+
+    this.currentBranchIds.add(identifier)
+  }
 
-    if (this.documentIds.has(id)) {
-      this.addOffense(
-        `Duplicate ID \`${id}\` found. IDs must be unique within a document.`,
-        attributeNode.location,
-        "error"
-      )
+  private handleLoopId(identifier: string, attributeNode: HTMLAttributeNode): void {
+    const isStaticId = this.isStaticId(attributeNode)
 
+    if (isStaticId) {
+      this.addDuplicateIdOffense(identifier, attributeNode.location)
       return
     }
 
-    this.documentIds.add(id)
+    if (this.currentBranchIds.has(identifier)) {
+      this.addSameLoopIterationOffense(identifier, attributeNode.location)
+    }
+  }
+
+  private handleConditionalId(identifier: string, attributeNode: HTMLAttributeNode): void {
+    if (this.currentBranchIds.has(identifier)) {
+      this.addSameBranchOffense(identifier, attributeNode.location)
+      return
+    }
+
+    if (this.documentIds.has(identifier)) {
+      this.addDuplicateIdOffense(identifier, attributeNode.location)
+      return
+    }
+
+    this.controlFlowIds.add(identifier)
+  }
+
+  private handleGlobalId(identifier: string, attributeNode: HTMLAttributeNode): void {
+    if (this.documentIds.has(identifier)) {
+      this.addDuplicateIdOffense(identifier, attributeNode.location)
+      return
+    }
+
+    this.documentIds.add(identifier)
+  }
+
+  private isStaticId(attributeNode: HTMLAttributeNode): boolean {
+    const valueNodes = attributeNode.value!.children
+    const isCompletelyStatic = valueNodes.every(child => isNode(child, LiteralNode))
+    const isEffectivelyStaticValue = isEffectivelyStatic(valueNodes)
+
+    return isCompletelyStatic || isEffectivelyStaticValue
+  }
+
+  private addDuplicateIdOffense(identifier: string, location: any): void {
+    this.addOffense(
+      `Duplicate ID \`${identifier}\` found. IDs must be unique within a document.`,
+      location,
+      "error"
+    )
+  }
+
+  private addSameLoopIterationOffense(identifier: string, location: any): void {
+    this.addOffense(
+      `Duplicate ID \`${identifier}\` found within the same loop iteration. IDs must be unique within the same loop iteration.`,
+      location,
+      "error"
+    )
+  }
+
+  private addSameBranchOffense(identifier: string, location: any): void {
+    this.addOffense(
+      `Duplicate ID \`${identifier}\` found within the same control flow branch. IDs must be unique within the same control flow branch.`,
+      location,
+      "error"
+    )
   }
 }
 

package/src/rules/html-no-empty-headings.ts

@@ -2,7 +2,7 @@ import { BaseRuleVisitor, getTagName, getAttributes, findAttributeByName, getAtt
 
 import { ParserRule } from "../types.js"
 import type { LintOffense, LintContext } from "../types.js"
-import type { HTMLElementNode, HTMLOpenTagNode, HTMLSelfCloseTagNode, ParseResult, LiteralNode, HTMLTextNode } from "@herb-tools/core"
+import type { HTMLElementNode, HTMLOpenTagNode, ParseResult, LiteralNode, HTMLTextNode } from "@herb-tools/core"
 
 class NoEmptyHeadingsVisitor extends BaseRuleVisitor {
   visitHTMLElementNode(node: HTMLElementNode): void {
@@ -10,10 +10,6 @@ class NoEmptyHeadingsVisitor extends BaseRuleVisitor {
     super.visitHTMLElementNode(node)
   }
 
-  visitHTMLSelfCloseTagNode(node: HTMLSelfCloseTagNode): void {
-    this.checkSelfClosingHeading(node)
-    super.visitHTMLSelfCloseTagNode(node)
-  }
 
   private checkHeadingElement(node: HTMLElementNode): void {
     if (!node.open_tag || node.open_tag.type !== "AST_HTML_OPEN_TAG_NODE") {
@@ -47,31 +43,6 @@ class NoEmptyHeadingsVisitor extends BaseRuleVisitor {
     }
   }
 
-  private checkSelfClosingHeading(node: HTMLSelfCloseTagNode): void {
-    const tagName = getTagName(node)
-    if (!tagName) {
-      return
-    }
-
-    // Check if it's a standard heading tag (h1-h6) or has role="heading"
-    const isStandardHeading = HEADING_TAGS.has(tagName)
-    const isAriaHeading = this.hasHeadingRole(node)
-
-    if (!isStandardHeading && !isAriaHeading) {
-      return
-    }
-
-    // Self-closing headings are always empty
-    const elementDescription = isStandardHeading
-      ? `\`<${tagName}>\``
-      : `\`<${tagName} role="heading">\``
-
-    this.addOffense(
-      `Heading element ${elementDescription} must not be empty. Provide accessible text content for screen readers and SEO.`,
-      node.tag_name!.location,
-      "error"
-    )
-  }
 
   private isEmptyHeading(node: HTMLElementNode): boolean {
     if (!node.body || node.body.length === 0) {
@@ -114,7 +85,7 @@ class NoEmptyHeadingsVisitor extends BaseRuleVisitor {
     return !hasAccessibleContent
   }
 
-  private hasHeadingRole(node: HTMLOpenTagNode | HTMLSelfCloseTagNode): boolean {
+  private hasHeadingRole(node: HTMLOpenTagNode): boolean {
     const attributes = getAttributes(node)
     const roleAttribute = findAttributeByName(attributes, "role")
 

package/src/rules/html-no-positive-tab-index.ts

@@ -0,0 +1,33 @@
+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 NoPositiveTabIndexVisitor extends AttributeVisitorMixin {
+  protected checkStaticAttributeStaticValue({ attributeName, attributeValue, attributeNode }: StaticAttributeStaticValueParams): void {
+    if (attributeName !== "tabindex") return
+
+    const tabIndexValue = parseInt(attributeValue, 10)
+
+    if (!isNaN(tabIndexValue) && tabIndexValue > 0) {
+      this.addOffense(
+        `Do not use positive \`tabindex\` values as they are error prone and can severely disrupt navigation experience for keyboard users. Use \`tabindex="0"\` to make an element focusable or \`tabindex=\"-1\"\` to remove it from the tab sequence.`,
+        attributeNode.location,
+        "error"
+      )
+    }
+  }
+}
+
+export class HTMLNoPositiveTabIndexRule extends ParserRule {
+  name = "html-no-positive-tab-index"
+
+  check(result: ParseResult, context?: Partial<LintContext>): LintOffense[] {
+    const visitor = new NoPositiveTabIndexVisitor(this.name, context)
+
+    visitor.visit(result.value)
+
+    return visitor.offenses
+  }
+}

package/src/rules/html-no-self-closing.ts

@@ -0,0 +1,41 @@
+import { ParserRule } from "../types.js"
+import { BaseRuleVisitor, isVoidElement } from "./rule-utils.js"
+import { getTagName } from "@herb-tools/core"
+
+import type { LintContext, LintOffense } from "../types.js"
+import type { HTMLOpenTagNode, HTMLElementNode, ParseResult } from "@herb-tools/core"
+
+class NoSelfClosingVisitor extends BaseRuleVisitor {
+  visitHTMLElementNode(node: HTMLElementNode): void {
+    if (getTagName(node) === "svg") {
+      this.visit(node.open_tag)
+    } else {
+      this.visitChildNodes(node)
+    }
+  }
+
+  visitHTMLOpenTagNode(node: HTMLOpenTagNode): void {
+    if (node.tag_closing?.value === "/>") {
+      const tagName = getTagName(node)
+      const instead = isVoidElement(tagName) ? `<${tagName}>` : `<${tagName}></${tagName}>`
+
+      this.addOffense(
+        `Use \`${instead}\` instead of self-closing \`<${tagName} />\` for HTML compatibility.`,
+        node.location,
+        "error"
+      )
+    }
+  }
+}
+
+export class HTMLNoSelfClosingRule extends ParserRule {
+  name = "html-no-self-closing"
+
+  check(result: ParseResult, context?: Partial<LintContext>): LintOffense[] {
+    const visitor = new NoSelfClosingVisitor(this.name, context)
+
+    visitor.visit(result.value)
+
+    return visitor.offenses
+  }
+}

package/src/rules/html-no-title-attribute.ts

@@ -0,0 +1,42 @@
+import { ParserRule } from "../types.js"
+import { BaseRuleVisitor, getTagName, hasAttribute } from "./rule-utils.js"
+
+import type { LintOffense, LintContext } from "../types.js"
+import type { HTMLOpenTagNode, ParseResult } from "@herb-tools/core"
+
+class NoTitleAttributeVisitor extends BaseRuleVisitor {
+  ALLOWED_ELEMENTS_WITH_TITLE = new Set(["iframe", "link"])
+
+  visitHTMLOpenTagNode(node: HTMLOpenTagNode): void {
+    this.checkTitleAttribute(node)
+    super.visitHTMLOpenTagNode(node)
+  }
+
+  private checkTitleAttribute(node: HTMLOpenTagNode): void {
+    const tagName = getTagName(node)
+
+    if (!tagName || this.ALLOWED_ELEMENTS_WITH_TITLE.has(tagName)) {
+      return
+    }
+
+    if (hasAttribute(node, "title")) {
+      this.addOffense(
+        "The `title` attribute should never be used as it is inaccessible for several groups of users. Use `aria-label` or `aria-describedby` instead. Exceptions are provided for `<iframe>` and `<link>` elements.",
+        node.tag_name!.location,
+        "error"
+      )
+    }
+  }
+}
+
+export class HTMLNoTitleAttributeRule extends ParserRule {
+  name = "html-no-title-attribute"
+
+  check(result: ParseResult, context?: Partial<LintContext>): LintOffense[] {
+    const visitor = new NoTitleAttributeVisitor(this.name, context)
+
+    visitor.visit(result.value)
+
+    return visitor.offenses
+  }
+}

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

@@ -1,53 +1,56 @@
+import { ParserRule } from "../types.js"
 import { BaseRuleVisitor } from "./rule-utils.js"
 
-import { ParserRule } from "../types.js"
+import { isNode, getTagName, HTMLElementNode, HTMLOpenTagNode, HTMLCloseTagNode, ParseResult, XMLDeclarationNode, Node } from "@herb-tools/core"
+
 import type { LintOffense, LintContext } from "../types.js"
-import type { HTMLElementNode, HTMLOpenTagNode, HTMLCloseTagNode, HTMLSelfCloseTagNode, ParseResult } from "@herb-tools/core"
 
-class TagNameLowercaseVisitor extends BaseRuleVisitor {
-  visitHTMLElementNode(node: HTMLElementNode): void {
-    const tagName = node.tag_name?.value
+class XMLDeclarationChecker extends BaseRuleVisitor {
+  hasXMLDeclaration: boolean = false
 
-    if (node.open_tag) {
-      this.checkTagName(node.open_tag as HTMLOpenTagNode)
-    }
+  visitXMLDeclarationNode(_node: XMLDeclarationNode): void {
+    this.hasXMLDeclaration = true
+  }
 
-    if (tagName && ["svg"].includes(tagName.toLowerCase())) {
-      if (node.close_tag) {
-        this.checkTagName(node.close_tag as HTMLCloseTagNode)
-      }
+  visitChildNodes(node: Node): void {
+    if (this.hasXMLDeclaration) return
+    super.visitChildNodes(node)
+  }
+}
 
-      return
+class TagNameLowercaseVisitor extends BaseRuleVisitor {
+  visitHTMLElementNode(node: HTMLElementNode): void {
+    if (getTagName(node).toLowerCase() === "svg") {
+      this.checkTagName(node.open_tag)
+      this.checkTagName(node.close_tag)
+    } else {
+      super.visitHTMLElementNode(node)
     }
+  }
 
-    this.visitChildNodes(node)
-
-    if (node.close_tag) {
-      this.checkTagName(node.close_tag as HTMLCloseTagNode)
-    }
+  visitHTMLOpenTagNode(node: HTMLOpenTagNode) {
+    this.checkTagName(node)
   }
 
-  visitHTMLSelfCloseTagNode(node: HTMLSelfCloseTagNode): void {
+  visitHTMLCloseTagNode(node: HTMLCloseTagNode) {
     this.checkTagName(node)
-    this.visitChildNodes(node)
   }
 
-  private checkTagName(node: HTMLOpenTagNode | HTMLCloseTagNode | HTMLSelfCloseTagNode): void {
-    const tagName = node.tag_name?.value
+  private checkTagName(node: HTMLOpenTagNode | HTMLCloseTagNode | null): void {
+    if (!node) return
+
+    const tagName = getTagName(node)
 
     if (!tagName) return
 
     const lowercaseTagName = tagName.toLowerCase()
 
-    if (tagName !== lowercaseTagName) {
-      let type: string = node.type
-
-      if (node.type == "AST_HTML_OPEN_TAG_NODE") type = "Opening"
-      if (node.type == "AST_HTML_CLOSE_TAG_NODE") type = "Closing"
-      if (node.type == "AST_HTML_SELF_CLOSE_TAG_NODE") type = "Self-closing"
+    const type = isNode(node, HTMLOpenTagNode) ? "Opening" : "Closing"
+    const open = isNode(node, HTMLOpenTagNode) ? "<" : "</"
 
+    if (tagName !== lowercaseTagName) {
       this.addOffense(
-        `${type} tag name \`${tagName}\` should be lowercase. Use \`${lowercaseTagName}\` instead.`,
+        `${type} tag name \`${open}${tagName}>\` should be lowercase. Use \`${open}${lowercaseTagName}>\` instead.`,
         node.tag_name!.location,
         "error"
       )
@@ -58,6 +61,16 @@ class TagNameLowercaseVisitor extends BaseRuleVisitor {
 export class HTMLTagNameLowercaseRule extends ParserRule {
   name = "html-tag-name-lowercase"
 
+  isEnabled(result: ParseResult, context?: Partial<LintContext>): boolean {
+    if (context?.fileName?.endsWith(".xml") || context?.fileName?.endsWith(".xml.erb")) {
+      return false
+    }
+
+    const checker = new XMLDeclarationChecker(this.name)
+    checker.visit(result.value)
+    return !checker.hasXMLDeclaration
+  }
+
   check(result: ParseResult, context?: Partial<LintContext>): LintOffense[] {
     const visitor = new TagNameLowercaseVisitor(this.name, context)
     visitor.visit(result.value)

package/src/rules/index.ts

@@ -1,19 +1,29 @@
 export * from "./erb-no-empty-tags.js"
 export * from "./erb-no-output-control-flow.js"
+export * from "./erb-no-silent-tag-in-attribute-name.js"
 export * from "./erb-prefer-image-tag-helper.js"
 export * from "./erb-requires-trailing-newline.js"
 export * from "./html-anchor-require-href.js"
+export * from "./html-aria-label-is-well-formatted.js"
 export * from "./html-aria-level-must-be-valid.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-equals-spacing.js"
 export * from "./html-attribute-values-require-quotes.js"
+export * from "./html-avoid-both-disabled-and-aria-disabled.js"
 export * from "./html-boolean-attributes-no-value.js"
+export * from "./html-iframe-has-title.js"
 export * from "./html-img-require-alt.js"
+export * from "./html-navigation-has-label.js"
+export * from "./html-no-aria-hidden-on-focusable.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-no-positive-tab-index.js"
+export * from "./html-no-self-closing.js"
+export * from "./html-no-title-attribute.js"
 export * from "./html-tag-name-lowercase.js"
 export * from "./svg-tag-name-capitalization.js"