Walk and traverse should give context

[bartveneman]

Add optional context to walk/traverse so a selector can know if it's inside a @keyframes, a declaration knows if it's inside a @supports, etc etc.

• Parent atrule
• parent rule
• nesting depth

[bartveneman]

Claude's plan

---

Implementation Plan: Optional Context for walk() and traverse()

Overview

Add optional context tracking to walk() and traverse() functions, allowing nodes to know their closest ancestor of specific types (rule, at-rule, declaration, value, selector). This enables use cases like:

• "Is this selector inside a @Keyframes?" → check context.atrule?.name === 'keyframes'
• "Is this declaration inside a @supports?" → check context.atrule?.name === 'supports'

Design Decisions

Context scope: Track only closest ancestor of specific types (rule, atrule, declaration, value, selector) - much simpler and lighter than tracking full ancestry arrays.

Performance: 4-7x CPU overhead and ~44% memory overhead acceptable since this is opt-in.

API: Single include_context option - keep it simple.

API Design

WalkContext Interface

interface WalkContext {
	// Closest ancestors by type (null if none exists)
	rule: CSSNode | null          // Closest STYLE_RULE
	atrule: CSSNode | null         // Closest AT_RULE
	declaration: CSSNode | null    // Closest DECLARATION
	value: CSSNode | null          // Closest value node (any type 10-18)
	selector: CSSNode | null       // Closest selector node (any type 20-31)

	// Convenience fields
	parent: CSSNode | null         // Immediate parent
	depth: number                  // Current depth (0 for root)
}

Function Signatures

walk():

function walk(
	node: CSSNode,
	callback: (node: CSSNode, depth: number, context?: WalkContext) => void | typeof SKIP | typeof BREAK,
	options?: WalkOptions | number  // number for backward compat (depth)
): boolean

interface WalkOptions {
	depth?: number                 // Starting depth (default: 0)
	include_context?: boolean      // Enable context (default: false)
}

traverse():

function traverse(
	node: CSSNode,
	options?: TraverseOptions
): boolean

interface TraverseOptions {
	enter?: (node: CSSNode, context?: WalkContext) => void | typeof SKIP | typeof BREAK
	leave?: (node: CSSNode, context?: WalkContext) => void | typeof SKIP | typeof BREAK
	include_context?: boolean      // Enable context (default: false)
}

Usage Examples

// Example 1: Find selectors inside @keyframes
walk(ast, (node, depth, context) => {
	if (node.type === SELECTOR && context?.atrule?.name === 'keyframes') {
		console.log('Selector in @keyframes:', node.text)
	}
}, { include_context: true })

// Example 2: Find declarations inside @supports
walk(ast, (node, depth, context) => {
	if (node.type === DECLARATION && context?.atrule?.name === 'supports') {
		console.log('Progressive enhancement:', node.property)
	}
}, { include_context: true })

// Example 3: Check if declaration is inside a style rule vs at-rule
walk(ast, (node, depth, context) => {
	if (node.type === DECLARATION) {
		if (context?.rule) {
			console.log('In style rule')
		} else if (context?.atrule) {
			console.log('In at-rule:', context.atrule.name)
		}
	}
}, { include_context: true })

// Example 4: Backward compatible - no context
walk(ast, (node, depth) => {
	console.log(node.type, depth)
})

Implementation Strategy

Context Building Logic

Key insight: Instead of building arrays, we maintain "current" pointers for each type category:

1. Start with all pointers null
2. As we descend into a node:
   • If node is STYLE_RULE, update current_rule
   • If node is AT_RULE, update current_atrule
   • If node is DECLARATION, update current_declaration
   • If node is value type (10-18), update current_value
   • If node is selector type (20-31), update current_selector
3. Pass current pointers as context to callback
4. When recursing to children, pass updated pointers
5. After visiting children, pointers automatically revert (via function scope)

Node type categorization:

• Rule: type === STYLE_RULE (type 2)
• At-rule: type === AT_RULE (type 3)
• Declaration: type === DECLARATION (type 4)
• Value: type >= 10 && type <= 18
• Selector: type >= 20 && type <= 31

walk() Implementation

export function walk(
	node: CSSNode,
	callback: (node: CSSNode, depth: number, context?: WalkContext) => void | typeof SKIP | typeof BREAK,
	options: WalkOptions | number = 0
): boolean {
	// Handle backward compat (old signature: walk(node, cb, depth))
	const opts = typeof options === 'number'
		? { depth: options, include_context: false }
		: options

	return walk_impl(
		node,
		callback,
		opts.depth ?? 0,
		opts.include_context ?? false,
		null, // parent
		null, // current_rule
		null, // current_atrule
		null, // current_declaration
		null, // current_value
		null  // current_selector
	)
}

function walk_impl(
	node: CSSNode,
	callback: (node: CSSNode, depth: number, context?: WalkContext) => void | typeof SKIP | typeof BREAK,
	depth: number,
	include_context: boolean,
	parent: CSSNode | null,
	current_rule: CSSNode | null,
	current_atrule: CSSNode | null,
	current_declaration: CSSNode | null,
	current_value: CSSNode | null,
	current_selector: CSSNode | null
): boolean {
	// Build context if enabled
	let context: WalkContext | undefined
	if (include_context) {
		context = {
			rule: current_rule,
			atrule: current_atrule,
			declaration: current_declaration,
			value: current_value,
			selector: current_selector,
			parent,
			depth
		}
	}

	// Call callback
	const result = include_context
		? callback(node, depth, context)
		: callback(node, depth, undefined)

	if (result === BREAK) return false
	if (result === SKIP) return true

	// Update current pointers based on node type
	const next_rule = node.type === STYLE_RULE ? node : current_rule
	const next_atrule = node.type === AT_RULE ? node : current_atrule
	const next_declaration = node.type === DECLARATION ? node : current_declaration
	const next_value = (node.type >= 10 && node.type <= 18) ? node : current_value
	const next_selector = (node.type >= 20 && node.type <= 31) ? node : current_selector

	// Recurse to children
	let child = node.first_child
	while (child) {
		const should_continue = walk_impl(
			child,
			callback,
			depth + 1,
			include_context,
			node, // parent
			next_rule,
			next_atrule,
			next_declaration,
			next_value,
			next_selector
		)
		if (!should_continue) return false
		child = child.next_sibling
	}

	return true
}

traverse() Implementation

Similar structure to walk() but with enter/leave callbacks:

export function traverse(
	node: CSSNode,
	options: TraverseOptions = {}
): boolean {
	const { enter = NOOP, leave = NOOP, include_context = false } = options

	return traverse_impl(
		node,
		enter,
		leave,
		0, // depth
		include_context,
		null, // parent
		null, // current_rule
		null, // current_atrule
		null, // current_declaration
		null, // current_value
		null  // current_selector
	)
}

function traverse_impl(
	node: CSSNode,
	enter: (node: CSSNode, context?: WalkContext) => void | typeof SKIP | typeof BREAK,
	leave: (node: CSSNode, context?: WalkContext) => void | typeof SKIP | typeof BREAK,
	depth: number,
	include_context: boolean,
	parent: CSSNode | null,
	current_rule: CSSNode | null,
	current_atrule: CSSNode | null,
	current_declaration: CSSNode | null,
	current_value: CSSNode | null,
	current_selector: CSSNode | null
): boolean {
	// Build context (same as walk)
	let context: WalkContext | undefined
	if (include_context) {
		context = {
			rule: current_rule,
			atrule: current_atrule,
			declaration: current_declaration,
			value: current_value,
			selector: current_selector,
			parent,
			depth
		}
	}

	// Call enter
	const enter_result = include_context
		? enter(node, context)
		: enter(node, undefined)

	if (enter_result === BREAK) return false

	// Traverse children if not SKIP
	if (enter_result !== SKIP) {
		// Update current pointers (same as walk)
		const next_rule = node.type === STYLE_RULE ? node : current_rule
		const next_atrule = node.type === AT_RULE ? node : current_atrule
		const next_declaration = node.type === DECLARATION ? node : current_declaration
		const next_value = (node.type >= 10 && node.type <= 18) ? node : current_value
		const next_selector = (node.type >= 20 && node.type <= 31) ? node : current_selector

		let child = node.first_child
		while (child) {
			const should_continue = traverse_impl(
				child,
				enter,
				leave,
				depth + 1,
				include_context,
				node,
				next_rule,
				next_atrule,
				next_declaration,
				next_value,
				next_selector
			)
			if (!should_continue) return false
			child = child.next_sibling
		}
	}

	// Call leave (always called even if children skipped)
	const leave_result = include_context
		? leave(node, context)
		: leave(node, undefined)

	return leave_result !== BREAK
}

Performance Analysis

Memory Overhead

Without context (current):

• Zero allocations during traversal
• Only recursion call stack: ~16 bytes/frame

With context enabled:

• WalkContext object: ~56 bytes (7 pointers × 8 bytes)
• Additional function parameters: ~48 bytes (6 node pointers)
• Total per node: ~104 bytes

For typical AST:

• 1,000 nodes: ~104 KB
• 10,000 nodes: ~1.04 MB
• 60,000 nodes (10MB CSS): ~6.24 MB

Comparison:

• 10MB CSS base parse: ~32 MB
• With context: ~32 MB + ~6 MB = ~38 MB
• Overhead: ~19% (much better than original 44% estimate!)

CPU Overhead

Operations per node when context enabled:

1. Type checks (5 comparisons): ~10 cycles
2. Pointer updates (5 assignments): ~5 cycles
3. Object creation (1 allocation): ~100 cycles
4. Total: ~115 cycles ≈ 0.05 μs on modern CPU

For 60K nodes: ~3ms additional overhead

Actual overhead likely 2-3x slower (not 4-7x) due to simpler design with no array operations.

Why faster than initial estimate:

• No array cloning ([...parents, node])
• No array filtering (building ancestor_atrules)
• No string concatenation (building path)
• Just simple pointer assignments

When Overhead is Acceptable

✅ Good use cases:

• Analysis tools (linters, formatters)
• One-time AST inspection
• Build-time processing
• Files < 5MB

❌ Avoid for:

• Hot path parsing (real-time)
• Repeated walks without caching
• Memory-constrained environments

Critical Files

Main implementation:

• src/walk.ts - Add context types, update walk()/traverse() implementations

Type exports:

• src/index.ts - Export WalkContext, WalkOptions, TraverseOptions types

Tests:

• src/walk.test.ts - Add comprehensive test suite for context functionality

Constants needed:

• src/constants.ts - Reference STYLE_RULE, AT_RULE, DECLARATION constants

Test Coverage

Core Functionality Tests

describe('walk with context', () => {
	test('provides closest rule ancestor')
	test('provides closest atrule ancestor')
	test('provides closest declaration ancestor')
	test('provides closest value ancestor')
	test('provides closest selector ancestor')
	test('provides immediate parent')
	test('provides correct depth')
	test('context is undefined when not enabled')
	test('backward compatible with old signature')
})

describe('traverse with context', () => {
	test('provides context in enter callback')
	test('provides context in leave callback')
	test('context is undefined when not enabled')
})

Use Case Tests

describe('real-world use cases', () => {
	test('detect selector inside @keyframes')
	test('detect declaration inside @supports')
	test('detect nested at-rules (@media > @supports)')
	test('distinguish declaration in rule vs at-rule')
	test('track value context in complex expressions')
})

Edge Cases

describe('edge cases', () => {
	test('context is null at root level')
	test('SKIP prevents context for children')
	test('BREAK stops immediately')
	test('deeply nested structures')
	test('multiple at-rules of same type')
})

Documentation Updates

CLAUDE.md

Update walk control flow section:

**Walk context:** Optionally track closest ancestors by type:
- `walk(node, callback, {include_context: true})` - callback receives (node, depth, context)
- Context provides: rule, atrule, declaration, value, selector ancestors
- Performance: ~2-3x slower, ~19% more memory - only enable when needed
- Example: Check if selector inside @keyframes with `context?.atrule?.name === 'keyframes'`

JSDoc Comments

Add performance warnings to function documentation:

/**
 * @param options.include_context - Enable ancestor tracking (default: false)
 *   WARNING: Adds ~2-3x CPU overhead. Only enable when you need ancestor context.
 */

Implementation Steps

1. Update types in src/walk.ts:

   • Add WalkContext interface
   • Add WalkOptions interface
   • Add TraverseOptions interface
   • Update function signatures

2. Implement walk_impl() helper with context parameters

3. Update walk() to handle options and delegate to walk_impl()

4. Implement traverse_impl() helper with context parameters

5. Update traverse() to handle options and delegate to traverse_impl()

6. Export types from src/index.ts

7. Add tests to src/walk.test.ts:

   • Core functionality (~7 tests)
   • Use cases (~5 tests)
   • Edge cases (~5 tests)

8. Update documentation:

   • Add JSDoc comments with performance warnings
   • Update CLAUDE.md with context tracking notes

Breaking Changes

None - fully backward compatible:

• Old signature walk(node, cb, depth) still works
• Old signature traverse(node, {enter, leave}) still works
• Context is opt-in via include_context: true

Estimated Performance Impact Summary

Metric	Without Context	With Context	Overhead
CPU Time (10MB file)	~100ms	~200-300ms	2-3x
Memory (10MB file)	~32 MB	~38 MB	+19%
Allocations	0	1 per node	N/A

Conclusion: Performance overhead is acceptable for the intended use cases (analysis, linting, build tools) since it's opt-in and provides significant value for context-aware traversal.