@tsrx/core 0.1.50 → 0.1.52

package/src/transform/scoping.js

@@ -6,11 +6,16 @@
  */
 
 /** @import * as AST from 'estree' */
+/** @import * as ESTreeJSX from 'estree-jsx' */
+/** @import { Visitors } from '../../types/index' */
 
 import { walk } from 'zimmerframe';
 import * as b from '../utils/builders.js';
+import { is_ast_node, is_style_element } from '../utils/ast.js';
 import { mark_class_map_selectors } from './style-ref.js';
 
+export { is_style_element };
+
 /**
  * Mark selectors inside the stylesheet as "used" so `renderStylesheets` does
  * not comment them out.
@@ -28,36 +33,35 @@ import { mark_class_map_selectors } from './style-ref.js';
  * along with their parent: they apply where the parent's class matched, and the
  * whole rule is pruned when the parent itself is unreachable.
  *
- * @param {any} stylesheet
+ * @param {AST.CSS.StyleSheet} stylesheet
  * @param {boolean} [is_style_expression]
- * @returns {any}
+ * @returns {AST.CSS.StyleSheet}
  */
 export function prepare_stylesheet_for_render(stylesheet, is_style_expression = false) {
 	if (is_style_expression) {
 		mark_class_map_selectors(stylesheet);
 	}
-	walk(stylesheet, null, {
-		_(node, { next, path }) {
-			if (node && node.metadata && typeof node.metadata === 'object') {
-				if (
-					is_style_expression &&
-					node.type === 'ComplexSelector' &&
-					is_unreachable_via_class_map(node, path)
-				) {
-					// Not in the generated class map. The analyzer pre-marks global
-					// selectors as used, so reset, and leave the subtree untouched —
-					// no `scoped` marks that would splice the hash into pruned output.
-					node.metadata.used = false;
-					return;
-				}
-				node.metadata.used = true;
-				if (node.type === 'RelativeSelector' && !node.metadata.is_global) {
+	walk(
+		/** @type {AST.CSS.Node} */ (stylesheet),
+		null,
+		/** @type {Visitors<AST.CSS.Node, null>} */ ({
+			_(node, { next, path }) {
+				if (node.type === 'ComplexSelector') {
+					if (is_style_expression && is_unreachable_via_class_map(node, path)) {
+						// Not in the generated class map. The analyzer pre-marks global
+						// selectors as used, so reset, and leave the subtree untouched —
+						// no `scoped` marks that would splice the hash into pruned output.
+						node.metadata.used = false;
+						return;
+					}
+					node.metadata.used = true;
+				} else if (node.type === 'RelativeSelector' && !node.metadata.is_global) {
 					node.metadata.scoped = true;
 				}
-			}
-			return next();
-		},
-	});
+				return next();
+			},
+		}),
+	);
 	return stylesheet;
 }
 
@@ -73,8 +77,8 @@ export function prepare_stylesheet_for_render(stylesheet, is_style_expression =
  * is kept because its contents render unscoped as authored and cannot be
  * pruned selector-by-selector.
  *
- * @param {any} complex_selector
- * @param {any[]} path
+ * @param {AST.CSS.ComplexSelector} complex_selector
+ * @param {AST.CSS.Node[]} path
  * @returns {boolean}
  */
 function is_unreachable_via_class_map(complex_selector, path) {
@@ -82,8 +86,8 @@ function is_unreachable_via_class_map(complex_selector, path) {
 	if (complex_selector.metadata.rule?.metadata?.parent_rule != null) return false;
 	if (path.some((parent) => parent.type === 'ComplexSelector')) return false;
 
-	if (complex_selector.children?.length === 1) {
-		const first = complex_selector.children[0]?.selectors?.[0];
+	if (complex_selector.children.length === 1) {
+		const first = complex_selector.children[0].selectors[0];
 		if (first?.type === 'PseudoClassSelector' && first.name === 'global' && first.args === null) {
 			return false;
 		}
@@ -94,19 +98,15 @@ function is_unreachable_via_class_map(complex_selector, path) {
 
 /**
  * @param {AST.Node | null | undefined} node
- * @returns {node is AST.JSXStyleElement}
- */
-export function is_style_element(node) {
-	return !!node && node.type === 'JSXStyleElement';
-}
-
-/**
- * @param {any} node
  * @returns {boolean}
  */
 export function is_composite_jsx_element(node) {
-	const name = node?.openingElement?.name;
-	if (node?.type !== 'JSXElement' || !name) {
+	if (node?.type !== 'JSXElement') {
+		return false;
+	}
+
+	const name = node.openingElement?.name;
+	if (!name) {
 		return false;
 	}
 
@@ -121,11 +121,11 @@ export function is_composite_jsx_element(node) {
  * Recursively walk native JSX nodes within a TSRX fragment and add the hash
  * class name so scope-qualified selectors (e.g. `.foo.hash`) match.
  *
- * @param {any} node
+ * @param {AST.Node} node
  * @param {string} hash
  * @param {'class' | 'className'} [jsx_class_attr_name='class']
  * @param {boolean} [preserve_style_elements=false]
- * @returns {any}
+ * @returns {AST.Node | null}
  */
 export function annotate_with_hash(
 	node,
@@ -147,20 +147,17 @@ export function annotate_with_hash(
 	}
 
 	if (node.type === 'JSXElement') {
-		if (!is_composite_jsx_element(node) || node.metadata?.dynamicElement) {
-			add_hash_class_to_jsx_element(node, hash, jsx_class_attr_name);
-		}
-		if (Array.isArray(node.children)) {
-			node.children = node.children
-				.map((/** @type {any} */ child) =>
-					annotate_with_hash(child, hash, jsx_class_attr_name, preserve_style_elements),
-				)
-				.filter(Boolean);
+		const element = /** @type {AST.TSRXJSXElement} */ (node);
+		if (!is_composite_jsx_element(element) || element.metadata?.dynamicElement) {
+			add_hash_class_to_jsx_element(element, hash, jsx_class_attr_name);
 		}
-		return node;
+		element.children = element.children
+			.map((child) => annotate_with_hash(child, hash, jsx_class_attr_name, preserve_style_elements))
+			.filter((child) => child !== null);
+		return element;
 	}
 
-	if (node.type === 'JSXStyleElement') {
+	if (is_style_element(node)) {
 		if (preserve_style_elements) {
 			node.children = [];
 			return node;
@@ -168,18 +165,21 @@ export function annotate_with_hash(
 		return null;
 	}
 
-	for (const key of Object.keys(node)) {
+	const entries = /** @type {Record<string, unknown>} */ (node);
+	for (const key of Object.keys(entries)) {
 		if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata' || key === 'css') {
 			continue;
 		}
 
-		const value = node[key];
+		const value = entries[key];
 		if (Array.isArray(value)) {
-			node[key] = value.map((/** @type {any} */ child) =>
-				annotate_with_hash(child, hash, jsx_class_attr_name, preserve_style_elements),
+			entries[key] = value.map((child) =>
+				is_ast_node(child)
+					? annotate_with_hash(child, hash, jsx_class_attr_name, preserve_style_elements)
+					: child,
 			);
-		} else if (value && typeof value === 'object') {
-			node[key] = annotate_with_hash(value, hash, jsx_class_attr_name, preserve_style_elements);
+		} else if (is_ast_node(value)) {
+			entries[key] = annotate_with_hash(value, hash, jsx_class_attr_name, preserve_style_elements);
 		}
 	}
 
@@ -187,7 +187,8 @@ export function annotate_with_hash(
 }
 
 /**
- * @param {any} component
+ * @param {{ body: AST.Node[] }} component a node whose `body` holds the
+ *   component's template children
  * @param {string} hash
  * @param {'class' | 'className'} [jsx_class_attr_name='class']
  * @param {boolean} [preserve_style_elements=false]
@@ -199,32 +200,53 @@ export function annotate_component_with_hash(
 	jsx_class_attr_name = 'class',
 	preserve_style_elements = false,
 ) {
-	/** @type {any[]} */
-	const body = component.body;
-	component.body = body
-		.filter((/** @type {any} */ child) => preserve_style_elements || !is_style_element(child))
-		.map((/** @type {any} */ child) =>
-			annotate_with_hash(child, hash, jsx_class_attr_name, preserve_style_elements),
-		);
+	component.body = component.body
+		.filter((child) => preserve_style_elements || !is_style_element(child))
+		.map((child) => annotate_with_hash(child, hash, jsx_class_attr_name, preserve_style_elements))
+		.filter((child) => child !== null);
+}
+
+/**
+ * The element's `class`/`className` attribute, if it has a static-named one.
+ *
+ * @param {ESTreeJSX.JSXAttributeNode} attr
+ * @returns {attr is ESTreeJSX.JSXAttribute}
+ */
+function is_class_attribute(attr) {
+	return (
+		attr.type === 'JSXAttribute' &&
+		attr.name.type === 'JSXIdentifier' &&
+		(attr.name.name === 'class' || attr.name.name === 'className')
+	);
+}
+
+/**
+ * Merge the hash into an existing class attribute value. Returns `false` when
+ * the value is not a string literal, so the caller must wrap it instead.
+ *
+ * @param {ESTreeJSX.JSXAttribute['value'] | AST.Expression | ESTreeJSX.JSXEmptyExpression} value
+ * @param {string} hash
+ * @returns {boolean} whether the hash was merged into the literal in place
+ */
+function merge_hash_into_literal(value, hash) {
+	if (value?.type !== 'Literal' || typeof value.value !== 'string') return false;
+	const merged = `${value.value} ${hash}`;
+	value.value = merged;
+	value.raw = JSON.stringify(merged);
+	return true;
 }
 
 /**
  * Ensure the element carries a class attribute containing the scoping hash.
  *
- * @param {any} element
+ * @param {AST.TSRXJSXElement} element
  * @param {string} hash
  * @param {'class' | 'className'} [class_attr_name='class']
  * @returns {void}
  */
 export function add_hash_class(element, hash, class_attr_name = 'class') {
 	const attrs = element.openingElement.attributes;
-	const existing = attrs.find(
-		(/** @type {any} */ a) =>
-			a.type === 'JSXAttribute' &&
-			a.name &&
-			a.name.type === 'JSXIdentifier' &&
-			(a.name.name === 'class' || a.name.name === 'className'),
-	);
+	const existing = attrs.find(is_class_attribute);
 
 	if (!existing) {
 		attrs.push(b.jsx_attribute(b.jsx_id(class_attr_name), b.literal(hash)));
@@ -233,17 +255,12 @@ export function add_hash_class(element, hash, class_attr_name = 'class') {
 
 	const value =
 		existing.value?.type === 'JSXExpressionContainer' ? existing.value.expression : existing.value;
-	if (!value) {
-		existing.value = { type: 'Literal', value: hash, raw: JSON.stringify(hash) };
+	if (!value || value.type === 'JSXEmptyExpression') {
+		existing.value = b.literal(hash, JSON.stringify(hash));
 		return;
 	}
 
-	if (value.type === 'Literal' && typeof value.value === 'string') {
-		const merged = `${value.value} ${hash}`;
-		value.value = merged;
-		value.raw = JSON.stringify(merged);
-		return;
-	}
+	if (merge_hash_into_literal(value, hash)) return;
 
 	// Dynamic expression. Concatenate at runtime via template literal.
 	existing.value = b.jsx_expression_container(
@@ -252,46 +269,37 @@ export function add_hash_class(element, hash, class_attr_name = 'class') {
 }
 
 /**
- * @param {any} element
+ * @param {AST.TSRXJSXElement} element
  * @param {string} hash
  * @param {'class' | 'className'} jsx_class_attr_name
  * @returns {void}
  */
 function add_hash_class_to_jsx_element(element, hash, jsx_class_attr_name) {
-	const attrs = element.openingElement?.attributes || (element.openingElement.attributes = []);
-	const existing = attrs.find(
-		(/** @type {any} */ attr) =>
-			attr?.type === 'JSXAttribute' &&
-			attr.name?.type === 'JSXIdentifier' &&
-			(attr.name.name === 'class' || attr.name.name === 'className'),
-	);
+	const attrs = (element.openingElement.attributes ??= []);
+	const existing = attrs.find(is_class_attribute);
 
 	if (!existing) {
-		const hash_literal = b.literal(hash);
-		/** @type {any} */ (hash_literal).raw = JSON.stringify(hash);
-		attrs.push(b.jsx_attribute(b.jsx_id(jsx_class_attr_name), hash_literal));
-		element.attributes = attrs;
+		attrs.push(
+			b.jsx_attribute(b.jsx_id(jsx_class_attr_name), b.literal(hash, JSON.stringify(hash))),
+		);
 		return;
 	}
 
 	const value = existing.value;
 	if (!value) {
-		existing.value = { type: 'Literal', value: hash, raw: JSON.stringify(hash) };
-		element.attributes = attrs;
+		existing.value = b.literal(hash, JSON.stringify(hash));
 		return;
 	}
 
-	if (value.type === 'Literal' && typeof value.value === 'string') {
-		const merged = `${value.value} ${hash}`;
-		value.value = merged;
-		value.raw = JSON.stringify(merged);
-		element.attributes = attrs;
+	if (merge_hash_into_literal(value, hash)) return;
+
+	const expression = value.type === 'JSXExpressionContainer' ? value.expression : value;
+	if (expression.type === 'JSXEmptyExpression') {
+		existing.value = b.literal(hash, JSON.stringify(hash));
 		return;
 	}
 
-	const expression = value.type === 'JSXExpressionContainer' ? value.expression : value;
 	existing.value = b.jsx_expression_container(
 		b.template([b.quasi('', false), b.quasi(` ${hash}`, true)], [expression]),
 	);
-	element.attributes = attrs;
 }

package/src/transform/segments.js

@@ -11,45 +11,15 @@
 	PostProcessingChanges,
 	LineOffsets,
 	CompileError,
+	CssElementInfo,
+	CssSourceRegion,
+	MappingToken,
+	ScriptSourceRegion,
+	TokenClass,
 } from '../../types/index';
 @import { CodeMapping as VolarCodeMapping } from '@volar/language-core';
  */
 
-/**
-@typedef {{
-	start: number,
-	end: number,
-	content: string,
-	id: string,
-}} CssSourceRegion;
-@typedef {{
-	start: number,
-	end: number,
-	content: string,
-	id: string,
-}} ScriptSourceRegion;
-@typedef {{
-	source: string | null | undefined;
-	generated: string;
-	loc: AST.SourceLocation;
-	metadata: PluginActionOverrides;
-	generatedLoc?: AST.SourceLocation;
-	end_loc?: AST.SourceLocation;
-	sourceLength?: number;
-	mappingData?: Partial<VolarCodeMapping['data']>;
-}} Token;
-@typedef {{
-	name: string,
-	line: number,
-	column: number,
-	offset: number,
-	length: number,
-	sourceOffset: number,
-}} TokenClass;
- */
-
-/** @typedef {Map<string, { scopedClasses: Map<string, { start: number; end: number; selector: any }>; hash: string } | undefined>} CssElementInfo */
-
 import { walk } from 'zimmerframe';
 import {
 	build_src_to_gen_map,
@@ -367,7 +337,7 @@ function extract_classes(node, src_to_gen_map, gen_line_offsets, src_line_offset
 /**
  * Create Volar mappings by walking the transformed AST
  * @param {AST.Node} ast - The transformed AST
- * @param {AST.Node} ast_from_source - The original AST from source
+ * @param {AST.Program} ast_from_source - The original AST from source
  * @param {string} source - Original source code
  * @param {string} generated_code - Generated code (returned in output, not used for searching)
  * @param {RawSourceMap} source_map - Esrap source map for accurate position lookup
@@ -401,7 +371,7 @@ export function convert_source_map_to_mappings(
 		errors.length > 0,
 	);
 
-	/** @type {Token[]} */
+	/** @type {MappingToken[]} */
 	const tokens = [];
 	/** @type {CssSourceRegion[]} */
 	const css_regions = [];
@@ -425,7 +395,7 @@ export function convert_source_map_to_mappings(
 	 * _$_server_$_.foo`), esrap records multiple generated positions for the
 	 * same source location. Keep token mappings in generated-order by consuming
 	 * the next matching generated token instead of always using the first one.
-	 * @param {Token} token
+	 * @param {MappingToken} token
 	 * @returns {{ line: number; column: number }}
 	 */
 	function get_generated_position_for_token(token) {
@@ -479,16 +449,22 @@ export function convert_source_map_to_mappings(
 	const mapped_comments = new Set();
 
 	/**
-	 * @param {any} node
+	 * @param {AST.Node | null | undefined} node
 	 * @returns {void}
 	 */
 	function add_preserved_comment_mappings(node) {
-		for (const key of ['leadingComments', 'trailingComments', 'innerComments', 'comments']) {
-			const comments = node?.[key];
+		if (!node) return;
+
+		for (const comments of [
+			node.leadingComments,
+			node.trailingComments,
+			node.innerComments,
+			node.comments,
+		]) {
 			if (!Array.isArray(comments)) continue;
 
 			for (const comment of comments) {
-				if (!comment?.loc || !should_preserve_comment(comment)) continue;
+				if (!has_location(comment) || !should_preserve_comment(comment)) continue;
 
 				const comment_key = `${comment.start}:${comment.end}`;
 				if (mapped_comments.has(comment_key)) continue;
@@ -522,7 +498,7 @@ export function convert_source_map_to_mappings(
 	}
 
 	/**
-	 * @param {any} generated_node
+	 * @param {AST.Identifier | ESTreeJSX.JSXIdentifier} generated_node
 	 * @returns {void}
 	 */
 	function add_extra_source_mapping_tokens(generated_node) {
@@ -558,7 +534,7 @@ export function convert_source_map_to_mappings(
 				// Only create mappings for identifiers with location info (from source)
 				// Synthesized identifiers (created by builders) don't have .loc and are skipped
 				if (node.name && node.loc) {
-					/** @type {Token} */
+					/** @type {MappingToken} */
 					let token;
 					// Check if this identifier was changed in metadata (e.g., #Map -> RippleMap)
 					// Or if it was capitalized during transformation
@@ -583,8 +559,8 @@ export function convert_source_map_to_mappings(
 					if (node.metadata?.source_length != null && LAZY_PARAM_IDENTIFIER_REGEX.test(node.name)) {
 						token.metadata.hover = create_lazy_param_hover_replacement(node.name);
 					}
-					if ('hover' in (node.metadata || {})) {
-						token.metadata.hover = /** @type {any} */ (node.metadata).hover;
+					if (node.metadata && 'hover' in node.metadata) {
+						token.metadata.hover = node.metadata.hover;
 					}
 					if (node.metadata?.disable_verification) {
 						token.mappingData = { ...mapping_data, verification: false };
@@ -624,7 +600,7 @@ export function convert_source_map_to_mappings(
 			} else if (node.type === 'JSXIdentifier') {
 				// JSXIdentifiers can also be capitalized (for dynamic components)
 				if (node.loc && node.name) {
-					/** @type {Token} */
+					/** @type {MappingToken} */
 					const token = {
 						source: node.metadata?.source_name ?? node.name,
 						generated: node.name,
@@ -998,8 +974,7 @@ export function convert_source_map_to_mappings(
 					// node-start-anchored arithmetic when tokens were not collected.
 					const keyword_bound =
 						node_fn.id?.start ?? node_fn.params?.[0]?.start ?? node_fn.body?.start ?? node_fn.end;
-					/** @type {Array<{ value: string, start: number, end: number, loc: AST.SourceLocation }>} */
-					const lexer_tokens = /** @type {any} */ (ast_from_source).tsrx_keyword_tokens ?? [];
+					const lexer_tokens = ast_from_source.tsrx_keyword_tokens ?? [];
 					/**
 					 * @param {'async' | 'function'} keyword
 					 * @param {number} from