@herb-tools/core 0.8.10 → 0.9.1

package/src/ast-utils.ts

@@ -14,8 +14,11 @@ import {
   HTMLElementNode,
   HTMLOpenTagNode,
   HTMLCloseTagNode,
+  HTMLAttributeNode,
   HTMLAttributeNameNode,
-  HTMLCommentNode
+  HTMLAttributeValueNode,
+  HTMLCommentNode,
+  WhitespaceNode
 } from "./nodes.js"
 
 import {
@@ -24,11 +27,21 @@ import {
   isERBNode,
   isERBContentNode,
   isHTMLCommentNode,
+  isHTMLElementNode,
+  isHTMLOpenTagNode,
+  isHTMLTextNode,
+  isWhitespaceNode,
+  isHTMLAttributeNameNode,
+  isHTMLAttributeValueNode,
   areAllOfType,
-  filterLiteralNodes
+  filterLiteralNodes,
+  filterHTMLAttributeNodes
 } from "./node-type-guards.js"
 
-import type { Location } from "./location.js"
+import { Location } from "./location.js"
+import { Range } from "./range.js"
+import { Token } from "./token.js"
+
 import type { Position } from "./position.js"
 
 export type ERBOutputNode = ERBNode & {
@@ -60,7 +73,7 @@ export function isERBCommentNode(node: Node): node is ERBCommentNode {
   if (!isERBNode(node)) return false
   if (!node.tag_opening?.value) return false
 
-  return node.tag_opening?.value === "<%#" || (node.tag_opening?.value !== "<%#" && (node.content?.value || "").trimStart().startsWith("#"))
+  return node.tag_opening?.value === "<%#" || (node.tag_opening?.value !== "<%#" && (node.content?.value || "").trimStart().startsWith("#"))
 }
 
 
@@ -175,7 +188,7 @@ export function hasStaticAttributeName(attributeNameNode: HTMLAttributeNameNode)
 /**
  * Checks if an HTML attribute name node has dynamic content (contains ERB)
  */
-export function hasDynamicAttributeName(attributeNameNode: HTMLAttributeNameNode): boolean {
+export function hasDynamicAttributeNameNode(attributeNameNode: HTMLAttributeNameNode): boolean {
   if (!attributeNameNode.children) {
     return false
   }
@@ -208,10 +221,26 @@ export function getCombinedAttributeName(attributeNameNode: HTMLAttributeNameNod
 }
 
 /**
- * Gets the tag name of an HTML element node
+ * Gets the tag name of an HTML element, open tag, or close tag node.
+ * Returns null if the node is null/undefined.
  */
-export function getTagName(node: HTMLElementNode | HTMLOpenTagNode | HTMLCloseTagNode): string {
-  return node.tag_name?.value ?? ""
+export function getTagName(node: HTMLElementNode | HTMLOpenTagNode | HTMLCloseTagNode): string
+export function getTagName(node: HTMLElementNode | HTMLOpenTagNode | HTMLCloseTagNode | null | undefined): string | null
+export function getTagName(node: HTMLElementNode | HTMLOpenTagNode | HTMLCloseTagNode | null | undefined): string | null {
+  if (!node) return null
+
+  return node.tag_name?.value ?? null
+}
+
+/**
+ * Gets the lowercased tag name of an HTML element, open tag, or close tag node.
+ * Similar to `Element.localName` in the DOM API.
+ * Returns null if the node is null/undefined.
+ */
+export function getTagLocalName(node: HTMLElementNode | HTMLOpenTagNode | HTMLCloseTagNode): string
+export function getTagLocalName(node: HTMLElementNode | HTMLOpenTagNode | HTMLCloseTagNode | null | undefined): string | null
+export function getTagLocalName(node: HTMLElementNode | HTMLOpenTagNode | HTMLCloseTagNode | null | undefined): string | null {
+  return getTagName(node)?.toLowerCase() ?? null
 }
 
 /**
@@ -221,6 +250,365 @@ export function isCommentNode(node: Node): node is HTMLCommentNode | ERBCommentN
   return isHTMLCommentNode(node) || isERBCommentNode(node)
 }
 
+/**
+ * Gets the open tag node from an HTMLElementNode, handling both regular and conditional open tags.
+ * For conditional open tags, returns null.
+ * If given an HTMLOpenTagNode directly, returns it as-is.
+ */
+export function getOpenTag(node: HTMLElementNode | HTMLOpenTagNode | null | undefined): HTMLOpenTagNode | null {
+  if (!node) return null
+  if (isHTMLOpenTagNode(node)) return node
+  if (isHTMLElementNode(node)) return isHTMLOpenTagNode(node.open_tag) ? node.open_tag : null
+
+  return null
+}
+
+/**
+ * Gets attributes from an HTMLElementNode or HTMLOpenTagNode
+ */
+export function getAttributes(node: HTMLElementNode | HTMLOpenTagNode | null | undefined): HTMLAttributeNode[] {
+  const openTag = getOpenTag(node)
+
+  return openTag ? filterHTMLAttributeNodes(openTag.children) : []
+}
+
+/**
+ * Gets the attribute name from an HTMLAttributeNode (lowercased)
+ * Returns null if the attribute name contains dynamic content (ERB)
+ */
+export function getAttributeName(attributeNode: HTMLAttributeNode, lowercase = true): string | null {
+  if (!isHTMLAttributeNameNode(attributeNode.name)) return null
+
+  const staticName = getStaticAttributeName(attributeNode.name)
+
+  if (!lowercase) return staticName
+
+  return staticName ? staticName.toLowerCase() : null
+}
+
+/**
+ * Checks if an attribute value contains only static content (no ERB).
+ * Accepts an HTMLAttributeNode directly, or an element/open tag + attribute name.
+ * Returns false for null/undefined input.
+ */
+export function hasStaticAttributeValue(attributeNode: HTMLAttributeNode | null | undefined): boolean
+export function hasStaticAttributeValue(node: HTMLElementNode | HTMLOpenTagNode | null | undefined, attributeName: string): boolean
+export function hasStaticAttributeValue(nodeOrAttribute: HTMLAttributeNode | HTMLElementNode | HTMLOpenTagNode | null | undefined, attributeName?: string): boolean {
+  const attributeNode = attributeName
+    ? getAttribute(nodeOrAttribute as HTMLElementNode | HTMLOpenTagNode, attributeName)
+    : nodeOrAttribute as HTMLAttributeNode | null | undefined
+
+  if (!attributeNode?.value?.children) return false
+
+  return attributeNode.value.children.every(isLiteralNode)
+}
+
+/**
+ * Gets the static string value of an attribute (returns null if it contains ERB).
+ * Accepts an HTMLAttributeNode directly, or an element/open tag + attribute name.
+ * Returns null for null/undefined input.
+ */
+export function getStaticAttributeValue(attributeNode: HTMLAttributeNode | null | undefined): string | null
+export function getStaticAttributeValue(node: HTMLElementNode | HTMLOpenTagNode | null | undefined, attributeName: string): string | null
+export function getStaticAttributeValue(nodeOrAttribute: HTMLAttributeNode | HTMLElementNode | HTMLOpenTagNode | null | undefined, attributeName?: string): string | null {
+  const attributeNode = attributeName
+    ? getAttribute(nodeOrAttribute as HTMLElementNode | HTMLOpenTagNode, attributeName)
+    : nodeOrAttribute as HTMLAttributeNode | null | undefined
+
+  if (!attributeNode) return null
+  if (!hasStaticAttributeValue(attributeNode)) return null
+
+  const valueNode = attributeNode.value
+  if (!valueNode) return null
+
+  return filterLiteralNodes(valueNode.children).map(child => child.content).join("") || ""
+}
+
+/**
+ * Attributes whose values are space-separated token lists.
+ */
+export const TOKEN_LIST_ATTRIBUTES = new Set([
+  "class", "data-controller", "data-action",
+])
+
+/**
+ * Splits a space-separated attribute value into individual tokens.
+ * Accepts a string, or an element/open tag + attribute name to look up.
+ * Returns an empty array for null/undefined/empty input.
+ */
+export function getTokenList(value: string | null | undefined): string[]
+export function getTokenList(node: HTMLElementNode | HTMLOpenTagNode | null | undefined, attributeName: string): string[]
+export function getTokenList(valueOrNode: string | HTMLElementNode | HTMLOpenTagNode | null | undefined, attributeName?: string): string[] {
+  const value = attributeName
+    ? getStaticAttributeValue(valueOrNode as HTMLElementNode | HTMLOpenTagNode, attributeName)
+    : valueOrNode as string | null | undefined
+
+  if (!value) return []
+
+  return value.trim().split(/\s+/).filter(token => token.length > 0)
+}
+
+/**
+ * Finds an attribute by name in a list of attribute nodes
+ */
+export function findAttributeByName(attributes: Node[], attributeName: string): HTMLAttributeNode | null {
+  for (const attribute of filterHTMLAttributeNodes(attributes)) {
+    const name = getAttributeName(attribute)
+
+    if (name === attributeName.toLowerCase()) {
+      return attribute
+    }
+  }
+
+  return null
+}
+
+/**
+ * Gets a specific attribute from an HTMLElementNode or HTMLOpenTagNode by name
+ */
+export function getAttribute(node: HTMLElementNode | HTMLOpenTagNode | null | undefined, attributeName: string): HTMLAttributeNode | null {
+  const attributes = getAttributes(node)
+
+  return findAttributeByName(attributes, attributeName)
+}
+
+/**
+ * Checks if an element or open tag has a specific attribute
+ */
+export function hasAttribute(node: HTMLElementNode | HTMLOpenTagNode | null | undefined, attributeName: string): boolean {
+  if (!node) return false
+
+  return getAttribute(node, attributeName) !== null
+}
+
+/**
+ * Checks if an attribute has a dynamic (ERB-containing) name.
+ */
+export function hasDynamicAttributeName(attributeNode: HTMLAttributeNode): boolean {
+  if (!isHTMLAttributeNameNode(attributeNode.name)) return false
+
+  return hasDynamicAttributeNameNode(attributeNode.name)
+}
+
+/**
+ * Gets the combined string representation of an attribute name (including ERB syntax).
+ * Accepts an HTMLAttributeNode (wraps the core HTMLAttributeNameNode-level check).
+ */
+export function getCombinedAttributeNameString(attributeNode: HTMLAttributeNode): string {
+  if (!isHTMLAttributeNameNode(attributeNode.name)) return ""
+
+  return getCombinedAttributeName(attributeNode.name)
+}
+
+/**
+ * Checks if an attribute value contains dynamic content (ERB)
+ */
+export function hasDynamicAttributeValue(attributeNode: HTMLAttributeNode): boolean {
+  if (!attributeNode.value?.children) return false
+
+  return attributeNode.value.children.some(isERBContentNode)
+}
+
+/**
+ * Gets the value nodes array from an attribute for dynamic inspection
+ */
+export function getAttributeValueNodes(attributeNode: HTMLAttributeNode): Node[] {
+  return attributeNode.value?.children || []
+}
+
+/**
+ * Checks if an attribute value contains any static content (for validation purposes)
+ */
+export function hasStaticAttributeValueContent(attributeNode: HTMLAttributeNode): boolean {
+  return hasStaticContent(getAttributeValueNodes(attributeNode))
+}
+
+/**
+ * Gets the static content of an attribute value (all literal parts combined).
+ * Unlike getStaticAttributeValue, this extracts only the static portions from mixed content.
+ * Returns the concatenated literal content, or null if no literal nodes exist.
+ */
+export function getStaticAttributeValueContent(attributeNode: HTMLAttributeNode): string | null {
+  return getStaticContentFromNodes(getAttributeValueNodes(attributeNode))
+}
+
+/**
+ * Gets the combined attribute value including both static text and ERB tag syntax.
+ * For ERB nodes, includes the full tag syntax (e.g., "<%= foo %>").
+ * Returns null if the attribute has no value.
+ */
+export function getAttributeValue(attributeNode: HTMLAttributeNode): string | null {
+  const valueNode = attributeNode.value
+  if (!valueNode) return null
+
+  if (valueNode.type !== "AST_HTML_ATTRIBUTE_VALUE_NODE" || !valueNode.children?.length) {
+    return null
+  }
+
+  let result = ""
+
+  for (const child of valueNode.children) {
+    if (isERBContentNode(child)) {
+      if (child.content) {
+        result += `${child.tag_opening?.value}${child.content.value}${child.tag_closing?.value}`
+      }
+    } else if (isLiteralNode(child)) {
+      result += child.content
+    }
+  }
+
+  return result
+}
+
+/**
+ * Checks if an attribute has a value node
+ */
+export function hasAttributeValue(attributeNode: HTMLAttributeNode): boolean {
+  return isHTMLAttributeValueNode(attributeNode.value)
+}
+
+/**
+ * Gets the quote type used for an attribute value
+ */
+export function getAttributeValueQuoteType(node: HTMLAttributeNode | HTMLAttributeValueNode): "single" | "double" | "none" | null {
+  const valueNode = isHTMLAttributeValueNode(node) ? node : node.value
+  if (!valueNode) return null
+
+  if (valueNode.quoted && valueNode.open_quote) {
+    return valueNode.open_quote.value === '"' ? "double" : "single"
+  }
+
+  return "none"
+}
+
+/**
+ * Checks if an attribute value is quoted
+ */
+export function isAttributeValueQuoted(attributeNode: HTMLAttributeNode): boolean {
+  if (!isHTMLAttributeValueNode(attributeNode.value)) return false
+
+  return !!attributeNode.value.quoted
+}
+
+/**
+ * Iterates over all attributes of an element or open tag node
+ */
+export function forEachAttribute(node: HTMLElementNode | HTMLOpenTagNode, callback: (attributeNode: HTMLAttributeNode) => void): void {
+  for (const attribute of getAttributes(node)) {
+    callback(attribute)
+  }
+}
+
+// --- Class Name Grouping Utilities ---
+
+/**
+ * Checks if a node is a whitespace-only literal or text node (no visible content)
+ */
+export function isPureWhitespaceNode(node: Node): boolean {
+  if (isWhitespaceNode(node)) return true
+  if (isLiteralNode(node)) return !node.content.trim()
+  if (isHTMLTextNode(node)) return !(node.content ?? "").trim()
+
+  return false
+}
+
+/**
+ * Splits literal nodes at whitespace boundaries into separate nodes.
+ * Non-literal nodes are passed through unchanged.
+ *
+ * For example, a literal `"bg-blue-500 text-white"` becomes two literals:
+ * `"bg-blue-500"` and `" "` and `"text-white"`.
+ */
+export function splitLiteralsAtWhitespace(nodes: Node[]): Node[] {
+  const result: Node[] = []
+
+  for (const node of nodes) {
+    if (isLiteralNode(node)) {
+      const parts = node.content.match(/(\S+|\s+)/g) || []
+
+      for (const part of parts) {
+        result.push(new LiteralNode({
+          type: "AST_LITERAL_NODE",
+          content: part,
+          errors: [],
+          location: node.location
+        }))
+      }
+    } else {
+      result.push(node)
+    }
+  }
+
+  return result
+}
+
+/**
+ * Groups split nodes into "class groups" where each group represents a single
+ * class name (possibly spanning multiple nodes when ERB is interpolated).
+ *
+ * For example, `text-<%= color %>-500 bg-blue-500` produces two groups:
+ *   - [`text-`, ERB, `-500`] (interpolated class)
+ *   - [`bg-blue-500`] (static class)
+ *
+ * The key heuristic: a hyphen at a node boundary means the nodes are part of
+ * the same class name (e.g., `bg-` + ERB + `-500`), while whitespace means
+ * a new class name starts.
+ */
+export function groupNodesByClass(nodes: Node[]): Node[][] {
+  if (nodes.length === 0) return []
+
+  const groups: Node[][] = []
+  let currentGroup: Node[] = []
+
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i]
+    const previousNode = i > 0 ? nodes[i - 1] : null
+
+    let startNewGroup = false
+
+    if (currentGroup.length === 0) {
+      startNewGroup = false
+    } else if (isLiteralNode(node)) {
+      if (/^\s/.test(node.content)) {
+        startNewGroup = true
+      } else if (/^-/.test(node.content)) {
+        startNewGroup = false
+      } else if (previousNode && !isLiteralNode(previousNode)) {
+        startNewGroup = true
+      } else if (currentGroup.every(member => isPureWhitespaceNode(member))) {
+        startNewGroup = true
+      }
+    } else {
+      if (previousNode && isLiteralNode(previousNode)) {
+        if (/\s$/.test(previousNode.content)) {
+          startNewGroup = true
+        } else if (/-$/.test(previousNode.content)) {
+          startNewGroup = false
+        } else {
+          startNewGroup = true
+        }
+      } else if (previousNode && !isLiteralNode(previousNode)) {
+        startNewGroup = false
+      }
+    }
+
+    if (startNewGroup && currentGroup.length > 0) {
+      groups.push(currentGroup)
+      currentGroup = []
+    }
+
+    currentGroup.push(node)
+  }
+
+  if (currentGroup.length > 0) {
+    groups.push(currentGroup)
+  }
+
+  return groups
+}
+
+// --- Position Utilities ---
+
 /**
  * Compares two positions to determine if the first comes before the second
  * Returns true if pos1 comes before pos2 in source order
@@ -316,3 +704,171 @@ export function getNodesAfterPosition<T extends Node>(nodes: T[], position: Posi
     node.location && isPositionAfter(node.location.start, position, inclusive)
   )
 }
+
+/**
+ * Checks if two attributes are structurally equivalent (same name and value),
+ * ignoring positional data like location and range.
+ */
+export function isEquivalentAttribute(first: HTMLAttributeNode, second: HTMLAttributeNode): boolean {
+  const firstName = getAttributeName(first)
+  const secondName = getAttributeName(second)
+
+  if (firstName !== secondName) return false
+
+  if (firstName && TOKEN_LIST_ATTRIBUTES.has(firstName)) {
+    const firstTokens = getTokenList(getAttributeValue(first))
+    const secondTokens = getTokenList(getAttributeValue(second))
+
+    if (firstTokens.length !== secondTokens.length) return false
+
+    const sortedFirst = [...firstTokens].sort()
+    const sortedSecond = [...secondTokens].sort()
+
+    return sortedFirst.every((token, index) => token === sortedSecond[index])
+  }
+
+  return getAttributeValue(first) === getAttributeValue(second)
+}
+
+/**
+ * Checks if two open tags are structurally equivalent (same tag name and attributes),
+ * ignoring positional data like location and range.
+ */
+export function isEquivalentOpenTag(first: HTMLOpenTagNode, second: HTMLOpenTagNode): boolean {
+  if (first.tag_name?.value !== second.tag_name?.value) return false
+
+  const firstAttributes = getAttributes(first)
+  const secondAttributes = getAttributes(second)
+
+  if (firstAttributes.length !== secondAttributes.length) return false
+
+  return firstAttributes.every((attribute) =>
+    secondAttributes.some((other) => isEquivalentAttribute(attribute, other))
+  )
+}
+
+/**
+ * Checks if two elements have structurally equivalent open tags (same tag name and attributes),
+ * ignoring positional data like location and range. Does not compare body or close tag.
+ */
+export function isEquivalentElement(first: HTMLElementNode, second: HTMLElementNode): boolean {
+  if (!isHTMLOpenTagNode(first.open_tag) || !isHTMLOpenTagNode(second.open_tag)) return false
+
+  return isEquivalentOpenTag(first.open_tag, second.open_tag)
+}
+
+// --- AST Mutation Utilities ---
+
+const CHILD_ARRAY_PROPS = ["children", "body", "statements", "conditions"]
+const LINKED_NODE_PROPS = ["subsequent", "else_clause"]
+
+/**
+ * Finds the array containing a target node in the AST, along with its index.
+ * Traverses child arrays and linked node properties (e.g., `subsequent`, `else_clause`).
+ *
+ * Useful for autofix operations that need to splice nodes in/out of their parent array.
+ *
+ * @param root - The root node to search from
+ * @param target - The node to find
+ * @returns The containing array and the target's index, or null if not found
+ */
+export function findParentArray(root: Node, target: Node): { array: Node[], index: number } | null {
+  const search = (node: Node): { array: Node[], index: number } | null => {
+    const record = node as Record<string, any>
+
+    for (const prop of CHILD_ARRAY_PROPS) {
+      const array = record[prop]
+
+      if (Array.isArray(array)) {
+        const index = array.indexOf(target)
+
+        if (index !== -1) {
+          return { array, index }
+        }
+      }
+    }
+
+    for (const prop of CHILD_ARRAY_PROPS) {
+      const array = record[prop]
+
+      if (Array.isArray(array)) {
+        for (const child of array) {
+          if (child && typeof child === 'object' && 'type' in child) {
+            const result = search(child)
+
+            if (result) {
+              return result
+            }
+          }
+        }
+      }
+    }
+
+    for (const prop of LINKED_NODE_PROPS) {
+      const value = record[prop]
+
+      if (value && typeof value === 'object' && 'type' in value) {
+        const result = search(value)
+
+        if (result) {
+          return result
+        }
+      }
+    }
+
+    return null
+  }
+
+  return search(root)
+}
+
+/**
+ * Removes a node from an array, also removing an adjacent preceding
+ * whitespace-only literal if present.
+ */
+export function removeNodeFromArray(array: Node[], node: Node): void {
+  const index = array.indexOf(node)
+  if (index === -1) return
+
+  if (index > 0 && isPureWhitespaceNode(array[index - 1])) {
+    array.splice(index - 1, 2)
+  } else {
+    array.splice(index, 1)
+  }
+}
+
+/**
+ * Replaces an element in an array with its body (children), effectively unwrapping it.
+ */
+export function replaceNodeWithBody(array: Node[], element: HTMLElementNode): void {
+  const index = array.indexOf(element)
+  if (index === -1) return
+
+  array.splice(index, 1, ...element.body)
+}
+
+/**
+ * Creates a synthetic LiteralNode with the given content and zero location.
+ * Useful for inserting whitespace or newlines during AST mutations.
+ */
+export function createLiteral(content: string): LiteralNode {
+  return new LiteralNode({
+    type: "AST_LITERAL_NODE",
+    content,
+    location: Location.zero,
+    errors: [],
+  })
+}
+
+export function createSyntheticToken(value: string, type = "TOKEN_SYNTHETIC"): Token {
+  return new Token(value, Range.zero, Location.zero, type)
+}
+
+export function createWhitespaceNode(): WhitespaceNode {
+  return new WhitespaceNode({
+    type: "AST_WHITESPACE_NODE",
+    location: Location.zero,
+    errors: [],
+    value: createSyntheticToken(" "),
+  })
+}

package/src/backend.ts

@@ -1,17 +1,18 @@
 import type { SerializedParseResult } from "./parse-result.js"
 import type { SerializedLexResult } from "./lex-result.js"
-import type { ParserOptions } from "./parser-options.js"
+import type { ParseOptions } from "./parser-options.js"
+import type { ExtractRubyOptions } from "./extract-ruby-options.js"
 
 interface LibHerbBackendFunctions {
   lex: (source: string) => SerializedLexResult
-  lexFile: (path: string) => SerializedLexResult
 
-  parse: (source: string, options?: ParserOptions) => SerializedParseResult
-  parseFile: (path: string) => SerializedParseResult
+  parse: (source: string, options?: ParseOptions) => SerializedParseResult
 
-  extractRuby: (source: string) => string
+  extractRuby: (source: string, options?: ExtractRubyOptions) => string
   extractHTML: (source: string) => string
 
+  parseRuby: (source: string) => Uint8Array | null
+
   version: () => string
 }
 
@@ -20,10 +21,9 @@ export type BackendPromise = () => Promise<LibHerbBackend>
 const expectedFunctions = [
   "parse",
   "lex",
-  "parseFile",
-  "lexFile",
   "extractRuby",
   "extractHTML",
+  "parseRuby",
   "version",
 ] as const
 

package/src/diagnostic.ts

@@ -1,6 +1,7 @@
 import { Location, SerializedLocation } from "./location.js"
 
 export type DiagnosticSeverity = "error" | "warning" | "info" | "hint"
+export type DiagnosticTag = "unnecessary" | "deprecated"
 
 /**
  * Base interface for all diagnostic information in Herb tooling.
@@ -32,6 +33,11 @@ export interface Diagnostic {
    * Optional source that generated this diagnostic (e.g., "parser", "linter", "lexer")
    */
   source?: string
+
+  /**
+   * Optional diagnostic tags for additional metadata (e.g., "unnecessary", "deprecated")
+   */
+  tags?: DiagnosticTag[]
 }
 
 /**
@@ -43,6 +49,7 @@ export interface SerializedDiagnostic {
   severity: DiagnosticSeverity
   code?: string
   source?: string
+  tags?: DiagnosticTag[]
 }
 
 export type MonacoSeverity = "error" | "warning" | "info"