@herb-tools/core 0.8.10 → 0.9.1

package/dist/types/ast-utils.d.ts

@@ -1,5 +1,6 @@
-import { Node, ERBNode, ERBContentNode, HTMLElementNode, HTMLOpenTagNode, HTMLCloseTagNode, HTMLAttributeNameNode, HTMLCommentNode } from "./nodes.js";
-import type { Location } from "./location.js";
+import { Node, LiteralNode, ERBNode, ERBContentNode, HTMLElementNode, HTMLOpenTagNode, HTMLCloseTagNode, HTMLAttributeNode, HTMLAttributeNameNode, HTMLAttributeValueNode, HTMLCommentNode, WhitespaceNode } from "./nodes.js";
+import { Location } from "./location.js";
+import { Token } from "./token.js";
 import type { Position } from "./position.js";
 export type ERBOutputNode = ERBNode & {
     tag_opening: {
@@ -68,7 +69,7 @@ export declare function hasStaticAttributeName(attributeNameNode: HTMLAttributeN
 /**
  * Checks if an HTML attribute name node has dynamic content (contains ERB)
  */
-export declare function hasDynamicAttributeName(attributeNameNode: HTMLAttributeNameNode): boolean;
+export declare function hasDynamicAttributeNameNode(attributeNameNode: HTMLAttributeNameNode): boolean;
 /**
  * Gets the static string value of an HTML attribute name node
  * Returns null if the attribute name contains dynamic content (ERB)
@@ -80,13 +81,148 @@ export declare function getStaticAttributeName(attributeNameNode: HTMLAttributeN
  */
 export declare function getCombinedAttributeName(attributeNameNode: HTMLAttributeNameNode): string;
 /**
- * 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 declare function getTagName(node: HTMLElementNode | HTMLOpenTagNode | HTMLCloseTagNode): string;
+export declare function getTagName(node: HTMLElementNode | HTMLOpenTagNode | HTMLCloseTagNode | null | undefined): string | 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 declare function getTagLocalName(node: HTMLElementNode | HTMLOpenTagNode | HTMLCloseTagNode): string;
+export declare function getTagLocalName(node: HTMLElementNode | HTMLOpenTagNode | HTMLCloseTagNode | null | undefined): string | null;
 /**
  * Check if a node is a comment (HTML comment or ERB comment)
  */
 export declare function isCommentNode(node: Node): node is HTMLCommentNode | ERBCommentNode;
+/**
+ * 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 declare function getOpenTag(node: HTMLElementNode | HTMLOpenTagNode | null | undefined): HTMLOpenTagNode | null;
+/**
+ * Gets attributes from an HTMLElementNode or HTMLOpenTagNode
+ */
+export declare function getAttributes(node: HTMLElementNode | HTMLOpenTagNode | null | undefined): HTMLAttributeNode[];
+/**
+ * Gets the attribute name from an HTMLAttributeNode (lowercased)
+ * Returns null if the attribute name contains dynamic content (ERB)
+ */
+export declare function getAttributeName(attributeNode: HTMLAttributeNode, lowercase?: boolean): string | 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 declare function hasStaticAttributeValue(attributeNode: HTMLAttributeNode | null | undefined): boolean;
+export declare function hasStaticAttributeValue(node: HTMLElementNode | HTMLOpenTagNode | null | undefined, attributeName: string): boolean;
+/**
+ * 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 declare function getStaticAttributeValue(attributeNode: HTMLAttributeNode | null | undefined): string | null;
+export declare function getStaticAttributeValue(node: HTMLElementNode | HTMLOpenTagNode | null | undefined, attributeName: string): string | null;
+/**
+ * Attributes whose values are space-separated token lists.
+ */
+export declare const TOKEN_LIST_ATTRIBUTES: Set<string>;
+/**
+ * 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 declare function getTokenList(value: string | null | undefined): string[];
+export declare function getTokenList(node: HTMLElementNode | HTMLOpenTagNode | null | undefined, attributeName: string): string[];
+/**
+ * Finds an attribute by name in a list of attribute nodes
+ */
+export declare function findAttributeByName(attributes: Node[], attributeName: string): HTMLAttributeNode | null;
+/**
+ * Gets a specific attribute from an HTMLElementNode or HTMLOpenTagNode by name
+ */
+export declare function getAttribute(node: HTMLElementNode | HTMLOpenTagNode | null | undefined, attributeName: string): HTMLAttributeNode | null;
+/**
+ * Checks if an element or open tag has a specific attribute
+ */
+export declare function hasAttribute(node: HTMLElementNode | HTMLOpenTagNode | null | undefined, attributeName: string): boolean;
+/**
+ * Checks if an attribute has a dynamic (ERB-containing) name.
+ */
+export declare function hasDynamicAttributeName(attributeNode: HTMLAttributeNode): boolean;
+/**
+ * Gets the combined string representation of an attribute name (including ERB syntax).
+ * Accepts an HTMLAttributeNode (wraps the core HTMLAttributeNameNode-level check).
+ */
+export declare function getCombinedAttributeNameString(attributeNode: HTMLAttributeNode): string;
+/**
+ * Checks if an attribute value contains dynamic content (ERB)
+ */
+export declare function hasDynamicAttributeValue(attributeNode: HTMLAttributeNode): boolean;
+/**
+ * Gets the value nodes array from an attribute for dynamic inspection
+ */
+export declare function getAttributeValueNodes(attributeNode: HTMLAttributeNode): Node[];
+/**
+ * Checks if an attribute value contains any static content (for validation purposes)
+ */
+export declare function hasStaticAttributeValueContent(attributeNode: HTMLAttributeNode): boolean;
+/**
+ * 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 declare function getStaticAttributeValueContent(attributeNode: HTMLAttributeNode): string | null;
+/**
+ * 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 declare function getAttributeValue(attributeNode: HTMLAttributeNode): string | null;
+/**
+ * Checks if an attribute has a value node
+ */
+export declare function hasAttributeValue(attributeNode: HTMLAttributeNode): boolean;
+/**
+ * Gets the quote type used for an attribute value
+ */
+export declare function getAttributeValueQuoteType(node: HTMLAttributeNode | HTMLAttributeValueNode): "single" | "double" | "none" | null;
+/**
+ * Checks if an attribute value is quoted
+ */
+export declare function isAttributeValueQuoted(attributeNode: HTMLAttributeNode): boolean;
+/**
+ * Iterates over all attributes of an element or open tag node
+ */
+export declare function forEachAttribute(node: HTMLElementNode | HTMLOpenTagNode, callback: (attributeNode: HTMLAttributeNode) => void): void;
+/**
+ * Checks if a node is a whitespace-only literal or text node (no visible content)
+ */
+export declare function isPureWhitespaceNode(node: Node): boolean;
+/**
+ * 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 declare function splitLiteralsAtWhitespace(nodes: Node[]): Node[];
+/**
+ * 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 declare function groupNodesByClass(nodes: Node[]): Node[][];
 /**
  * Compares two positions to determine if they are equal
  * Returns true if pos1 and pos2 are at the same location
@@ -136,3 +272,48 @@ export declare function getNodesBeforePosition<T extends Node>(nodes: T[], posit
  * @param inclusive - If true, includes nodes that start exactly at the position (default: true, matching typical boundary behavior)
  */
 export declare function getNodesAfterPosition<T extends Node>(nodes: T[], position: Position, inclusive?: boolean): T[];
+/**
+ * Checks if two attributes are structurally equivalent (same name and value),
+ * ignoring positional data like location and range.
+ */
+export declare function isEquivalentAttribute(first: HTMLAttributeNode, second: HTMLAttributeNode): boolean;
+/**
+ * Checks if two open tags are structurally equivalent (same tag name and attributes),
+ * ignoring positional data like location and range.
+ */
+export declare function isEquivalentOpenTag(first: HTMLOpenTagNode, second: HTMLOpenTagNode): boolean;
+/**
+ * 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 declare function isEquivalentElement(first: HTMLElementNode, second: HTMLElementNode): boolean;
+/**
+ * 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 declare function findParentArray(root: Node, target: Node): {
+    array: Node[];
+    index: number;
+} | null;
+/**
+ * Removes a node from an array, also removing an adjacent preceding
+ * whitespace-only literal if present.
+ */
+export declare function removeNodeFromArray(array: Node[], node: Node): void;
+/**
+ * Replaces an element in an array with its body (children), effectively unwrapping it.
+ */
+export declare function replaceNodeWithBody(array: Node[], element: HTMLElementNode): void;
+/**
+ * Creates a synthetic LiteralNode with the given content and zero location.
+ * Useful for inserting whitespace or newlines during AST mutations.
+ */
+export declare function createLiteral(content: string): LiteralNode;
+export declare function createSyntheticToken(value: string, type?: string): Token;
+export declare function createWhitespaceNode(): WhitespaceNode;

package/dist/types/backend.d.ts

@@ -1,17 +1,17 @@
 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;
-    extractRuby: (source: string) => string;
+    parse: (source: string, options?: ParseOptions) => SerializedParseResult;
+    extractRuby: (source: string, options?: ExtractRubyOptions) => string;
     extractHTML: (source: string) => string;
+    parseRuby: (source: string) => Uint8Array | null;
     version: () => string;
 }
 export type BackendPromise = () => Promise<LibHerbBackend>;
-declare const expectedFunctions: readonly ["parse", "lex", "parseFile", "lexFile", "extractRuby", "extractHTML", "version"];
+declare const expectedFunctions: readonly ["parse", "lex", "extractRuby", "extractHTML", "parseRuby", "version"];
 type LibHerbBackendFunctionName = (typeof expectedFunctions)[number];
 export declare function _TYPECHECK(): {
     checkFunctionsExist: true;

package/dist/types/diagnostic.d.ts

@@ -1,5 +1,6 @@
 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.
  * This includes parser errors, lexer errors, lint offenses, and any other
@@ -26,6 +27,10 @@ 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[];
 }
 /**
  * Serialized form of a Diagnostic for JSON representation
@@ -36,6 +41,7 @@ export interface SerializedDiagnostic {
     severity: DiagnosticSeverity;
     code?: string;
     source?: string;
+    tags?: DiagnosticTag[];
 }
 export type MonacoSeverity = "error" | "warning" | "info";
 /**