@herb-tools/linter 0.4.0

package/src/rules/erb-no-output-control-flow.ts

@@ -0,0 +1,61 @@
+import { BaseRuleVisitor } from "./rule-utils.js"
+
+import type { Node, ERBIfNode, ERBUnlessNode, ERBElseNode, ERBEndNode } from "@herb-tools/core"
+import type { Rule, LintOffense } from "../types.js"
+
+class ERBNoOutputControlFlowRuleVisitor extends BaseRuleVisitor {
+  visitERBIfNode(node: ERBIfNode): void {
+    this.checkOutputControlFlow(node)
+    this.visitChildNodes(node)
+  }
+
+  visitERBUnlessNode(node: ERBUnlessNode): void {
+    this.checkOutputControlFlow(node)
+    this.visitChildNodes(node)
+  }
+
+  visitERBElseNode(node: ERBElseNode): void {
+    this.checkOutputControlFlow(node)
+    this.visitChildNodes(node)
+  }
+
+  visitERBEndNode(node: ERBEndNode): void {
+    this.checkOutputControlFlow(node)
+    this.visitChildNodes(node)
+  }
+
+  private checkOutputControlFlow(controlBlock: ERBIfNode | ERBUnlessNode | ERBElseNode | ERBEndNode): void {
+    const openTag = controlBlock.tag_opening;
+    if (!openTag) {
+      return
+    }
+
+    if (openTag.value === "<%="){
+      let controlBlockType: string = controlBlock.type
+
+      if (controlBlock.type === "AST_ERB_IF_NODE") controlBlockType = "if"
+      if (controlBlock.type === "AST_ERB_ELSE_NODE") controlBlockType = "else"
+      if (controlBlock.type === "AST_ERB_END_NODE") controlBlockType = "end"
+      if (controlBlock.type === "AST_ERB_UNLESS_NODE") controlBlockType = "unless"
+
+      this.addOffense(
+        `Control flow statements like \`${controlBlockType}\` should not be used with output tags. Use \`<% ${controlBlockType} ... %>\` instead.`,
+        openTag.location,
+        "error"
+      )
+    }
+
+    return
+  }
+}
+
+export class ERBNoOutputControlFlowRule implements Rule {
+  name = "erb-no-output-control-flow"
+  check(node: Node): LintOffense[] {
+    const visitor = new ERBNoOutputControlFlowRuleVisitor(this.name)
+
+    visitor.visit(node)
+
+    return visitor.offenses
+  }
+}

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

@@ -0,0 +1,61 @@
+import type { Node, Token } from "@herb-tools/core"
+import { isERBNode } from "@herb-tools/core";
+import type { LintOffense, Rule } from "../types.js"
+import { BaseRuleVisitor } from "./rule-utils.js"
+
+class RequireWhitespaceInsideTags extends BaseRuleVisitor {
+
+  visitChildNodes(node: Node): void {
+    this.checkWhitespace(node)
+    super.visitChildNodes(node)
+  }
+
+  private checkWhitespace(node: Node): void {
+    if (!isERBNode(node)) {
+      return
+    }
+    const openTag = node.tag_opening
+    const closeTag = node.tag_closing
+    const content = node.content
+
+    if (!openTag || !closeTag || !content) {
+      return
+    }
+
+    const value = content.value
+
+    this.checkOpenTagWhitespace(openTag, value)
+    this.checkCloseTagWhitespace(closeTag, value)
+  }
+
+  private checkOpenTagWhitespace(openTag: Token, content:string):void {
+    if (content.startsWith(" ") || content.startsWith("\n")) {
+      return
+    }
+    this.addOffense(
+      `Add whitespace after \`${openTag.value}\`.`,
+      openTag.location,
+      "error"
+    )
+  }
+
+  private checkCloseTagWhitespace(closeTag: Token, content:string):void {
+    if (content.endsWith(" ") || content.endsWith("\n")) {
+      return
+    }
+    this.addOffense(
+      `Add whitespace before \`${closeTag.value}\`.`,
+      closeTag.location,
+      "error"
+    )
+  }
+}
+
+export class ERBRequireWhitespaceRule implements Rule {
+  name = "erb-require-whitespace-inside-tags"
+  check(node: Node): LintOffense[] {
+    const visitor = new RequireWhitespaceInsideTags(this.name)
+    visitor.visit(node)
+    return visitor.offenses
+  }
+}

package/src/rules/html-anchor-require-href.ts

@@ -0,0 +1,39 @@
+import { BaseRuleVisitor, getTagName, hasAttribute } from "./rule-utils.js"
+
+import { Rule, LintOffense } from "../types.js"
+import type { HTMLOpenTagNode, Node } from "@herb-tools/core"
+
+class AnchorRechireHrefVisitor extends BaseRuleVisitor {
+  visitHTMLOpenTagNode(node: HTMLOpenTagNode): void {
+    this.checkATag(node)
+    super.visitHTMLOpenTagNode(node)
+  }
+
+  private checkATag(node: HTMLOpenTagNode): void {
+    const tagName = getTagName(node)
+
+    if (tagName !== "a") {
+      return
+    }
+
+    if (!hasAttribute(node, "href")) {
+      this.addOffense(
+        "Add an `href` attribute to `<a>` to ensure it is focusable and accessible.",
+        node.tag_name!.location,
+        "error",
+      )
+    }
+  }
+}
+
+export class HTMLAnchorRequireHrefRule implements Rule {
+  name = "html-anchor-require-href"
+
+  check(node: Node): LintOffense[] {
+    const visitor = new AnchorRechireHrefVisitor(this.name)
+
+    visitor.visit(node)
+
+    return visitor.offenses
+  }
+}

package/src/rules/html-aria-role-heading-requires-level.ts

@@ -0,0 +1,44 @@
+import { AttributeVisitorMixin, getAttributeName, getAttributes } from "./rule-utils.js"
+
+import type { Rule, LintOffense } from "../types.js"
+import type { Node, HTMLAttributeNode, HTMLOpenTagNode, HTMLSelfCloseTagNode } from "@herb-tools/core"
+
+class AriaRoleHeadingRequiresLevel extends AttributeVisitorMixin {
+
+  // We want to check 2 attributes here:
+  // 1. role="heading"
+  // 2. aria-level (which must be present if role="heading")
+  checkAttribute(
+    attributeName: string,
+    attributeValue: string | null,
+    attributeNode: HTMLAttributeNode,
+    parentNode: HTMLOpenTagNode | HTMLSelfCloseTagNode
+  ): void {
+
+    if (!(attributeName === "role" && attributeValue === "heading")) {
+      return
+    }
+
+    const allAttributes = getAttributes(parentNode)
+
+    // If we have a role="heading", we must check for aria-level
+    const ariaLevelAttr = allAttributes.find(attr => getAttributeName(attr) === "aria-level")
+    if (!ariaLevelAttr) {
+      this.addOffense(
+        `Element with \`role="heading"\` must have an \`aria-level\` attribute.`,
+        attributeNode.location,
+        "error"
+      )
+    }
+  }
+}
+
+export class HTMLAriaRoleHeadingRequiresLevelRule implements Rule {
+  name = "html-aria-role-heading-requires-level"
+
+  check(node: Node): LintOffense[] {
+    const visitor = new AriaRoleHeadingRequiresLevel(this.name)
+    visitor.visit(node)
+    return visitor.offenses
+  }
+}

package/src/rules/html-attribute-double-quotes.ts

@@ -0,0 +1,28 @@
+import { AttributeVisitorMixin, getAttributeValueQuoteType, hasAttributeValue } from "./rule-utils.js"
+
+import type { Rule, LintOffense } from "../types.js"
+import type { Node, HTMLAttributeNode } from "@herb-tools/core"
+
+class AttributeDoubleQuotesVisitor extends AttributeVisitorMixin {
+  protected checkAttribute(attributeName: string, attributeValue: string | null, attributeNode: HTMLAttributeNode): void {
+    if (!hasAttributeValue(attributeNode)) return
+    if (getAttributeValueQuoteType(attributeNode) !== "single") return
+    if (attributeValue?.includes('"')) return // Single quotes acceptable when value contains double quotes
+
+    this.addOffense(
+      `Attribute \`${attributeName}\` uses single quotes. Prefer double quotes for HTML attribute values: \`${attributeName}="value"\`.`,
+      attributeNode.value!.location,
+      "warning"
+    )
+  }
+}
+
+export class HTMLAttributeDoubleQuotesRule implements Rule {
+  name = "html-attribute-double-quotes"
+
+  check(node: Node): LintOffense[] {
+    const visitor = new AttributeDoubleQuotesVisitor(this.name)
+    visitor.visit(node)
+    return visitor.offenses
+  }
+}

package/src/rules/html-attribute-values-require-quotes.ts

@@ -0,0 +1,30 @@
+import { AttributeVisitorMixin } from "./rule-utils.js"
+
+import type { Rule, LintOffense } from "../types.js"
+import type { HTMLAttributeNode, HTMLAttributeValueNode, Node } from "@herb-tools/core"
+
+class AttributeValuesRequireQuotesVisitor extends AttributeVisitorMixin {
+  protected checkAttribute(attributeName: string, _attributeValue: string | null, attributeNode: HTMLAttributeNode): void {
+    if (attributeNode.value?.type !== "AST_HTML_ATTRIBUTE_VALUE_NODE") return
+
+    const valueNode = attributeNode.value as HTMLAttributeValueNode
+    if (valueNode.quoted) return
+
+    this.addOffense(
+      // TODO: print actual attribute value in message
+      `Attribute value should be quoted: \`${attributeName}="value"\`. Always wrap attribute values in quotes.`,
+      valueNode.location,
+      "error"
+    )
+  }
+}
+
+export class HTMLAttributeValuesRequireQuotesRule implements Rule {
+  name = "html-attribute-values-require-quotes"
+
+  check(node: Node): LintOffense[] {
+    const visitor = new AttributeValuesRequireQuotesVisitor(this.name)
+    visitor.visit(node)
+    return visitor.offenses
+  }
+}

package/src/rules/html-boolean-attributes-no-value.ts

@@ -0,0 +1,27 @@
+import { AttributeVisitorMixin, isBooleanAttribute, hasAttributeValue } from "./rule-utils.js"
+
+import type { Rule, LintOffense } from "../types.js"
+import type { HTMLAttributeNode, Node } from "@herb-tools/core"
+
+class BooleanAttributesNoValueVisitor extends AttributeVisitorMixin {
+  protected checkAttribute(attributeName: string, _attributeValue: string | null, attributeNode: HTMLAttributeNode): void {
+    if (!isBooleanAttribute(attributeName)) return
+    if (!hasAttributeValue(attributeNode)) return
+
+    this.addOffense(
+      `Boolean attribute \`${attributeName}\` should not have a value. Use \`${attributeName}\` instead of \`${attributeName}="${attributeName}"\`.`,
+      attributeNode.value!.location,
+      "error"
+    )
+  }
+}
+
+export class HTMLBooleanAttributesNoValueRule implements Rule {
+  name = "html-boolean-attributes-no-value"
+
+  check(node: Node): LintOffense[] {
+    const visitor = new BooleanAttributesNoValueVisitor(this.name)
+    visitor.visit(node)
+    return visitor.offenses
+  }
+}

package/src/rules/html-img-require-alt.ts

@@ -0,0 +1,42 @@
+import { BaseRuleVisitor, getTagName, hasAttribute } from "./rule-utils.js"
+
+import type { Rule, LintOffense } from "../types.js"
+import type { HTMLOpenTagNode, HTMLSelfCloseTagNode, Node } from "@herb-tools/core"
+
+class ImgRequireAltVisitor extends BaseRuleVisitor {
+  visitHTMLOpenTagNode(node: HTMLOpenTagNode): void {
+    this.checkImgTag(node)
+    super.visitHTMLOpenTagNode(node)
+  }
+
+  visitHTMLSelfCloseTagNode(node: HTMLSelfCloseTagNode): void {
+    this.checkImgTag(node)
+    super.visitHTMLSelfCloseTagNode(node)
+  }
+
+  private checkImgTag(node: HTMLOpenTagNode | HTMLSelfCloseTagNode): void {
+    const tagName = getTagName(node)
+
+    if (tagName !== "img") {
+      return
+    }
+
+    if (!hasAttribute(node, "alt")) {
+      this.addOffense(
+        'Missing required `alt` attribute on `<img>` tag. Add `alt=""` for decorative images or `alt="description"` for informative images.',
+        node.tag_name!.location,
+        "error"
+      )
+    }
+  }
+}
+
+export class HTMLImgRequireAltRule implements Rule {
+  name = "html-img-require-alt"
+
+  check(node: Node): LintOffense[] {
+    const visitor = new ImgRequireAltVisitor(this.name)
+    visitor.visit(node)
+    return visitor.offenses
+  }
+}

package/src/rules/html-no-block-inside-inline.ts

@@ -0,0 +1,84 @@
+import { BaseRuleVisitor, isInlineElement, isBlockElement } from "./rule-utils.js"
+
+import type { Rule, LintOffense } from "../types.js"
+import type { HTMLOpenTagNode, HTMLElementNode, Node } from "@herb-tools/core"
+
+class BlockInsideInlineVisitor extends BaseRuleVisitor {
+  private inlineStack: string[] = []
+
+  private isValidHTMLOpenTag(node: HTMLElementNode): boolean {
+    return !!(node.open_tag && node.open_tag.type === "AST_HTML_OPEN_TAG_NODE")
+  }
+
+  private getElementType(tagName: string): { isInline: boolean; isBlock: boolean; isUnknown: boolean } {
+    const isInline = isInlineElement(tagName)
+    const isBlock = isBlockElement(tagName)
+    const isUnknown = !isInline && !isBlock
+
+    return { isInline, isBlock, isUnknown }
+  }
+
+  private addViolationMessage(tagName: string, isBlock: boolean, openTag: HTMLOpenTagNode): void {
+    const parentInline = this.inlineStack[this.inlineStack.length - 1]
+    const elementType = isBlock ? "Block-level" : "Unknown"
+
+    this.addOffense(
+      `${elementType} element \`<${tagName}>\` cannot be placed inside inline element \`<${parentInline}>\`.`,
+      openTag.tag_name!.location,
+      "error"
+    )
+  }
+
+  private visitInlineElement(node: HTMLElementNode, tagName: string): void {
+    this.inlineStack.push(tagName)
+    super.visitHTMLElementNode(node)
+    this.inlineStack.pop()
+  }
+
+  private visitBlockElement(node: HTMLElementNode): void {
+    const savedStack = [...this.inlineStack]
+    this.inlineStack = []
+    super.visitHTMLElementNode(node)
+    this.inlineStack = savedStack
+  }
+
+  visitHTMLElementNode(node: HTMLElementNode): void {
+    if (!this.isValidHTMLOpenTag(node)) {
+      super.visitHTMLElementNode(node)
+
+      return
+    }
+
+    const openTag = node.open_tag as HTMLOpenTagNode
+    const tagName = openTag.tag_name?.value.toLowerCase()
+
+    if (!tagName) {
+      super.visitHTMLElementNode(node)
+
+      return
+    }
+
+    const { isInline, isBlock, isUnknown } = this.getElementType(tagName)
+
+    if ((isBlock || isUnknown) && this.inlineStack.length > 0) {
+      this.addViolationMessage(tagName, isBlock, openTag)
+    }
+
+    if (isInline) {
+      this.visitInlineElement(node, tagName)
+      return
+    }
+
+    this.visitBlockElement(node)
+  }
+}
+
+export class HTMLNoBlockInsideInlineRule implements Rule {
+  name = "html-no-block-inside-inline"
+
+  check(node: Node): LintOffense[] {
+    const visitor = new BlockInsideInlineVisitor(this.name)
+    visitor.visit(node)
+    return visitor.offenses
+  }
+}

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

@@ -0,0 +1,59 @@
+import { BaseRuleVisitor, forEachAttribute } from "./rule-utils.js"
+
+import type { Rule, LintOffense } from "../types.js"
+import type { HTMLOpenTagNode, HTMLSelfCloseTagNode, HTMLAttributeNameNode, Node } from "@herb-tools/core"
+
+class NoDuplicateAttributesVisitor extends BaseRuleVisitor {
+  visitHTMLOpenTagNode(node: HTMLOpenTagNode): void {
+    this.checkDuplicateAttributes(node)
+    super.visitHTMLOpenTagNode(node)
+  }
+
+  visitHTMLSelfCloseTagNode(node: HTMLSelfCloseTagNode): void {
+    this.checkDuplicateAttributes(node)
+    super.visitHTMLSelfCloseTagNode(node)
+  }
+
+  private checkDuplicateAttributes(node: HTMLOpenTagNode | HTMLSelfCloseTagNode): void {
+    const attributeNames = new Map<string, HTMLAttributeNameNode[]>()
+
+    forEachAttribute(node, (attributeNode) => {
+      if (attributeNode.name?.type !== "AST_HTML_ATTRIBUTE_NAME_NODE") return
+
+      const nameNode = attributeNode.name as HTMLAttributeNameNode
+      if (!nameNode.name) return
+
+      const attributeName = nameNode.name.value.toLowerCase() // HTML attributes are case-insensitive
+
+      if (!attributeNames.has(attributeName)) {
+        attributeNames.set(attributeName, [])
+      }
+
+      attributeNames.get(attributeName)!.push(nameNode)
+    })
+
+    for (const [attributeName, nameNodes] of attributeNames) {
+      if (nameNodes.length > 1) {
+        for (let i = 1; i < nameNodes.length; i++) {
+          const nameNode = nameNodes[i]
+
+          this.addOffense(
+            `Duplicate attribute \`${attributeName}\` found on tag. Remove the duplicate occurrence.`,
+            nameNode.location,
+            "error"
+          )
+        }
+      }
+    }
+  }
+}
+
+export class HTMLNoDuplicateAttributesRule implements Rule {
+  name = "html-no-duplicate-attributes"
+
+  check(node: Node): LintOffense[] {
+    const visitor = new NoDuplicateAttributesVisitor(this.name)
+    visitor.visit(node)
+    return visitor.offenses
+  }
+}

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

@@ -0,0 +1,185 @@
+import { BaseRuleVisitor, getTagName, getAttributes, findAttributeByName, getAttributeValue, HEADING_TAGS } from "./rule-utils.js"
+
+import type { Rule, LintOffense } from "../types.js"
+import type { HTMLElementNode, HTMLOpenTagNode, HTMLSelfCloseTagNode, Node, LiteralNode, HTMLTextNode } from "@herb-tools/core"
+
+class NoEmptyHeadingsVisitor extends BaseRuleVisitor {
+  visitHTMLElementNode(node: HTMLElementNode): void {
+    this.checkHeadingElement(node)
+    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") {
+      return
+    }
+
+    const openTag = node.open_tag as HTMLOpenTagNode
+    const tagName = getTagName(openTag)
+
+    if (!tagName) {
+      return
+    }
+
+    const isStandardHeading = HEADING_TAGS.has(tagName)
+    const isAriaHeading = this.hasHeadingRole(openTag)
+
+    if (!isStandardHeading && !isAriaHeading) {
+      return
+    }
+
+    if (this.isEmptyHeading(node)) {
+      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.location,
+        "error"
+      )
+    }
+  }
+
+  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) {
+      return true
+    }
+
+    // Check if all content is just whitespace or inaccessible
+    let hasAccessibleContent = false
+
+    for (const child of node.body) {
+      if (child.type === "AST_LITERAL_NODE") {
+        const literalNode = child as LiteralNode
+
+        if (literalNode.content.trim().length > 0) {
+          hasAccessibleContent = true
+          break
+        }
+      } else if (child.type === "AST_HTML_TEXT_NODE") {
+        const textNode = child as HTMLTextNode
+
+        if (textNode.content.trim().length > 0) {
+          hasAccessibleContent = true
+          break
+        }
+      } else if (child.type === "AST_HTML_ELEMENT_NODE") {
+        const elementNode = child as HTMLElementNode
+
+        // Check if this element is accessible (not aria-hidden="true")
+        if (this.isElementAccessible(elementNode)) {
+          hasAccessibleContent = true
+          break
+        }
+      } else {
+        // If there's any non-literal/non-text/non-element content (like ERB), consider it accessible
+        hasAccessibleContent = true
+        break
+      }
+    }
+
+    return !hasAccessibleContent
+  }
+
+  private hasHeadingRole(node: HTMLOpenTagNode | HTMLSelfCloseTagNode): boolean {
+    const attributes = getAttributes(node)
+    const roleAttribute = findAttributeByName(attributes, "role")
+
+    if (!roleAttribute) {
+      return false
+    }
+
+    const roleValue = getAttributeValue(roleAttribute)
+    return roleValue === "heading"
+  }
+
+  private isElementAccessible(node: HTMLElementNode): boolean {
+    // Check if the element has aria-hidden="true"
+    if (!node.open_tag || node.open_tag.type !== "AST_HTML_OPEN_TAG_NODE") {
+      return true
+    }
+
+    const openTag = node.open_tag as HTMLOpenTagNode
+    const attributes = getAttributes(openTag)
+    const ariaHiddenAttribute = findAttributeByName(attributes, "aria-hidden")
+
+    if (ariaHiddenAttribute) {
+      const ariaHiddenValue = getAttributeValue(ariaHiddenAttribute)
+
+      if (ariaHiddenValue === "true") {
+        return false
+      }
+    }
+
+    // Recursively check if the element has any accessible content
+    if (!node.body || node.body.length === 0) {
+      return false
+    }
+
+    for (const child of node.body) {
+      if (child.type === "AST_LITERAL_NODE") {
+        const literalNode = child as LiteralNode
+        if (literalNode.content.trim().length > 0) {
+          return true
+        }
+      } else if (child.type === "AST_HTML_TEXT_NODE") {
+        const textNode = child as HTMLTextNode
+        if (textNode.content.trim().length > 0) {
+          return true
+        }
+      } else if (child.type === "AST_HTML_ELEMENT_NODE") {
+        const elementNode = child as HTMLElementNode
+        if (this.isElementAccessible(elementNode)) {
+          return true
+        }
+      } else {
+        // If there's any non-literal/non-text/non-element content (like ERB), consider it accessible
+        return true
+      }
+    }
+
+    return false
+  }
+}
+
+export class HTMLNoEmptyHeadingsRule implements Rule {
+  name = "html-no-empty-headings"
+
+  check(node: Node): LintOffense[] {
+    const visitor = new NoEmptyHeadingsVisitor(this.name)
+    visitor.visit(node)
+    return visitor.offenses
+  }
+}