svg-eslint-parser 0.0.5 → 0.0.6

package/README.md

@@ -10,7 +10,16 @@
 > [!IMPORTANT]
 > Status: Work In Progress, not ready for production.
 >
-> API is not stale now, Use at your own risk.
+> API is not stable now, use at your own risk.
+
+## Features
+
+- ✅ **ESLint Compatible**: Produces AST compatible with ESLint's parser interface
+- 🎯 **Type Safe**: Full TypeScript support with comprehensive type definitions
+- 🔍 **Rich Utilities**: Built-in functions for searching, traversing, and manipulating AST
+- 📊 **Detailed AST**: 16 node types covering all SVG/XML constructs
+- 🚀 **Zero Dependencies**: Minimal runtime dependencies for fast installation
+- 🎪 **Interactive Playground**: Try it online at [svg-eslint-parser.ntnyq.com](https://svg-eslint-parser.ntnyq.com/play)
 
 ## Install
 
@@ -26,12 +35,188 @@ yarn add svg-eslint-parser -D
 pnpm add svg-eslint-parser -D
 ```
 
+## Usage
+
+### Basic Parsing
+
+```typescript
+import { parse, parseForESLint } from 'svg-eslint-parser'
+
+// For direct use
+const document = parse('<svg><circle cx="50" cy="50" r="40" /></svg>')
+console.log(document.type) // 'Document'
+
+// For ESLint integration
+const result = parseForESLint('<svg><circle cx="50" cy="50" r="40" /></svg>')
+console.log(result.ast.type) // 'Program'
+```
+
+### With ESLint
+
+```javascript
+import pluginSVG from 'eslint-plugin-svg'
+import * as parserSVG from 'svg-eslint-parser'
+
+export default [
+  {
+    name: 'svg/rules',
+    files: ['**/*.svg'],
+    plugins: {
+      svg: pluginSVG,
+    },
+    languageOptions: {
+      parser: parserSVG,
+    },
+    rules: {
+      'svg/no-empty-title': 'error',
+    },
+  },
+]
+```
+
+### Using Utilities
+
+```typescript
+import {
+  parseForESLint,
+  findNodeByType,
+  NodeTypes,
+  traverseAST,
+} from 'svg-eslint-parser'
+
+const { ast } = parseForESLint(svgSource)
+const document = ast.body[0]
+
+// Find all tag nodes
+const tags = findNodeByType(document, NodeTypes.Tag)
+console.log(`Found ${tags.length} tags`)
+
+// Traverse with visitor pattern
+traverseAST(document, {
+  enter(node, parent) {
+    console.log('Visiting:', node.type)
+    // Return false to skip children
+    if (node.type === 'Comment') return false
+  },
+  leave(node, parent) {
+    console.log('Leaving:', node.type)
+  },
+})
+```
+
+## API
+
+### Parser Functions
+
+#### `parseForESLint(code: string, options?: ParserOptions)`
+
+Returns an ESLint-compatible result with AST, visitor keys, and services.
+
+#### `parse(code: string, options?: ParserOptions)`
+
+Returns a Document node directly.
+
+### Utility Functions
+
+#### Search & Traversal
+
+- `findNodeByType<T>(node, type)` - Find all nodes of a specific type
+- `findFirstNodeByType<T>(node, type)` - Find first node of a specific type
+- `traverseAST(node, visitor)` - Visitor pattern traversal with enter/leave hooks
+- `walkAST(node, callback)` - Simple traversal with callback
+
+#### Validation
+
+- `validateNode(node)` - Validate node structure
+- `isNodeType<T>(node, type)` - Type guard function
+
+#### Manipulation
+
+- `cloneNode<T>(node)` - Deep clone without parent references
+- `cloneNodeWithParent<T>(node, parent?)` - Clone preserving parent refs
+- `filterNodes(node, predicate)` - Filter nodes by predicate
+- `mapNodes<T>(node, mapper)` - Map over all nodes
+
+#### Analysis
+
+- `countNodes(node)` - Count total nodes
+- `getNodeDepth(node)` - Get node depth (requires parent refs)
+- `getParentChain(node)` - Get ancestor chain (requires parent refs)
+
+### Node Types
+
+The parser defines 34 node types:
+
+**Document Structure**: `Program`, `Document`
+
+**Elements**: `Tag`, `OpenTagStart`, `OpenTagEnd`, `CloseTag`
+
+**Attributes**: `Attribute`, `AttributeKey`, `AttributeValue`, `AttributeValueWrapperStart`, `AttributeValueWrapperEnd`
+
+**Text & Comments**: `Text`, `Comment`, `CommentOpen`, `CommentContent`, `CommentClose`
+
+**XML Declaration**: `XMLDeclaration`, `XMLDeclarationOpen`, `XMLDeclarationClose`, `XMLDeclarationAttribute`, `XMLDeclarationAttributeKey`, `XMLDeclarationAttributeValue`, `XMLDeclarationAttributeValueWrapperStart`, `XMLDeclarationAttributeValueWrapperEnd`
+
+**DOCTYPE**: `Doctype`, `DoctypeOpen`, `DoctypeClose`, `DoctypeAttribute`, `DoctypeAttributeValue`, `DoctypeAttributeWrapperStart`, `DoctypeAttributeWrapperEnd`
+
+**Error Handling**: `Error`
+
+## Documentation
+
+Full documentation is available at [svg-eslint-parser.ntnyq.com](https://svg-eslint-parser.ntnyq.com):
+
+- [API Documentation](https://svg-eslint-parser.ntnyq.com/api/)
+- [AST Structure](https://svg-eslint-parser.ntnyq.com/api/ast)
+- [Utilities Guide](https://svg-eslint-parser.ntnyq.com/api/utilities)
+- [Migration Guide](https://svg-eslint-parser.ntnyq.com/guide/migration)
+
 ## Playground
 
-You can try the parser in [playground](https://svg-eslint-parser.ntnyq.com/play).
+You can try the parser in the [interactive playground](https://svg-eslint-parser.ntnyq.com/play).
 
 Feel free to open an issue if you have any suggestions or find any bugs.
 
+## Example: Finding All Circles
+
+```typescript
+import { parseForESLint, findNodeByType, NodeTypes } from 'svg-eslint-parser'
+
+const svgCode = `
+<svg width="200" height="200">
+  <circle cx="50" cy="50" r="40" fill="red" />
+  <circle cx="150" cy="150" r="30" fill="blue" />
+  <rect x="10" y="10" width="50" height="50" />
+</svg>
+`
+
+const { ast } = parseForESLint(svgCode)
+const document = ast.body[0]
+
+// Find all tags and filter for circles
+const allTags = findNodeByType(document, NodeTypes.Tag)
+const circles = allTags.filter(tag => tag.name === 'circle')
+
+console.log(`Found ${circles.length} circles`)
+
+circles.forEach((circle, i) => {
+  const cx = circle.attributes.find(attr => attr.key.value === 'cx')
+  const cy = circle.attributes.find(attr => attr.key.value === 'cy')
+  const r = circle.attributes.find(attr => attr.key.value === 'r')
+
+  console.log(
+    `Circle ${i + 1}: cx=${cx?.value?.value}, cy=${cy?.value?.value}, r=${r?.value?.value}`,
+  )
+})
+```
+
+Output:
+
+```
+Found 2 circles
+Circle 1: cx=50, cy=50, r=40
+Circle 2: cx=150, cy=150, r=30
+```
+
 ## Links
 
 - [Scalable Vector Graphics (SVG) 2](https://www.w3.org/TR/SVG2/)

package/dist/index.d.ts

@@ -61,69 +61,65 @@ declare enum NodeTypes {
   Attribute = "Attribute",
   AttributeKey = "AttributeKey",
   AttributeValue = "AttributeValue",
-  AttributeValueWrapperEnd = "AttributeValueWrapperEnd",
-  AttributeValueWrapperStart = "AttributeValueWrapperStart",
-  CloseTag = "CloseTag",
   Comment = "Comment",
-  CommentClose = "CommentClose",
-  CommentContent = "CommentContent",
-  CommentOpen = "CommentOpen",
   Doctype = "Doctype",
   DoctypeAttribute = "DoctypeAttribute",
   DoctypeAttributeValue = "DoctypeAttributeValue",
-  DoctypeAttributeWrapperEnd = "DoctypeAttributeWrapperEnd",
-  DoctypeAttributeWrapperStart = "DoctypeAttributeWrapperStart",
-  DoctypeClose = "DoctypeClose",
-  DoctypeOpen = "DoctypeOpen",
   Document = "Document",
-  OpenTagEnd = "OpenTagEnd",
-  OpenTagStart = "OpenTagStart",
+  Error = "Error",
   Program = "Program",
   Tag = "Tag",
   Text = "Text",
   XMLDeclaration = "XMLDeclaration",
   XMLDeclarationAttribute = "XMLDeclarationAttribute",
   XMLDeclarationAttributeKey = "XMLDeclarationAttributeKey",
-  XMLDeclarationAttributeValue = "XMLDeclarationAttributeValue",
-  XMLDeclarationAttributeValueWrapperEnd = "XMLDeclarationAttributeValueWrapperEnd",
-  XMLDeclarationAttributeValueWrapperStart = "XMLDeclarationAttributeValueWrapperStart",
-  XMLDeclarationClose = "XMLDeclarationClose",
-  XMLDeclarationOpen = "XMLDeclarationOpen",
+  XMLDeclarationAttributeValue = "XMLDeclarationAttributeValue"
 }
 //#endregion
 //#region src/constants/tokenTypes.d.ts
 declare enum TokenTypes {
-  Attribute = "Attribute",
+  /**
+   * @pg Content tokens
+   */
+  Text = "Text",
+  /**
+   * @pg Attribute tokens
+   */
   AttributeAssignment = "AttributeAssignment",
   AttributeKey = "AttributeKey",
   AttributeValue = "AttributeValue",
   AttributeValueWrapperEnd = "AttributeValueWrapperEnd",
   AttributeValueWrapperStart = "AttributeValueWrapperStart",
-  CloseTag = "CloseTag",
-  Comment = "Comment",
-  CommentClose = "CommentClose",
-  CommentContent = "CommentContent",
-  CommentOpen = "CommentOpen",
-  Doctype = "Doctype",
+  /**
+   * @pg Doctype tokens
+   */
   DoctypeAttributeValue = "DoctypeAttributeValue",
   DoctypeAttributeWrapperEnd = "DoctypeAttributeWrapperEnd",
   DoctypeAttributeWrapperStart = "DoctypeAttributeWrapperStart",
   DoctypeClose = "DoctypeClose",
   DoctypeOpen = "DoctypeOpen",
-  Document = "Document",
+  /**
+   * @pg Tag tokens
+   */
+  CloseTag = "CloseTag",
   OpenTagEnd = "OpenTagEnd",
   OpenTagStart = "OpenTagStart",
-  Program = "Program",
-  Tag = "Tag",
-  Text = "Text",
-  XMLDeclarationAttribute = "XMLDeclarationAttribute",
+  /**
+   * @pg Comment tokens
+   */
+  CommentClose = "CommentClose",
+  CommentContent = "CommentContent",
+  CommentOpen = "CommentOpen",
+  /**
+   * @pg XML Declaration tokens
+   */
   XMLDeclarationAttributeAssignment = "XMLDeclarationAttributeAssignment",
   XMLDeclarationAttributeKey = "XMLDeclarationAttributeKey",
   XMLDeclarationAttributeValue = "XMLDeclarationAttributeValue",
   XMLDeclarationAttributeValueWrapperEnd = "XMLDeclarationAttributeValueWrapperEnd",
   XMLDeclarationAttributeValueWrapperStart = "XMLDeclarationAttributeValueWrapperStart",
   XMLDeclarationClose = "XMLDeclarationClose",
-  XMLDeclarationOpen = "XMLDeclarationOpen",
+  XMLDeclarationOpen = "XMLDeclarationOpen"
 }
 //#endregion
 //#region src/constants/specialChar.d.ts
@@ -186,7 +182,7 @@ declare enum TokenizerContextTypes {
   XMLDeclarationAttributeValue = "XMLDeclarationAttributeValue",
   XMLDeclarationAttributeValueWrapped = "XMLDeclarationAttributeValueWrapped",
   XMLDeclarationClose = "XMLDeclarationClose",
-  XMLDeclarationOpen = "XMLDeclarationOpen",
+  XMLDeclarationOpen = "XMLDeclarationOpen"
 }
 //#endregion
 //#region src/constants/constructTreeContextTypes.d.ts
@@ -204,7 +200,7 @@ declare enum ConstructTreeContextTypes {
   XMLDeclaration = "XMLDeclaration",
   XMLDeclarationAttribute = "XMLDeclarationAttribute",
   XMLDeclarationAttributes = "XMLDeclarationAttributes",
-  XMLDeclarationAttributeValue = "XMLDeclarationAttributeValue",
+  XMLDeclarationAttributeValue = "XMLDeclarationAttributeValue"
 }
 //#endregion
 //#region src/types/ast/common.d.ts
@@ -238,7 +234,7 @@ interface SourceLocation {
 /**
  * any token
  */
-type AnyToken = Token<TokenTypes.Attribute> | Token<TokenTypes.AttributeAssignment> | Token<TokenTypes.AttributeKey> | Token<TokenTypes.AttributeValue> | Token<TokenTypes.AttributeValueWrapperEnd> | Token<TokenTypes.AttributeValueWrapperStart> | Token<TokenTypes.CloseTag> | Token<TokenTypes.Comment> | Token<TokenTypes.CommentClose> | Token<TokenTypes.CommentContent> | Token<TokenTypes.CommentOpen> | Token<TokenTypes.Doctype> | Token<TokenTypes.DoctypeAttributeValue> | Token<TokenTypes.DoctypeAttributeWrapperEnd> | Token<TokenTypes.DoctypeAttributeWrapperStart> | Token<TokenTypes.DoctypeClose> | Token<TokenTypes.DoctypeOpen> | Token<TokenTypes.Document> | Token<TokenTypes.OpenTagEnd> | Token<TokenTypes.OpenTagStart> | Token<TokenTypes.Program> | Token<TokenTypes.Tag> | Token<TokenTypes.Text> | Token<TokenTypes.XMLDeclarationAttribute> | Token<TokenTypes.XMLDeclarationAttributeAssignment> | Token<TokenTypes.XMLDeclarationAttributeKey> | Token<TokenTypes.XMLDeclarationAttributeValue> | Token<TokenTypes.XMLDeclarationAttributeValueWrapperEnd> | Token<TokenTypes.XMLDeclarationAttributeValueWrapperStart> | Token<TokenTypes.XMLDeclarationClose> | Token<TokenTypes.XMLDeclarationOpen>;
+type AnyToken = Token<TokenTypes.AttributeAssignment> | Token<TokenTypes.AttributeKey> | Token<TokenTypes.AttributeValue> | Token<TokenTypes.AttributeValueWrapperEnd> | Token<TokenTypes.AttributeValueWrapperStart> | Token<TokenTypes.CloseTag> | Token<TokenTypes.CommentClose> | Token<TokenTypes.CommentContent> | Token<TokenTypes.CommentOpen> | Token<TokenTypes.DoctypeAttributeValue> | Token<TokenTypes.DoctypeAttributeWrapperEnd> | Token<TokenTypes.DoctypeAttributeWrapperStart> | Token<TokenTypes.DoctypeClose> | Token<TokenTypes.DoctypeOpen> | Token<TokenTypes.OpenTagEnd> | Token<TokenTypes.OpenTagStart> | Token<TokenTypes.Text> | Token<TokenTypes.XMLDeclarationAttributeAssignment> | Token<TokenTypes.XMLDeclarationAttributeKey> | Token<TokenTypes.XMLDeclarationAttributeValue> | Token<TokenTypes.XMLDeclarationAttributeValueWrapperEnd> | Token<TokenTypes.XMLDeclarationAttributeValueWrapperStart> | Token<TokenTypes.XMLDeclarationClose> | Token<TokenTypes.XMLDeclarationOpen>;
 /**
  * token
  */
@@ -263,117 +259,99 @@ interface SimpleNode<T extends NodeTypes> extends BaseNode {
 }
 type TextNode = SimpleNode<NodeTypes.Text>;
 /**
- * attribute
+ * attribute nodes
  * @pg
  */
 type AttributeKeyNode = SimpleNode<NodeTypes.AttributeKey>;
+type AttributeValueNode = SimpleNode<NodeTypes.AttributeValue>;
 interface AttributeNode extends BaseNode {
   key: AttributeKeyNode;
   type: NodeTypes.Attribute;
   value: AttributeValueNode;
-  endWrapper?: AttributeValueWrapperEndNode;
-  startWrapper?: AttributeValueWrapperStartNode;
+  quoteChar?: '"' | "'" | undefined;
 }
-type AttributeValueNode = SimpleNode<NodeTypes.AttributeValue>;
-type AttributeValueWrapperEndNode = SimpleNode<NodeTypes.AttributeValueWrapperEnd>;
-type AttributeValueWrapperStartNode = SimpleNode<NodeTypes.AttributeValueWrapperStart>;
 /**
- * comment
+ * comment nodes
  * @pg
  */
-type CommentCloseNode = SimpleNode<NodeTypes.CommentClose>;
-type CommentContentNode = SimpleNode<NodeTypes.CommentContent>;
 interface CommentNode extends BaseNode {
-  close: CommentCloseNode;
-  open: CommentOpenNode;
+  content: string;
   type: NodeTypes.Comment;
-  value: CommentContentNode;
 }
-type CommentOpenNode = SimpleNode<NodeTypes.CommentOpen>;
 /**
- * doctype
+ * doctype nodes
  * @pg
  */
+type DoctypeAttributeValueNode = SimpleNode<NodeTypes.DoctypeAttributeValue>;
 interface DoctypeAttributeNode extends BaseNode {
   type: NodeTypes.DoctypeAttribute;
-  endWrapper?: DoctypeAttributeWrapperEndNode;
-  startWrapper?: DoctypeAttributeWrapperStartNode;
+  quoteChar?: '"' | "'" | undefined;
   value?: DoctypeAttributeValueNode;
 }
-type DoctypeAttributeValueNode = SimpleNode<NodeTypes.DoctypeAttributeValue>;
-type DoctypeAttributeWrapperEndNode = SimpleNode<NodeTypes.DoctypeAttributeWrapperEnd>;
-type DoctypeAttributeWrapperStartNode = SimpleNode<NodeTypes.DoctypeAttributeWrapperStart>;
-type DoctypeCloseNode = SimpleNode<NodeTypes.DoctypeClose>;
 interface DoctypeNode extends BaseNode {
   attributes: DoctypeAttributeNode[];
-  close: DoctypeCloseNode;
-  open: DoctypeOpenNode;
   type: NodeTypes.Doctype;
 }
-type DoctypeOpenNode = SimpleNode<NodeTypes.DoctypeOpen>;
 /**
- * tag
+ * tag nodes
  * @pg
  */
-type CloseTagNode = SimpleNode<NodeTypes.CloseTag>;
-type OpenTagEndNode = SimpleNode<NodeTypes.OpenTagEnd>;
-type OpenTagStartNode = SimpleNode<NodeTypes.OpenTagStart>;
 interface TagNode extends BaseNode {
   attributes: AttributeNode[];
   children: NestableNode[];
   name: string;
-  openEnd: OpenTagEndNode;
-  openStart: OpenTagStartNode;
   selfClosing: boolean;
   type: NodeTypes.Tag;
-  close?: CloseTagNode;
 }
 /**
- * XML declaration
+ * XML declaration nodes
  */
 type XMLDeclarationAttributeKeyNode = SimpleNode<NodeTypes.XMLDeclarationAttributeKey>;
+type XMLDeclarationAttributeValueNode = SimpleNode<NodeTypes.XMLDeclarationAttributeValue>;
 interface XMLDeclarationAttributeNode extends BaseNode {
   key: XMLDeclarationAttributeKeyNode;
   type: NodeTypes.XMLDeclarationAttribute;
   value: XMLDeclarationAttributeValueNode;
-  endWrapper?: XMLDeclarationAttributeValueWrapperEndNode;
-  startWrapper?: XMLDeclarationAttributeValueWrapperStartNode;
+  quoteChar?: '"' | "'" | undefined;
 }
-type XMLDeclarationAttributeValueNode = SimpleNode<NodeTypes.XMLDeclarationAttributeValue>;
-type XMLDeclarationAttributeValueWrapperEndNode = SimpleNode<NodeTypes.XMLDeclarationAttributeValueWrapperEnd>;
-type XMLDeclarationAttributeValueWrapperStartNode = SimpleNode<NodeTypes.XMLDeclarationAttributeValueWrapperStart>;
-type XMLDeclarationCloseNode = SimpleNode<NodeTypes.XMLDeclarationClose>;
 interface XMLDeclarationNode extends BaseNode {
   attributes: XMLDeclarationAttributeNode[];
-  close: XMLDeclarationCloseNode;
-  open: XMLDeclarationOpenNode;
   type: NodeTypes.XMLDeclaration;
 }
-type XMLDeclarationOpenNode = SimpleNode<NodeTypes.XMLDeclarationOpen>;
+/**
+ * error nodes
+ * @pg
+ */
+interface ErrorNode extends BaseNode {
+  code: string;
+  message: string;
+  type: NodeTypes.Error;
+  recoveredNode?: AnyNode;
+}
 /**
  * nestable node
  * @pg
  */
-type NestableNode = CommentNode | TagNode | TextNode | XMLDeclarationNode;
+type NestableNode = CommentNode | DoctypeNode | TagNode | TextNode | XMLDeclarationNode;
 /**
  * program
  * @pg
  */
-interface DocumentNode extends BaseNode {
-  children: NestableNode[];
-  type: NodeTypes.Document;
-}
 interface Program extends BaseNode {
   body: DocumentNode[];
-  comments: CommentContentNode[];
+  comments: string[];
   tokens: AnyToken[];
   type: NodeTypes.Program;
 }
+interface DocumentNode extends BaseNode {
+  children: NestableNode[];
+  type: NodeTypes.Document;
+}
 /**
  * any node
  * @pg
  */
-type AnyNode = AttributeKeyNode | AttributeNode | AttributeValueNode | AttributeValueWrapperEndNode | AttributeValueWrapperStartNode | CloseTagNode | CommentCloseNode | CommentContentNode | CommentNode | CommentOpenNode | DoctypeAttributeNode | DoctypeAttributeValueNode | DoctypeAttributeWrapperEndNode | DoctypeAttributeWrapperStartNode | DoctypeCloseNode | DoctypeNode | DoctypeOpenNode | DocumentNode | OpenTagEndNode | OpenTagStartNode | Program | TagNode | TextNode | XMLDeclarationAttributeKeyNode | XMLDeclarationAttributeNode | XMLDeclarationAttributeValueNode | XMLDeclarationAttributeValueWrapperEndNode | XMLDeclarationAttributeValueWrapperStartNode | XMLDeclarationCloseNode | XMLDeclarationNode | XMLDeclarationOpenNode;
+type AnyNode = AttributeKeyNode | AttributeNode | AttributeValueNode | CommentNode | DoctypeAttributeNode | DoctypeAttributeValueNode | DoctypeNode | DocumentNode | ErrorNode | Program | TagNode | TextNode | XMLDeclarationAttributeKeyNode | XMLDeclarationAttributeNode | XMLDeclarationAttributeValueNode | XMLDeclarationNode;
 //#endregion
 //#region src/types/parse.d.ts
 interface Options {
@@ -408,11 +386,11 @@ interface ParseResult {
 }
 //#endregion
 //#region src/types/contextualNode.d.ts
-type AnyContextualNode = ContextualAttributeNode | ContextualCommentNode | ContextualDoctypeAttributeNode | ContextualDoctypeNode | ContextualDocumentNode | ContextualTagNode | ContextualXMLDeclarationAttributeNode | ContextuaLXMLDeclarationNode;
+type AnyContextualNode = ContextualAttributeNode | ContextualCommentNode | ContextualDoctypeAttributeNode | ContextualDoctypeNode | ContextualDocumentNode | ContextualTagNode | ContextualXMLDeclarationAttributeNode | ContextualXMLDeclarationNode;
 type ContextualAttributeNode = ContextualNode<AttributeNode, 'key' | 'value'>;
-type ContextualCommentNode = ContextualNode<CommentNode, 'close' | 'open' | 'value'>;
-type ContextualDoctypeAttributeNode = ContextualNode<DoctypeAttributeNode, 'value'>;
-type ContextualDoctypeNode = ContextualNode<DoctypeNode, 'close' | 'open'> & {
+type ContextualCommentNode = ContextualNode<CommentNode, 'content'>;
+type ContextualDoctypeAttributeNode = ContextualNode<DoctypeAttributeNode, 'type' | 'value'>;
+type ContextualDoctypeNode = ContextualNode<DoctypeNode, 'attributes'> & {
   attributes: ContextualDoctypeAttributeNode[];
 };
 type ContextualDocumentNode = Omit<ContextualNode<DocumentNode, never>, 'children'> & {
@@ -421,12 +399,12 @@ type ContextualDocumentNode = Omit<ContextualNode<DocumentNode, never>, 'childre
 type ContextualNode<T extends AnyNode, K extends keyof T> = PartialBy<T, K> & {
   parentRef?: any;
 };
-type ContextualTagNode = ContextualNode<TagNode, 'close' | 'name' | 'openEnd' | 'openStart' | 'selfClosing'> & {
+type ContextualTagNode = ContextualNode<TagNode, 'attributes' | 'children' | 'name' | 'selfClosing'> & {
   attributes: ContextualAttributeNode[];
   children: Array<ContextualCommentNode | ContextualDoctypeNode | ContextualTagNode | TagNode['children'][number]>;
 };
 type ContextualXMLDeclarationAttributeNode = ContextualNode<XMLDeclarationAttributeNode, 'key' | 'value'>;
-type ContextuaLXMLDeclarationNode = ContextualNode<XMLDeclarationNode, 'close' | 'open'> & {
+type ContextualXMLDeclarationNode = ContextualNode<XMLDeclarationNode, 'attributes'> & {
   attributes: ContextualXMLDeclarationAttributeNode[];
 };
 type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
@@ -523,15 +501,124 @@ interface TokenizeHandler {
   handleContentEnd?: (state: TokenizerState) => void;
 }
 declare namespace index_d_exports {
-  export { AnyContextualNode, AnyNode, AnyToken, AttributeKeyNode, AttributeNode, AttributeValueNode, AttributeValueWrapperEndNode, AttributeValueWrapperStartNode, BaseNode, CloseTagNode, CommentCloseNode, CommentContentNode, CommentNode, CommentOpenNode, ConstructTreeHandler, ConstructTreeState, ContextuaLXMLDeclarationNode, ContextualAttributeNode, ContextualCommentNode, ContextualDoctypeAttributeNode, ContextualDoctypeNode, ContextualDocumentNode, ContextualNode, ContextualTagNode, ContextualXMLDeclarationAttributeNode, DoctypeAttributeNode, DoctypeAttributeValueNode, DoctypeAttributeWrapperEndNode, DoctypeAttributeWrapperStartNode, DoctypeCloseNode, DoctypeNode, DoctypeOpenNode, DocumentNode, Locations, NestableNode, OpenTagEndNode, OpenTagStartNode, Options, ParseForESLintResult, ParseResult, PartialBy, Position, Program, Range, SimpleNode, SourceLocation, TagNode, TextNode, Token, TokenizeHandler, TokenizerState, XMLDeclarationAttributeKeyNode, XMLDeclarationAttributeNode, XMLDeclarationAttributeValueNode, XMLDeclarationAttributeValueWrapperEndNode, XMLDeclarationAttributeValueWrapperStartNode, XMLDeclarationCloseNode, XMLDeclarationNode, XMLDeclarationOpenNode };
+  export { AnyContextualNode, AnyNode, AnyToken, AttributeKeyNode, AttributeNode, AttributeValueNode, BaseNode, CommentNode, ConstructTreeHandler, ConstructTreeState, ContextualAttributeNode, ContextualCommentNode, ContextualDoctypeAttributeNode, ContextualDoctypeNode, ContextualDocumentNode, ContextualNode, ContextualTagNode, ContextualXMLDeclarationAttributeNode, ContextualXMLDeclarationNode, DoctypeAttributeNode, DoctypeAttributeValueNode, DoctypeNode, DocumentNode, ErrorNode, Locations, NestableNode, Options, ParseForESLintResult, ParseResult, PartialBy, Position, Program, Range, SimpleNode, SourceLocation, TagNode, TextNode, Token, TokenizeHandler, TokenizerState, XMLDeclarationAttributeKeyNode, XMLDeclarationAttributeNode, XMLDeclarationAttributeValueNode, XMLDeclarationNode };
 }
 //#endregion
 //#region src/parser/parseForESLint.d.ts
 declare function parseForESLint(source: string, options?: Options): ParseForESLintResult;
 //#endregion
+//#region src/utils/cloneNode.d.ts
+/**
+ * Deep clone a node, removing parent references
+ * @param node - Node to clone
+ * @returns Cloned node
+ */
+declare function cloneNode<T extends AnyNode>(node: T): T;
+/**
+ * Deep clone a node, preserving parent references
+ * @param node - Node to clone
+ * @param parent - Parent node for the cloned node
+ * @returns Cloned node with parent references
+ */
+declare function cloneNodeWithParent<T extends AnyNode>(node: T, parent?: AnyNode): T;
+//#endregion
+//#region src/utils/nodeHelpers.d.ts
+/**
+ * Filter nodes by a predicate function
+ * @param node - Root node to filter from
+ * @param predicate - Filter function
+ * @returns Array of matching nodes
+ */
+declare function filterNodes(node: AnyNode, predicate: (node: AnyNode) => boolean): AnyNode[];
+/**
+ * Map over all nodes in the AST
+ * @param node - Root node to map from
+ * @param mapper - Mapping function
+ * @returns Transformed node
+ */
+declare function mapNodes<T extends AnyNode>(node: T, mapper: (node: AnyNode) => AnyNode): T;
+/**
+ * Get all parent nodes from a node up to the root
+ * @param node - Starting node
+ * @returns Array of parent nodes (from immediate parent to root)
+ */
+declare function getParentChain(node: any): AnyNode[];
+/**
+ * Get the depth of a node in the AST (distance from root)
+ * @param node - Node to measure
+ * @returns Depth level (root = 0)
+ */
+declare function getNodeDepth(node: any): number;
+/**
+ * Count total number of nodes in the AST
+ * @param node - Root node
+ * @returns Total node count
+ */
+declare function countNodes(node: AnyNode): number;
+//#endregion
+//#region src/utils/traverseAST.d.ts
+/**
+ * Visitor function for AST traversal
+ */
+type ASTVisitor = {
+  /**
+   * Called when entering a node
+   * Return false to skip traversing children
+   */
+  enter?: (node: AnyNode, parent: AnyNode | null) => void | boolean;
+  /**
+   * Called when leaving a node
+   */
+  leave?: (node: AnyNode, parent: AnyNode | null) => void;
+};
+/**
+ * Traverse the AST with a visitor pattern
+ * @param node - Root node to traverse from
+ * @param visitor - Visitor object with enter/leave hooks
+ * @param parent - Parent node (used internally)
+ */
+declare function traverseAST(node: AnyNode, visitor: ASTVisitor, parent?: AnyNode | null): void;
+/**
+ * Simple traversal function that calls a callback for each node
+ * @param node - Root node to traverse from
+ * @param callback - Function to call for each node
+ */
+declare function walkAST(node: AnyNode, callback: (node: AnyNode, parent: AnyNode | null) => void): void;
+//#endregion
+//#region src/utils/validateNode.d.ts
+/**
+ * Validate if a node matches its expected structure
+ * @param node - Node to validate
+ * @returns True if node is valid
+ */
+declare function validateNode(node: AnyNode): boolean;
+/**
+ * Check if a node is of a specific type with type guard
+ * @param node - Node to check
+ * @param type - Expected node type
+ * @returns True if node is of the specified type
+ */
+declare function isNodeType<T extends NodeTypes>(node: AnyNode, type: T): boolean;
+//#endregion
+//#region src/utils/findNodeByType.d.ts
+/**
+ * Find all nodes of a specific type in the AST
+ * @param node - Root node to search from
+ * @param type - Node type to search for
+ * @returns Array of matching nodes
+ */
+declare function findNodeByType<T extends NodeTypes>(node: AnyNode, type: T): AnyNode[];
+/**
+ * Find the first node of a specific type in the AST
+ * @param node - Root node to search from
+ * @param type - Node type to search for
+ * @returns First matching node or undefined
+ */
+declare function findFirstNodeByType<T extends NodeTypes>(node: AnyNode, type: T): AnyNode | undefined;
+//#endregion
 //#region src/index.d.ts
 declare const name: string;
 declare const VisitorKeys: eslint0.SourceCode.VisitorKeys;
 declare function parse(code: string, options?: Options): Program;
 //#endregion
-export { type index_d_exports as AST, AnyContextualNode, AnyNode, AnyToken, AttributeKeyNode, AttributeNode, AttributeValueNode, AttributeValueWrapperEndNode, AttributeValueWrapperStartNode, BaseNode, COMMENT_END, COMMENT_START, CloseTagNode, CommentCloseNode, CommentContentNode, CommentNode, CommentOpenNode, ConstructTreeContextTypes, ConstructTreeHandler, ConstructTreeState, ContextuaLXMLDeclarationNode, ContextualAttributeNode, ContextualCommentNode, ContextualDoctypeAttributeNode, ContextualDoctypeNode, ContextualDocumentNode, ContextualNode, ContextualTagNode, ContextualXMLDeclarationAttributeNode, DEPRECATED_SVG_ELEMENTS, DoctypeAttributeNode, DoctypeAttributeValueNode, DoctypeAttributeWrapperEndNode, DoctypeAttributeWrapperStartNode, DoctypeCloseNode, DoctypeNode, DoctypeOpenNode, DocumentNode, Locations, NestableNode, NodeTypes, OpenTagEndNode, OpenTagStartNode, Options, ParseError, ParseForESLintResult, ParseResult, PartialBy, Position, Program, RE_CLOSE_TAG_NAME, RE_INCOMPLETE_CLOSING_TAG, RE_OPEN_TAG_NAME, RE_OPEN_TAG_START, Range, SELF_CLOSING_ELEMENTS, SPECIAL_CHAR, SVG_ELEMENTS, SimpleNode, SourceLocation, TagNode, TextNode, Token, TokenTypes, TokenizeHandler, TokenizerContextTypes, TokenizerState, VisitorKeys, XMLDeclarationAttributeKeyNode, XMLDeclarationAttributeNode, XMLDeclarationAttributeValueNode, XMLDeclarationAttributeValueWrapperEndNode, XMLDeclarationAttributeValueWrapperStartNode, XMLDeclarationCloseNode, XMLDeclarationNode, XMLDeclarationOpenNode, XML_DECLARATION_END, XML_DECLARATION_START, meta, name, parse, parseForESLint };
+export { type index_d_exports as AST, type ASTVisitor, AnyContextualNode, AnyNode, AnyToken, AttributeKeyNode, AttributeNode, AttributeValueNode, BaseNode, COMMENT_END, COMMENT_START, CommentNode, ConstructTreeContextTypes, ConstructTreeHandler, ConstructTreeState, ContextualAttributeNode, ContextualCommentNode, ContextualDoctypeAttributeNode, ContextualDoctypeNode, ContextualDocumentNode, ContextualNode, ContextualTagNode, ContextualXMLDeclarationAttributeNode, ContextualXMLDeclarationNode, DEPRECATED_SVG_ELEMENTS, DoctypeAttributeNode, DoctypeAttributeValueNode, DoctypeNode, DocumentNode, ErrorNode, Locations, NestableNode, NodeTypes, Options, ParseError, ParseForESLintResult, ParseResult, PartialBy, Position, Program, RE_CLOSE_TAG_NAME, RE_INCOMPLETE_CLOSING_TAG, RE_OPEN_TAG_NAME, RE_OPEN_TAG_START, Range, SELF_CLOSING_ELEMENTS, SPECIAL_CHAR, SVG_ELEMENTS, SimpleNode, SourceLocation, TagNode, TextNode, Token, TokenTypes, TokenizeHandler, TokenizerContextTypes, TokenizerState, VisitorKeys, XMLDeclarationAttributeKeyNode, XMLDeclarationAttributeNode, XMLDeclarationAttributeValueNode, XMLDeclarationNode, XML_DECLARATION_END, XML_DECLARATION_START, cloneNode, cloneNodeWithParent, countNodes, filterNodes, findFirstNodeByType, findNodeByType, getNodeDepth, getParentChain, isNodeType, mapNodes, meta, name, parse, parseForESLint, traverseAST, validateNode, walkAST };