feat: Add AST traversal functionality with visitor pattern

Implements a comprehensive traverse() function that enables walking through
the CSS selector AST using the visitor pattern. Supports both simple visitor
functions and objects with enter/exit hooks, context information (parent,
parents, key, index), and ability to skip subtrees.

Added:
- src/traverse.ts: Core traversal implementation with visitor pattern
- test/traverse.test.ts: 30+ comprehensive test cases
- Updated README.md with usage examples and documentation
- Exported traverse types from index.ts

Author: mdevils

README.md

@@ -11,6 +11,7 @@ A high-performance CSS selector parser with advanced features for modern web dev
 
 - 🚀 **Fast and memory-efficient** parsing for all CSS selectors
 - 🌳 **AST-based** object model for programmatic manipulation
+- 🚶 **AST traversal** with visitor pattern for analyzing and transforming selectors
 - 📊 **Full compliance** with all CSS selector specifications
 - 🧪 **Comprehensive test coverage**
 - 📚 **Well-documented API** with TypeScript support
@@ -20,18 +21,9 @@ A high-performance CSS selector parser with advanced features for modern web dev
 
 ## Playground
 
-Try the interactive playground to explore the parser's capabilities:
+**[🎮 Launch Interactive Playground](https://mdevils.github.io/css-selector-parser/)**
 
-**[🎮 Launch Playground](https://mdevils.github.io/css-selector-parser/)**
-
-The playground allows you to:
-- ✍️ Write CSS selectors with syntax highlighting
-- ⚙️ Configure parser options in real-time
-- 🌳 View the parsed AST structure
-- 🧪 Test different CSS syntax levels and modules
-- ✅ See rendered output for validation
-
-Perfect for learning, debugging, and exploring CSS selector syntax!
+Test CSS selectors in your browser with syntax highlighting, real-time AST visualization, and configurable parser options.
 
 ## Supported CSS Selector Standards
 
@@ -173,6 +165,70 @@ const selector = ast.selector({
 console.log(render(selector)); // a[href^="/"], .container:has(nav) > a[href]:nth-child(2)::before
 ```
 
+### Traversing the AST
+
+The `traverse` function allows you to walk through the AST and visit each node, making it easy to analyze or transform selectors.
+
+```javascript
+import { createParser, traverse } from 'css-selector-parser';
+
+const parse = createParser();
+const selector = parse('div.foo > span#bar:hover::before');
+
+// Simple visitor function - called for each node
+traverse(selector, (node, context) => {
+    console.log(node.type, context.parents.length);
+});
+
+// Visitor with enter/exit hooks
+traverse(selector, {
+    enter(node, context) {
+        console.log('Entering:', node.type);
+        if (node.type === 'ClassName') {
+            console.log('Found class:', node.name);
+        }
+    },
+    exit(node, context) {
+        console.log('Leaving:', node.type);
+    }
+});
+
+// Skip visiting children of specific nodes
+traverse(selector, (node) => {
+    if (node.type === 'PseudoClass') {
+        // Don't visit children of pseudo-classes
+        return false;
+    }
+});
+
+// Practical example: collect all class names
+const classNames = [];
+traverse(selector, (node) => {
+    if (node.type === 'ClassName') {
+        classNames.push(node.name);
+    }
+});
+console.log(classNames); // ['foo']
+
+// Access parent information
+traverse(selector, (node, context) => {
+    console.log({
+        type: node.type,
+        parent: context.parent?.type,
+        depth: context.parents.length,
+        key: context.key,
+        index: context.index
+    });
+});
+```
+
+The traversal context provides:
+- `node`: The current AST node being visited
+- `parent`: The parent node (undefined for root)
+- `parents`: Array of all ancestor nodes from root to current
+- `key`: Property name in parent that references this node
+- `index`: Array index if this node is in an array
+
 ## CSS Modules Support
 
 CSS Modules are specifications that add new selectors or modify existing ones. This parser supports various CSS modules that can be included in your syntax definition:
@@ -205,6 +261,7 @@ The `latest` syntax automatically includes all modules marked as current specifi
 - [Parsing CSS Selectors](docs/modules.md#createParser)
 - [Constructing CSS AST](docs/modules.md#ast)
 - [Rendering CSS AST](docs/modules.md#render)
+- [Traversing CSS AST](docs/modules.md#traverse)
 
 ## Contributing
 

src/index.ts

@@ -23,3 +23,4 @@ export {
     AstWildcardTag
 } from './ast.js';
 export {CssLevel, CssModule, SyntaxDefinition} from './syntax-definitions.js';
+export {traverse, Visitor, VisitorFunction, TraversalContext, TraverseOptions} from './traverse.js';

src/traverse.ts

@@ -0,0 +1,256 @@
+import {
+    AstEntity,
+    AstSelector,
+    AstRule,
+    AstTagName,
+    AstWildcardTag,
+    AstAttribute,
+    AstPseudoClass,
+    AstPseudoElement,
+    AstFormulaOfSelector
+} from './ast.js';
+
+/**
+ * Visitor function that is called for each node during traversal.
+ * Return `false` to skip visiting children of this node.
+ * Return `true` or `undefined` to continue traversal normally.
+ */
+export type VisitorFunction = (node: AstEntity, context: TraversalContext) => void | boolean | undefined;
+
+/**
+ * Visitor object with optional enter and exit hooks.
+ * - `enter`: Called when first visiting a node (before its children)
+ * - `exit`: Called when leaving a node (after its children)
+ */
+export interface Visitor {
+    /**
+     * Called when entering a node (before visiting its children).
+     * Return `false` to skip visiting children of this node.
+     */
+    enter?: VisitorFunction;
+    /**
+     * Called when exiting a node (after visiting its children).
+     */
+    exit?: VisitorFunction;
+}
+
+/**
+ * Context information provided to visitor functions during traversal.
+ */
+export interface TraversalContext {
+    /** The current node being visited */
+    node: AstEntity;
+    /** Parent node (undefined for root) */
+    parent?: AstEntity;
+    /** Path of parent nodes from root to current node */
+    parents: AstEntity[];
+    /** Property name in parent that references this node */
+    key?: string;
+    /** Array index if this node is in an array */
+    index?: number;
+}
+
+/**
+ * Options for controlling traversal behavior.
+ */
+export interface TraverseOptions {
+    /** Custom visitor implementation */
+    visitor?: Visitor | VisitorFunction;
+}
+
+/**
+ * Internal state for tracking traversal.
+ */
+interface TraversalState {
+    visitor: Visitor;
+    parents: AstEntity[];
+}
+
+/**
+ * Traverses a CSS selector AST, calling visitor functions for each node.
+ *
+ * @param node - The root AST node to start traversal from
+ * @param visitor - Visitor function or object with enter/exit hooks
+ *
+ * @example
+ * ```typescript
+ * import { createParser, traverse } from 'css-selector-parser';
+ *
+ * const parse = createParser();
+ * const selector = parse('div.foo > span#bar');
+ *
+ * // Simple visitor function
+ * traverse(selector, (node, context) => {
+ *   console.log(node.type, context.parents.length);
+ * });
+ *
+ * // Visitor with enter/exit hooks
+ * traverse(selector, {
+ *   enter(node, context) {
+ *     if (node.type === 'ClassName') {
+ *       console.log('Found class:', node.name);
+ *     }
+ *   },
+ *   exit(node, context) {
+ *     console.log('Leaving:', node.type);
+ *   }
+ * });
+ *
+ * // Skip subtrees
+ * traverse(selector, {
+ *   enter(node, context) {
+ *     if (node.type === 'PseudoClass') {
+ *       // Don't visit children of pseudo-classes
+ *       return false;
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export function traverse(node: AstEntity, visitor: Visitor | VisitorFunction): void {
+    const visitorObj: Visitor = typeof visitor === 'function' ? {enter: visitor} : visitor;
+
+    const state: TraversalState = {
+        visitor: visitorObj,
+        parents: []
+    };
+
+    visitNode(node, state, undefined, undefined, undefined);
+}
+
+/**
+ * Visits a single node and its children.
+ */
+function visitNode(
+    node: AstEntity,
+    state: TraversalState,
+    parent: AstEntity | undefined,
+    key: string | undefined,
+    index: number | undefined
+): void {
+    const context: TraversalContext = {
+        node,
+        parent,
+        parents: [...state.parents],
+        key,
+        index
+    };
+
+    // Call enter hook
+    let skipChildren = false;
+    if (state.visitor.enter) {
+        const result = state.visitor.enter(node, context);
+        if (result === false) {
+            skipChildren = true;
+        }
+    }
+
+    // Visit children unless skipped
+    if (!skipChildren) {
+        state.parents.push(node);
+        visitChildren(node, state);
+        state.parents.pop();
+    }
+
+    // Call exit hook
+    if (state.visitor.exit) {
+        state.visitor.exit(node, context);
+    }
+}
+
+/**
+ * Visits all children of a node based on its type.
+ */
+function visitChildren(node: AstEntity, state: TraversalState): void {
+    switch (node.type) {
+        case 'Selector':
+            visitSelector(node, state);
+            break;
+        case 'Rule':
+            visitRule(node, state);
+            break;
+        case 'TagName':
+            visitTagName(node, state);
+            break;
+        case 'WildcardTag':
+            visitWildcardTag(node, state);
+            break;
+        case 'Attribute':
+            visitAttribute(node, state);
+            break;
+        case 'PseudoClass':
+            visitPseudoClass(node, state);
+            break;
+        case 'PseudoElement':
+            visitPseudoElement(node, state);
+            break;
+        case 'FormulaOfSelector':
+            visitFormulaOfSelector(node, state);
+            break;
+        // Leaf nodes with no children
+        case 'Id':
+        case 'ClassName':
+        case 'NamespaceName':
+        case 'WildcardNamespace':
+        case 'NoNamespace':
+        case 'NestingSelector':
+        case 'String':
+        case 'Formula':
+        case 'Substitution':
+            // No children to visit
+            break;
+    }
+}
+
+function visitSelector(node: AstSelector, state: TraversalState): void {
+    node.rules.forEach((rule, index) => {
+        visitNode(rule, state, node, 'rules', index);
+    });
+}
+
+function visitRule(node: AstRule, state: TraversalState): void {
+    node.items.forEach((item, index) => {
+        visitNode(item, state, node, 'items', index);
+    });
+
+    if (node.nestedRule) {
+        visitNode(node.nestedRule, state, node, 'nestedRule', undefined);
+    }
+}
+
+function visitTagName(node: AstTagName, state: TraversalState): void {
+    if (node.namespace) {
+        visitNode(node.namespace, state, node, 'namespace', undefined);
+    }
+}
+
+function visitWildcardTag(node: AstWildcardTag, state: TraversalState): void {
+    if (node.namespace) {
+        visitNode(node.namespace, state, node, 'namespace', undefined);
+    }
+}
+
+function visitAttribute(node: AstAttribute, state: TraversalState): void {
+    if (node.namespace) {
+        visitNode(node.namespace, state, node, 'namespace', undefined);
+    }
+    if (node.value) {
+        visitNode(node.value, state, node, 'value', undefined);
+    }
+}
+
+function visitPseudoClass(node: AstPseudoClass, state: TraversalState): void {
+    if (node.argument) {
+        visitNode(node.argument, state, node, 'argument', undefined);
+    }
+}
+
+function visitPseudoElement(node: AstPseudoElement, state: TraversalState): void {
+    if (node.argument) {
+        visitNode(node.argument, state, node, 'argument', undefined);
+    }
+}
+
+function visitFormulaOfSelector(node: AstFormulaOfSelector, state: TraversalState): void {
+    visitNode(node.selector, state, node, 'selector', undefined);
+}

test/import.ts

@@ -1,8 +1,9 @@
 import * as Lib from '../src/index.js';
 
 // eslint-disable-next-line @typescript-eslint/no-var-requires
-const {ast, render, createParser} = require(
+const {ast, render, createParser, traverse} = require(
     process.env.TEST_DIST ? `../dist/${process.env.TEST_DIST}/index.js` : '../src/index.js'
 ) as typeof Lib;
 
-export {ast, render, createParser};
+export {ast, render, createParser, traverse};
+export type {AstEntity, AstSelector, TraversalContext} from '../src/index.js';