fix: when parse_* is false, add RAW nodes to AST (#155)

- src/parse.ts: Selector fallback now creates a RAW node when
parse_selectors_enabled is false, instead of always using SELECTOR_LIST
- src/parse-declaration.ts: Added RAW import and an else branch that
creates a
RAW node as a child of DECLARATION when value_parser is null
(parse_values:
  false)
- src/css-node.ts: Updated the value getter to only return first_child
when
it's a VALUE node (not RAW), keeping declaration.value returning the raw
text
  string when parse_values: false
- src/parse-options.test.ts: Updated 9 test assertions — has_children:
false →
  true for parse_values:false cases, SELECTOR_LIST → RAW for
parse_selectors:false cases, plus added first_child?.type === RAW
assertion
- src/walk.test.ts: Updated 19 expected type arrays — SELECTOR_LIST →
RAW for
all parse_selectors: false cases, and added RAW after DECLARATION for
all
  parse_values: false cases

some extras

- expose `ATTR_FLAG_NAMES` and `ATTR_OPERATOR_NAMES` publicly

Author: bartveneman

src/api.test.ts

@@ -13,7 +13,7 @@ import {
 	FUNCTION,
 	ATTRIBUTE_SELECTOR,
 } from './arena'
-import { PlainCSSNode } from './css-node'
+import { CSSNode, PlainCSSNode } from './css-node'
 
 describe('CSSNode', () => {
 	describe('iteration', () => {
@@ -65,7 +65,8 @@ describe('CSSNode', () => {
 			const importRule = root.first_child!
 			const children = [...importRule]
 
-			expect(children).toHaveLength(0)
+			// RAW prelude node is created when parse_atrule_preludes is false
+			expect(children).toHaveLength(1)
 		})
 	})
 
@@ -208,7 +209,7 @@ describe('CSSNode', () => {
 			expect(rule.has_prelude).toBe(true) // has selector
 
 			expect(declaration.has_prelude).toBe(false)
-			expect(declaration.value).toBe('red')
+			expect((declaration.value as PlainCSSNode).text).toBe('red')
 		})
 	})
 
@@ -771,7 +772,7 @@ describe('CSSNode', () => {
 				expect(clone.text).toBe('color: red;')
 				expect(clone.name).toBe(undefined)
 				expect(clone.property).toBe('color')
-				expect(clone.value).toBe('red')
+				expect((clone.value as PlainCSSNode).text).toBe('red')
 				expect(clone.children).toBeUndefined()
 			})
 
@@ -841,7 +842,7 @@ describe('CSSNode', () => {
 				expect(clone.type_name).toBe('Declaration')
 				expect(clone.property).toBe('color')
 				expect(clone.name).toBe(undefined)
-				expect(clone.value).toBe('red')
+				expect((clone.value as CSSNode)?.text).toBe('red')
 				expect(clone.is_important).toBe(true)
 			})
 
@@ -896,53 +897,53 @@ describe('CSSNode', () => {
 				expect(clone.attr_flags).toBeDefined()
 			})
 
-		test('returns human-readable attribute operator strings', () => {
-			const operators = [
-				{ selector: '[attr]', expected: null },
-				{ selector: '[attr="val"]', expected: '=' },
-				{ selector: '[attr~="val"]', expected: '~=' },
-				{ selector: '[attr|="val"]', expected: '|=' },
-				{ selector: '[attr^="val"]', expected: '^=' },
-				{ selector: '[attr$="val"]', expected: '$=' },
-				{ selector: '[attr*="val"]', expected: '*=' },
-			]
-
-			for (const { selector, expected } of operators) {
-				const ast = parse_selector(selector)
-				const attribute = ast.first_child!.first_child!
-				const clone = attribute.clone({ deep: false })
+			test('returns human-readable attribute operator strings', () => {
+				const operators = [
+					{ selector: '[attr]', expected: null },
+					{ selector: '[attr="val"]', expected: '=' },
+					{ selector: '[attr~="val"]', expected: '~=' },
+					{ selector: '[attr|="val"]', expected: '|=' },
+					{ selector: '[attr^="val"]', expected: '^=' },
+					{ selector: '[attr$="val"]', expected: '$=' },
+					{ selector: '[attr*="val"]', expected: '*=' },
+				]
+
+				for (const { selector, expected } of operators) {
+					const ast = parse_selector(selector)
+					const attribute = ast.first_child!.first_child!
+					const clone = attribute.clone({ deep: false })
+
+					expect(clone.attr_operator).toBe(expected)
+				}
+			})
 
-				expect(clone.attr_operator).toBe(expected)
-			}
-		})
+			test('returns human-readable attribute flag strings', () => {
+				const flags = [
+					{ selector: '[attr="val"]', expected: null },
+					{ selector: '[attr="val" i]', expected: 'i' },
+					{ selector: '[attr="val" s]', expected: 's' },
+				]
 
-		test('returns human-readable attribute flag strings', () => {
-			const flags = [
-				{ selector: '[attr="val"]', expected: null },
-				{ selector: '[attr="val" i]', expected: 'i' },
-				{ selector: '[attr="val" s]', expected: 's' },
-			]
+				for (const { selector, expected } of flags) {
+					const ast = parse_selector(selector)
+					const attribute = ast.first_child!.first_child!
+					const clone = attribute.clone({ deep: false })
 
-			for (const { selector, expected } of flags) {
-				const ast = parse_selector(selector)
-				const attribute = ast.first_child!.first_child!
-				const clone = attribute.clone({ deep: false })
-
-				expect(clone.attr_flags).toBe(expected)
-			}
-		})
+					expect(clone.attr_flags).toBe(expected)
+				}
+			})
 
-		test('extracts nth selector properties', () => {
-			const ast = parse_selector(':nth-child(2n+1)')
-			const selector = ast.first_child!
-			const pseudo = selector.first_child!
-			const nth = pseudo.first_child!
+			test('extracts nth selector properties', () => {
+				const ast = parse_selector(':nth-child(2n+1)')
+				const selector = ast.first_child!
+				const pseudo = selector.first_child!
+				const nth = pseudo.first_child!
 
-			const clone = nth.clone({ deep: false })
+				const clone = nth.clone({ deep: false })
 
-			expect(clone.type).toBe(NTH_SELECTOR)
-			expect(clone.nth_a).toBe('2n')
-			expect(clone.nth_b).toBe('+1')
+				expect(clone.type).toBe(NTH_SELECTOR)
+				expect(clone.nth_a).toBe('2n')
+				expect(clone.nth_b).toBe('+1')
 			})
 		})
 

src/arena.ts

@@ -51,6 +51,7 @@ export const DECLARATION = 4
 export const SELECTOR = 5
 export const COMMENT = 6
 export const BLOCK = 7 // Block container for declarations and nested rules
+export const RAW = 8 // Unparsed nodes
 
 // Value node type constants (for declaration values)
 export const IDENTIFIER = 10 // identifier: red, auto, inherit

src/constants.ts

@@ -9,6 +9,7 @@ import {
 	SELECTOR,
 	COMMENT,
 	BLOCK,
+	RAW,
 	IDENTIFIER,
 	NUMBER,
 	DIMENSION,
@@ -62,6 +63,7 @@ export {
 	SELECTOR,
 	COMMENT,
 	BLOCK,
+	RAW,
 	IDENTIFIER,
 	NUMBER,
 	DIMENSION,
@@ -117,6 +119,7 @@ export const NODE_TYPES = {
 	SELECTOR,
 	COMMENT,
 	BLOCK,
+	RAW,
 	// Value nodes
 	IDENTIFIER,
 	NUMBER,

src/css-node.ts

@@ -1,6 +1,7 @@
 // CSSNode - Ergonomic wrapper over arena node indices
 import type { CSSDataArena } from './arena'
 import {
+	RAW,
 	STYLESHEET,
 	STYLE_RULE,
 	AT_RULE,
@@ -71,6 +72,7 @@ export const TYPE_NAMES = {
 	[SELECTOR]: 'Selector',
 	[COMMENT]: 'Comment',
 	[BLOCK]: 'Block',
+	[RAW]: 'Raw',
 	[IDENTIFIER]: 'Identifier',
 	[NUMBER]: 'Number',
 	[DIMENSION]: 'Dimension',
@@ -135,6 +137,7 @@ export type CSSNodeType =
 	| typeof SELECTOR
 	| typeof COMMENT
 	| typeof BLOCK
+	| typeof RAW
 	| typeof IDENTIFIER
 	| typeof NUMBER
 	| typeof DIMENSION
@@ -356,7 +359,7 @@ export class CSSNode {
 	get prelude(): CSSNode | null | undefined {
 		if (this.type === AT_RULE) {
 			let first = this.first_child
-			if (first && first.type === AT_RULE_PRELUDE) {
+			if (first?.type === AT_RULE_PRELUDE || first?.type === RAW) {
 				return first
 			}
 			return null

src/index.ts

@@ -15,7 +15,15 @@ export { is_custom, is_vendor_prefixed, str_equals, str_starts_with, str_index_o
 export { type ParserOptions } from './parse'
 
 // Types
-export { CSSNode, type CSSNodeType, TYPE_NAMES, type CloneOptions, type PlainCSSNode } from './css-node'
+export {
+	CSSNode,
+	type CSSNodeType,
+	TYPE_NAMES,
+	type CloneOptions,
+	type PlainCSSNode,
+	ATTR_FLAG_NAMES,
+	ATTR_OPERATOR_NAMES,
+} from './css-node'
 export type { LexerPosition, CommentInfo } from './tokenize'
 
 export {

src/parse-declaration.ts

@@ -1,6 +1,6 @@
 // Declaration Parser - Parses CSS declarations into structured AST nodes
 import { Lexer } from './tokenize'
-import { CSSDataArena, DECLARATION, FLAG_IMPORTANT, FLAG_BROWSERHACK } from './arena'
+import { CSSDataArena, DECLARATION, RAW, FLAG_IMPORTANT, FLAG_BROWSERHACK } from './arena'
 import { ValueParser } from './parse-value'
 import { is_vendor_prefixed } from './string-utils'
 import {
@@ -119,11 +119,7 @@ export class DeclarationParser {
 		}
 
 		// Expect identifier, at-keyword, or hash token (property name) - whitespace already skipped by caller
-		if (
-			lexer.token_type !== TOKEN_IDENT &&
-			lexer.token_type !== TOKEN_AT_KEYWORD &&
-			lexer.token_type !== TOKEN_HASH
-		) {
+		if (lexer.token_type !== TOKEN_IDENT && lexer.token_type !== TOKEN_AT_KEYWORD && lexer.token_type !== TOKEN_HASH) {
 			return null
 		}
 
@@ -228,6 +224,10 @@ export class DeclarationParser {
 
 				// Link VALUE node as single child of the declaration
 				this.arena.append_children(declaration, [valueNode])
+			} else {
+				// Create RAW node for unparsed value text
+				let rawNode = this.arena.create_node(RAW, trimmed[0], trimmed[1] - trimmed[0], value_start_line, value_start_column)
+				this.arena.append_children(declaration, [rawNode])
 			}
 		} else {
 			// Empty value - set zero-length value field so node.value returns "" instead of null