breaking: always wrap selectors in selector_list node

bartveneman · bartveneman · commit 0dbde1ed35e7 · 2025-11-19T18:09:43.000+01:00
diff --git a/API.md b/API.md
@@ -79,7 +79,8 @@ console.log(declaration.value) // "red"
 ```
 Stylesheet (NODE_STYLESHEET)
   └─ StyleRule (NODE_STYLE_RULE)
-       ├─ Selector (NODE_SELECTOR) "body"
+       ├─ SelectorList (NODE_SELECTOR_LIST) "body"
+       │    └─ Type (NODE_SELECTOR_TYPE) "body"
        └─ Declaration (NODE_DECLARATION) "color: red"
             └─ Keyword (NODE_VALUE_KEYWORD) "red"
 ```
@@ -234,8 +235,9 @@ import { parse_selector } from '@projectwallace/css-parser'
 
 const selector = parse_selector('div.class > p#id::before')
 
-console.log(selector.type) // NODE_SELECTOR
-for (const part of selector) {
+console.log(selector.type) // NODE_SELECTOR_LIST
+// Iterate over selector components
+for (const part of selector.first_child) {
 	console.log(part.type, part.text)
 }
 // NODE_SELECTOR_TYPE "div"
@@ -290,7 +292,8 @@ walk(ast, (node, depth) => {
 })
 // NODE_STYLESHEET
 //   NODE_STYLE_RULE
-//     NODE_SELECTOR
+//     NODE_SELECTOR_LIST
+//       NODE_SELECTOR_TYPE
 //     NODE_DECLARATION
 //       NODE_VALUE_KEYWORD
 ```
diff --git a/src/column-tracking.test.ts b/src/column-tracking.test.ts
@@ -1,6 +1,6 @@
 import { describe, test, expect } from 'vitest'
 import { parse } from './parse'
-import { NODE_STYLE_RULE, NODE_DECLARATION, NODE_AT_RULE, NODE_SELECTOR } from './parser'
+import { NODE_STYLE_RULE, NODE_DECLARATION, NODE_AT_RULE, NODE_SELECTOR_LIST } from './parser'
 
 describe('Column Tracking', () => {
 	test('should track column for single-line CSS', () => {
@@ -21,7 +21,7 @@ describe('Column Tracking', () => {
 		// Selector (body)
 		const selector = rule!.first_child
 		expect(selector).not.toBeNull()
-		expect(selector!.type).toBe(NODE_SELECTOR)
+		expect(selector!.type).toBe(NODE_SELECTOR_LIST)
 		expect(selector!.line).toBe(1)
 		expect(selector!.column).toBe(1)
 
diff --git a/src/css-node.test.ts b/src/css-node.test.ts
@@ -1,6 +1,6 @@
 import { describe, test, expect } from 'vitest'
 import { Parser } from './parser'
-import { NODE_DECLARATION, NODE_SELECTOR, NODE_STYLE_RULE, NODE_AT_RULE } from './arena'
+import { NODE_DECLARATION, NODE_SELECTOR_LIST, NODE_STYLE_RULE, NODE_AT_RULE } from './arena'
 
 describe('CSSNode', () => {
 	describe('iteration', () => {
@@ -16,7 +16,7 @@ describe('CSSNode', () => {
 				types.push(child.type)
 			}
 
-			expect(types).toEqual([NODE_SELECTOR, NODE_DECLARATION, NODE_DECLARATION, NODE_DECLARATION])
+			expect(types).toEqual([NODE_SELECTOR_LIST, NODE_DECLARATION, NODE_DECLARATION, NODE_DECLARATION])
 		})
 
 		test('should work with spread operator', () => {
diff --git a/src/parse-selector.test.ts b/src/parse-selector.test.ts
@@ -1,156 +1,156 @@
 import { describe, test, expect } from 'vitest'
 import { parse_selector } from './parse-selector'
-import { NODE_SELECTOR } from './arena'
+import { NODE_SELECTOR_LIST } from './arena'
 
 describe('parse_selector()', () => {
 	test('should parse simple type selector', () => {
 		const result = parse_selector('div')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('div')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse class selector', () => {
 		const result = parse_selector('.classname')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('.classname')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse ID selector', () => {
 		const result = parse_selector('#identifier')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('#identifier')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse compound selector', () => {
 		const result = parse_selector('div.class#id')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('div.class#id')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse complex selector with combinator', () => {
 		const result = parse_selector('div.class > p#id')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('div.class > p#id')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse selector list', () => {
 		const result = parse_selector('h1, h2, h3')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('h1, h2, h3')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse pseudo-class selector', () => {
 		const result = parse_selector('a:hover')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('a:hover')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse pseudo-class with function', () => {
 		const result = parse_selector(':nth-child(2n+1)')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe(':nth-child(2n+1)')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse attribute selector', () => {
 		const result = parse_selector('[href^="https"]')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('[href^="https"]')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse universal selector', () => {
 		const result = parse_selector('*')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('*')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse nesting selector', () => {
 		const result = parse_selector('& .child')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('& .child')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse descendant combinator', () => {
 		const result = parse_selector('div span')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('div span')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse child combinator', () => {
 		const result = parse_selector('ul > li')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('ul > li')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse adjacent sibling combinator', () => {
 		const result = parse_selector('h1 + p')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('h1 + p')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse general sibling combinator', () => {
 		const result = parse_selector('h1 ~ p')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('h1 ~ p')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse modern pseudo-classes', () => {
 		const result = parse_selector(':is(h1, h2, h3)')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe(':is(h1, h2, h3)')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse :where() pseudo-class', () => {
 		const result = parse_selector(':where(.a, .b)')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe(':where(.a, .b)')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse :has() pseudo-class', () => {
 		const result = parse_selector('div:has(> img)')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('div:has(> img)')
 		expect(result.has_children).toBe(true)
 	})
 
 	test('should parse empty selector', () => {
 		const result = parse_selector('')
 
-		expect(result.type).toBe(NODE_SELECTOR)
+		expect(result.type).toBe(NODE_SELECTOR_LIST)
 		expect(result.text).toBe('')
 	})
 
diff --git a/src/parse-selector.ts b/src/parse-selector.ts
@@ -1,4 +1,4 @@
-import { CSSDataArena, NODE_SELECTOR } from './arena'
+import { CSSDataArena, NODE_SELECTOR_LIST } from './arena'
 import { SelectorParser } from './selector-parser'
 import { CSSNode } from './css-node'
 
@@ -18,9 +18,9 @@ export function parse_selector(source: string): CSSNode {
 	const selector_index = selector_parser.parse_selector(0, source.length)
 
 	if (selector_index === null) {
-		// Return empty selector node if parsing failed
+		// Return empty selector list node if parsing failed
 		const empty = arena.create_node()
-		arena.set_type(empty, NODE_SELECTOR)
+		arena.set_type(empty, NODE_SELECTOR_LIST)
 		arena.set_start_offset(empty, 0)
 		arena.set_length(empty, 0)
 		arena.set_start_line(empty, 1)
diff --git a/src/parser-options.test.ts b/src/parser-options.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest'
 import { Parser } from './parser'
-import { NODE_SELECTOR, NODE_DECLARATION, NODE_VALUE_KEYWORD } from './arena'
+import { NODE_SELECTOR_LIST, NODE_DECLARATION, NODE_VALUE_KEYWORD } from './arena'
 
 describe('Parser Options', () => {
 	const css = 'body { color: red; }'
@@ -12,10 +12,10 @@ describe('Parser Options', () => {
 			const rule = root.first_child
 
 			// Check selector is parsed with detailed structure
-			// All selectors wrapped in NODE_SELECTOR
+			// All selectors wrapped in NODE_SELECTOR_LIST
 			const selector = rule?.first_child
 			expect(selector).not.toBeNull()
-			expect(selector?.type).toBe(NODE_SELECTOR)
+			expect(selector?.type).toBe(NODE_SELECTOR_LIST)
 
 			// Check value is parsed with detailed structure
 			const declaration = selector?.next_sibling
@@ -31,9 +31,9 @@ describe('Parser Options', () => {
 			const rule = root.first_child
 
 			// Check selector is parsed
-			// Simple selector (just "body") returns NODE_SELECTOR directly
+			// Simple selector (just "body") returns NODE_SELECTOR_LIST directly
 			const selector = rule?.first_child
-			expect(selector?.type).toBe(NODE_SELECTOR)
+			expect(selector?.type).toBe(NODE_SELECTOR_LIST)
 
 			// Check value is parsed
 			const declaration = selector?.next_sibling
@@ -49,10 +49,10 @@ describe('Parser Options', () => {
 			const rule = root.first_child
 
 			// Selector should still be parsed
-			// Simple selector (just "body") returns NODE_SELECTOR directly
+			// Simple selector (just "body") returns NODE_SELECTOR_LIST directly
 			const selector = rule?.first_child
 			expect(selector).not.toBeNull()
-			expect(selector?.type).toBe(NODE_SELECTOR)
+			expect(selector?.type).toBe(NODE_SELECTOR_LIST)
 
 			// Declaration should exist but have no value children
 			const declaration = selector?.next_sibling
@@ -94,10 +94,10 @@ describe('Parser Options', () => {
 			const root = parser.parse()
 			const rule = root.first_child
 
-			// Selector should exist but be simple (just NODE_SELECTOR, no detailed structure)
+			// Selector should exist but be simple (just NODE_SELECTOR_LIST, no detailed structure)
 			const selector = rule?.first_child
 			expect(selector).not.toBeNull()
-			expect(selector?.type).toBe(NODE_SELECTOR)
+			expect(selector?.type).toBe(NODE_SELECTOR_LIST)
 			expect(selector?.text).toBe('body')
 			expect(selector?.has_children).toBe(false) // No detailed selector nodes
 
@@ -113,7 +113,7 @@ describe('Parser Options', () => {
 			const rule = root.first_child
 			const selector = rule?.first_child
 
-			expect(selector?.type).toBe(NODE_SELECTOR)
+			expect(selector?.type).toBe(NODE_SELECTOR_LIST)
 			expect(selector?.text).toBe('div.container#app')
 			expect(selector?.has_children).toBe(false)
 		})
@@ -124,7 +124,7 @@ describe('Parser Options', () => {
 			const rule = root.first_child
 			const selector = rule?.first_child
 
-			expect(selector?.type).toBe(NODE_SELECTOR)
+			expect(selector?.type).toBe(NODE_SELECTOR_LIST)
 			expect(selector?.text).toBe('div, p, span')
 			expect(selector?.has_children).toBe(false)
 		})
@@ -138,7 +138,7 @@ describe('Parser Options', () => {
 
 			// Selector should be simple
 			const selector = rule?.first_child
-			expect(selector?.type).toBe(NODE_SELECTOR)
+			expect(selector?.type).toBe(NODE_SELECTOR_LIST)
 			expect(selector?.text).toBe('body')
 			expect(selector?.has_children).toBe(false)
 
@@ -162,7 +162,7 @@ describe('Parser Options', () => {
 			const rule = root.first_child
 
 			const selector = rule?.first_child
-			expect(selector?.type).toBe(NODE_SELECTOR)
+			expect(selector?.type).toBe(NODE_SELECTOR_LIST)
 			expect(selector?.has_children).toBe(false)
 
 			const decl1 = selector?.next_sibling
@@ -234,7 +234,7 @@ describe('Parser Options', () => {
 			const declaration = selector?.next_sibling
 
 			// Should use defaults (both enabled)
-			expect(selector?.type).toBe(NODE_SELECTOR)
+			expect(selector?.type).toBe(NODE_SELECTOR_LIST)
 			expect(declaration?.has_children).toBe(true)
 		})
 
@@ -246,7 +246,7 @@ describe('Parser Options', () => {
 			const declaration = selector?.next_sibling
 
 			// Selector should still be parsed (default true)
-			expect(selector?.type).toBe(NODE_SELECTOR)
+			expect(selector?.type).toBe(NODE_SELECTOR_LIST)
 			// Values should not be parsed (explicitly false)
 			expect(declaration?.has_children).toBe(false)
 		})
diff --git a/src/parser.ts b/src/parser.ts
@@ -5,6 +5,7 @@ import {
 	NODE_STYLESHEET,
 	NODE_STYLE_RULE,
 	NODE_SELECTOR,
+	NODE_SELECTOR_LIST,
 	NODE_DECLARATION,
 	NODE_AT_RULE,
 	FLAG_IMPORTANT,
@@ -237,9 +238,9 @@ export class Parser {
 			}
 		}
 
-		// Otherwise create a simple selector node with just text offsets
+		// Otherwise create a simple selector list node with just text offsets
 		let selector = this.arena.create_node()
-		this.arena.set_type(selector, NODE_SELECTOR)
+		this.arena.set_type(selector, NODE_SELECTOR_LIST)
 		this.arena.set_start_line(selector, selector_line)
 		this.arena.set_start_column(selector, selector_column)
 		this.arena.set_start_offset(selector, selector_start)
diff --git a/src/selector-parser.test.ts b/src/selector-parser.test.ts
diff --git a/src/selector-parser.ts b/src/selector-parser.ts
diff --git a/src/walk.test.ts b/src/walk.test.ts
