@tsrx/core 0.1.49 → 0.1.51

package/src/transform/style-ref.js

@@ -1,29 +1,46 @@
 /** @import * as AST from 'estree' */
+/** @import * as ESTreeJSX from 'estree-jsx' */
+/** @import { ClassMapCollectionState, StyleRefOptions, TopScopedClasses, Visitors } from '../../types/index' */
 
+import { walk } from 'zimmerframe';
 import * as b from '../utils/builders.js';
-import { is_function_or_class_node as is_function_or_class_boundary } from '../utils/ast.js';
+import {
+	child_nodes,
+	is_function_or_class_node as is_function_or_class_boundary,
+	is_style_element,
+} from '../utils/ast.js';
 import { clone_ast_node, clone_identifier } from './jsx/ast-builders.js';
 
 const regex_backslash_and_following_character = /\\(.)/g;
 
 /**
- * @typedef {{
- *   allowMutableRefTarget?: boolean;
- *   createTempIdentifier?: () => AST.Identifier;
- *   visitExpression?: (expression: AST.Expression) => AST.Expression;
- * }} StyleRefOptions
+ * @param {AST.Node} component
+ * @param {AST.CSS.StyleSheet} css
+ * @returns {AST.ObjectExpression}
  */
+export function create_style_class_map(component, css) {
+	return build_style_class_map(
+		component.metadata?.topScopedClasses ?? collect_style_class_map_entries(css),
+		css.hash,
+	);
+}
 
 /**
- * @param {any} component
- * @param {any} css
+ * @param {AST.CSS.StyleSheet} css
  * @returns {AST.ObjectExpression}
  */
-export function create_style_class_map(component, css) {
-	const hash = css?.hash ?? null;
-	const top_scoped_classes = /** @type {Map<string, any>} */ (
-		component?.metadata?.topScopedClasses ?? collect_style_class_map_entries(css)
-	);
+export function create_style_class_map_from_stylesheet(css) {
+	return build_style_class_map(collect_style_class_map_entries(css), css.hash);
+}
+
+/**
+ * `{ foo: 'hash foo', … }` for every class the style expression exposes.
+ *
+ * @param {TopScopedClasses} top_scoped_classes
+ * @param {string | null} hash
+ * @returns {AST.ObjectExpression}
+ */
+function build_style_class_map(top_scoped_classes, hash) {
 	const class_names = [...top_scoped_classes.keys()].sort();
 
 	return b.object(
@@ -34,42 +51,28 @@ export function create_style_class_map(component, css) {
 }
 
 /**
- * @param {any} css
- * @returns {AST.ObjectExpression}
- */
-export function create_style_class_map_from_stylesheet(css) {
-	return create_style_class_map(
-		{ metadata: { topScopedClasses: collect_style_class_map_entries(css) } },
-		css,
-	);
-}
-
-/**
- * @param {any} style_element
- * @returns {any | null}
+ * @param {AST.JSXStyleElement} style_element
+ * @returns {AST.CSS.StyleSheet | null}
  */
 export function get_style_element_stylesheet(style_element) {
-	return (
-		style_element?.children?.find?.((/** @type {any} */ child) => child.type === 'StyleSheet') ??
-		null
-	);
+	return style_element.children?.find((child) => child.type === 'StyleSheet') ?? null;
 }
 
 /**
- * @param {any} node
- * @param {any[]} [refs]
- * @returns {any[]}
+ * @param {AST.Node | AST.Node[]} node
+ * @param {ESTreeJSX.JSXAttribute[]} [refs]
+ * @returns {ESTreeJSX.JSXAttribute[]}
  */
 export function collect_style_ref_attributes(node, refs = []) {
-	if (!node || typeof node !== 'object') return refs;
-
 	if (Array.isArray(node)) {
 		for (const child of node) collect_style_ref_attributes(child, refs);
 		return refs;
 	}
 
+	if (!node || typeof node !== 'object') return refs;
+
 	if (is_style_element(node)) {
-		for (const attr of node.openingElement?.attributes || []) {
+		for (const attr of node.openingElement.attributes) {
 			if (is_ref_attribute(attr) && attr.value) {
 				refs.push(attr);
 			}
@@ -81,18 +84,15 @@ export function collect_style_ref_attributes(node, refs = []) {
 		return refs;
 	}
 
-	for (const key of Object.keys(node)) {
-		if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata' || key === 'css') {
-			continue;
-		}
-		collect_style_ref_attributes(node[key], refs);
+	for (const child of child_nodes(node, 'css')) {
+		collect_style_ref_attributes(child, refs);
 	}
 
 	return refs;
 }
 
 /**
- * @param {any[]} ref_attributes
+ * @param {ESTreeJSX.JSXAttribute[]} ref_attributes
  * @param {AST.Expression} style_map
  * @param {StyleRefOptions} [options]
  * @returns {AST.Statement[]}
@@ -203,7 +203,7 @@ function visit_expression(expression, options) {
 }
 
 /**
- * @param {any} attr
+ * @param {ESTreeJSX.JSXAttribute} attr
  * @returns {AST.Expression | null}
  */
 function get_ref_attribute_expression(attr) {
@@ -216,28 +216,21 @@ function get_ref_attribute_expression(attr) {
 }
 
 /**
- * @param {any} attr
- * @returns {boolean}
+ * @param {ESTreeJSX.JSXAttributeNode} attr
+ * @returns {attr is ESTreeJSX.JSXAttribute}
  */
 function is_ref_attribute(attr) {
 	return (
-		attr?.type === 'JSXAttribute' && attr.name?.type === 'JSXIdentifier' && attr.name.name === 'ref'
+		attr.type === 'JSXAttribute' && attr.name.type === 'JSXIdentifier' && attr.name.name === 'ref'
 	);
 }
 
 /**
- * @param {any} node
- * @returns {boolean}
- */
-function is_style_element(node) {
-	return !!node && node.type === 'JSXStyleElement';
-}
-
-/**
- * @param {any} css
- * @returns {Map<string, any>}
+ * @param {AST.CSS.StyleSheet} css
+ * @returns {TopScopedClasses}
  */
 function collect_style_class_map_entries(css) {
+	/** @type {TopScopedClasses} */
 	const entries = new Map();
 	collect_rule_class_map_entries(css, entries);
 	return entries;
@@ -249,7 +242,7 @@ function collect_style_class_map_entries(css) {
  * `create_style_class_map_from_stylesheet`, so marking and the generated map
  * always agree; calling both is harmless.
  *
- * @param {any} css
+ * @param {AST.CSS.StyleSheet} css
  * @returns {void}
  */
 export function mark_class_map_selectors(css) {
@@ -257,66 +250,59 @@ export function mark_class_map_selectors(css) {
 }
 
 /**
- * @param {any} node
- * @param {Map<string, any>} entries
- * @param {any} [enclosing_selector] the nearest prelude-level selector; classes
- *   found inside another selector (e.g. in `:global(...)` args) mark it as the
- *   selector that carries their class map entry
+ * The state threaded through the class-map collection walk: the nearest
+ * prelude-level selector. Classes found inside another selector (e.g. in
+ * `:global(...)` args) mark it as the selector that carries their class map
+ * entry.
+ *
+ * @param {AST.CSS.StyleSheet} css
+ * @param {TopScopedClasses} entries
  * @returns {void}
  */
-function collect_rule_class_map_entries(node, entries, enclosing_selector = null) {
-	if (!node || typeof node !== 'object') return;
-
-	if (Array.isArray(node)) {
-		for (const child of node) collect_rule_class_map_entries(child, entries, enclosing_selector);
-		return;
-	}
-
-	if (node.type === 'ComplexSelector') {
-		enclosing_selector ??= node;
-		const class_selector = get_standalone_class_selector(node);
-		if (class_selector) {
-			// Mark the prelude-level selector for every occurrence (not just the
-			// deduped first) so the render preparation of style expressions keeps
-			// exactly the selectors whose classes the map exposes.
-			(enclosing_selector.metadata ??= {}).class_map_selector = true;
-			const name = class_selector.name.replace(regex_backslash_and_following_character, '$1');
-			if (!entries.has(name)) {
-				entries.set(name, {
-					start: class_selector.start,
-					end: class_selector.end,
-					selector: class_selector,
-				});
-			}
-		}
-	}
-
-	if (is_function_or_class_boundary(node)) {
-		return;
-	}
-
-	for (const key of Object.keys(node)) {
-		if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata') {
-			continue;
-		}
-		collect_rule_class_map_entries(node[key], entries, enclosing_selector);
-	}
+function collect_rule_class_map_entries(css, entries) {
+	walk(
+		/** @type {AST.CSS.Node} */ (css),
+		/** @type {ClassMapCollectionState} */ ({ enclosing_selector: null }),
+		/** @type {Visitors<AST.CSS.Node, ClassMapCollectionState>} */ ({
+			ComplexSelector(node, context) {
+				const enclosing_selector = context.state.enclosing_selector ?? node;
+				const class_selector = get_standalone_class_selector(node);
+
+				if (class_selector) {
+					// Mark the prelude-level selector for every occurrence (not just the
+					// deduped first) so the render preparation of style expressions keeps
+					// exactly the selectors whose classes the map exposes.
+					enclosing_selector.metadata.class_map_selector = true;
+					const name = class_selector.name.replace(regex_backslash_and_following_character, '$1');
+					if (!entries.has(name)) {
+						entries.set(name, {
+							start: class_selector.start,
+							end: class_selector.end,
+							selector: class_selector,
+						});
+					}
+				}
+
+				context.next({ enclosing_selector });
+			},
+		}),
+	);
 }
 
 /**
- * @param {any} complex_selector
- * @returns {any | null}
+ * @param {AST.CSS.ComplexSelector} complex_selector
+ * @returns {AST.CSS.ClassSelector | null}
  */
 function get_standalone_class_selector(complex_selector) {
-	if (complex_selector?.children?.length !== 1) return null;
+	if (complex_selector.children.length !== 1) return null;
 	const relative_selector = complex_selector.children[0];
 	if (
-		relative_selector?.metadata?.is_global ||
-		relative_selector?.metadata?.is_global_like ||
-		relative_selector?.selectors?.length !== 1
+		relative_selector.metadata.is_global ||
+		relative_selector.metadata.is_global_like ||
+		relative_selector.selectors.length !== 1
 	) {
 		return null;
 	}
 	const selector = relative_selector.selectors[0];
-	return selector?.type === 'ClassSelector' ? selector : null;
+	return selector.type === 'ClassSelector' ? selector : null;
 }

package/src/transform/stylesheet.js

@@ -1,22 +1,6 @@
 /**
 @import * as AST from 'estree';
-@import { Visitors } from '../../types/index';
- */
-
-/**
-@typedef {{
-  code: MagicString;
-  hash: string;
-  minify: boolean;
-  selector: string;
-  keyframes: Record<string, {
-    indexes: number[];
-    local: boolean | undefined;
-  }>;
-  specificity: {
-    bumped: boolean
-  }
-}} State
+@import { StylesheetRenderState, Visitors } from '../../types/index';
  */
 
 import MagicString from 'magic-string';
@@ -39,7 +23,7 @@ function remove_css_prefix(name) {
 /**
  * Walk backwards until we find a non-whitespace character
  * @param {number} end
- * @param {State} state
+ * @param {StylesheetRenderState} state
  */
 function remove_preceding_whitespace(end, state) {
 	let start = end;
@@ -121,7 +105,7 @@ function has_global_in_middle(rule) {
 /**
  * @param {AST.CSS.PseudoClassSelector} selector
  * @param {AST.CSS.Combinator | null} combinator
- * @param {State} state
+ * @param {StylesheetRenderState} state
  */
 function remove_global_pseudo_class(selector, combinator, state) {
 	if (selector.args === null) {
@@ -166,7 +150,7 @@ function escape_comment_close(node, code) {
 }
 
 /**
- * @param {State} state
+ * @param {StylesheetRenderState} state
  * @param {number} index
  */
 function append_hash(state, index) {
@@ -207,7 +191,7 @@ function is_empty(rule, is_in_global_block) {
 	return true;
 }
 
-/** @type {Visitors<AST.CSS.Node, State>} */
+/** @type {Visitors<AST.CSS.Node, StylesheetRenderState>} */
 const visitors = {
 	_: (node, context) => {
 		context.state.code.addSourcemapLocation(node.start);

package/src/utils/ast.js

@@ -1,22 +1,6 @@
 /** @import * as AST from 'estree' */
 
-/**
- * Represents the path of a destructured assignment from either a declaration
- * or assignment expression. For example, given `const { foo: { bar: baz } } = quux`,
- * the path of `baz` is `foo.bar`
- * @typedef {{
- *   node: AST.Identifier | AST.MemberExpression;
- *   is_rest: boolean;
- *   has_default_value: boolean;
- *   expression: (object: AST.Identifier | AST.CallExpression) => AST.Expression;
- *   update_expression: (object: AST.Identifier) => AST.Expression;
- * }} DestructuredAssignment
- * - `node`: The node the destructuring path ends in. Can be a member expression only for assignment expressions
- * - `is_rest`: `true` if this is a `...rest` destructuring
- * - `has_default_value`: `true` if this has a fallback value like `const { foo = 'bar' } = ..`
- * - `expression`: The value of the current path. Will be a call expression if a rest element or default is involved — e.g. `const { foo: { bar: baz = 42 }, ...rest } = quux` — since we can't represent `baz` or `rest` purely as a path. Will be an await expression in case of an async default value (`const { foo = await bar } = ...`)
- * - `update_expression`: Like `expression` but without default values.
- */
+/** @import { DestructuredAssignment } from '../../types/index' */
 
 import * as b from './builders.js';
 
@@ -57,6 +41,19 @@ export function child_nodes(node, skip_key) {
 	return children;
 }
 
+/**
+ * The children a node carries, as nodes. Node types differ in whether they
+ * have a `children` slot at all (`JSXCodeBlock` does not) and in what it may
+ * hold, so this reads it uniformly instead of forcing every caller to narrow.
+ *
+ * @param {AST.Node} node
+ * @returns {AST.Node[]}
+ */
+export function node_children(node) {
+	const children = /** @type {AST.TraversableAstNode} */ (node).children;
+	return Array.isArray(children) ? children.filter(is_ast_node) : [];
+}
+
 /**
  * @template {object} T
  * @param {T | null | undefined} node
@@ -68,6 +65,14 @@ export function has_location(node) {
 	return location.loc != null && location.start !== undefined && location.end !== undefined;
 }
 
+/**
+ * @param {AST.Node | null | undefined} node
+ * @returns {node is AST.JSXStyleElement}
+ */
+export function is_style_element(node) {
+	return !!node && node.type === 'JSXStyleElement';
+}
+
 /**
  * @param {AST.Node} node
  * @returns {node is AST.Function}
@@ -90,7 +95,7 @@ export function is_function_or_class_node(node) {
 
 /**
  * @param {AST.Node} node
- * @returns {boolean}
+ * @returns {node is AST.Function}
  */
 export function is_function_or_component_node(node) {
 	return is_function_node(node);
@@ -199,8 +204,8 @@ export function get_component_from_path(path, includes_functions = false) {
 		const node = path[i];
 
 		if (is_function_node(node)) {
-			if (/** @type {any} */ (node).metadata?.native_tsrx_function) {
-				return /** @type {AST.Function} */ (node);
+			if (node.metadata?.native_tsrx_function) {
+				return node;
 			}
 			if (!includes_functions) {
 				return;

package/src/utils/builders.js

@@ -604,6 +604,47 @@ export function ts_type_literal(members, loc_info) {
 	return set_location(node, loc_info);
 }
 
+/**
+ * `<left>.<right>` — the qualified entity name of a type reference or of an
+ * import-equals module reference.
+ *
+ * @param {AST.EntityName} left
+ * @param {AST.Identifier} right
+ * @param {AST.NodeWithLocation} [loc_info]
+ * @returns {AST.TSQualifiedName}
+ */
+export function ts_qualified_name(left, right, loc_info) {
+	const node = /** @type {AST.TSQualifiedName} */ ({
+		type: 'TSQualifiedName',
+		left,
+		right,
+		metadata: { path: [] },
+	});
+
+	return set_location(node, loc_info);
+}
+
+/**
+ * `import <id> = <module_reference>;` — the alias form that keeps every meaning
+ * (value, type, namespace) of the referenced binding.
+ *
+ * @param {AST.Identifier} id
+ * @param {AST.EntityName | AST.TSExternalModuleReference} module_reference
+ * @param {AST.NodeWithLocation} [loc_info]
+ * @returns {AST.TSStatement<AST.TSImportEqualsDeclaration>}
+ */
+export function ts_import_equals(id, module_reference, loc_info) {
+	const node = /** @type {AST.TSStatement<AST.TSImportEqualsDeclaration>} */ ({
+		type: 'TSImportEqualsDeclaration',
+		id,
+		moduleReference: module_reference,
+		importKind: 'value',
+		metadata: { path: [] },
+	});
+
+	return set_location(node, loc_info);
+}
+
 /**
  * `@types/estree`'s `Statement` union has no TS declarations in it, so the
  * result is typed as both: a `type X = …` alias occupies a statement slot
@@ -612,10 +653,10 @@ export function ts_type_literal(members, loc_info) {
  * @param {AST.Identifier} id
  * @param {AST.Node} type_annotation
  * @param {AST.NodeWithLocation} [loc_info]
- * @returns {AST.TSTypeAliasDeclaration & AST.Statement}
+ * @returns {AST.TSStatement<AST.TSTypeAliasDeclaration>}
  */
 export function ts_type_alias(id, type_annotation, loc_info) {
-	const node = /** @type {AST.TSTypeAliasDeclaration & AST.Statement} */ ({
+	const node = /** @type {AST.TSStatement<AST.TSTypeAliasDeclaration>} */ ({
 		type: 'TSTypeAliasDeclaration',
 		id,
 		typeParameters: undefined,
@@ -685,6 +726,29 @@ export function prop(kind, key, value, computed = false, shorthand = false) {
 	};
 }
 
+/**
+ * A property of an object *pattern* — its value is a binding target, not an
+ * expression, so it cannot be built with {@link prop}.
+ *
+ * @param {AST.Expression} key
+ * @param {AST.Pattern} value
+ * @param {boolean} computed
+ * @param {boolean} shorthand
+ * @returns {AST.AssignmentProperty}
+ */
+export function assignment_prop(key, value, computed = false, shorthand = false) {
+	return {
+		type: 'Property',
+		kind: 'init',
+		key,
+		value,
+		method: false,
+		shorthand,
+		computed,
+		metadata: { path: [] },
+	};
+}
+
 /**
  * @param {AST.Expression | AST.PrivateIdentifier} key
  * @param {AST.Expression | null | undefined} value

package/src/vite/dep-scan.js

@@ -0,0 +1,135 @@
+/**
+ * Rolldown plugins that make `.tsrx` modules visible to Vite's dependency
+ * scanner.
+ *
+ * The scanner runs through Rolldown without the main plugin pipeline, so on its
+ * own it cannot read `.tsrx` modules. Any npm dependency imported only from
+ * `.tsrx` files is then discovered at request time rather than at startup,
+ * which forces a re-optimize and a full page reload. Registering one of these
+ * under `optimizeDeps.rolldownOptions.plugins` teaches the scan pass to compile
+ * `.tsrx` modules so their imports are crawled up front.
+ *
+ * Which factory to use depends on how the host plugin exposes `.tsrx` modules:
+ *
+ * - {@link createDepScanTransformPlugin} for plugins that transform `.tsrx`
+ *   ids directly. Those plugins must also list the extension in
+ *   `optimizeDeps.extensions`, because the scanner externalizes anything that
+ *   is not a known JS type before a plugin gets a chance to run.
+ * - {@link createDepScanLoadPlugin} for plugins that rewrite `.tsrx` ids to a
+ *   virtual `<path>.tsx` form. The scanner accepts those on extension alone, so
+ *   no `optimizeDeps.extensions` entry is needed, but it never calls Vite
+ *   `load()` hooks for virtual ids.
+ *
+ * Both swallow compile failures. Vite responds to a scan error by skipping
+ * pre-bundling for the whole project, so a single malformed file would
+ * otherwise cost every other dependency its pre-bundle. Handing back an empty
+ * module keeps the rest of the graph crawlable and leaves the error to the host
+ * plugin's own transform, which reports it at request time where it can be
+ * surfaced properly.
+ *
+ * @import { DepScanCompile, DepScanLoadPlugin, DepScanTransformPlugin } from '../../types/vite/dep-scan.js'
+ */
+
+import { readFile } from 'node:fs/promises';
+
+/**
+ * Render `imports` as a side-effect import prelude. Used for runtime modules
+ * that the host plugin's own output depends on but that the scan pass would
+ * otherwise miss — a JSX runtime, for instance, which the scanner's own JSX
+ * transform may resolve to a different specifier than the host plugin does.
+ *
+ * @param {string[] | undefined} imports
+ * @returns {string}
+ */
+function render_prelude(imports) {
+	if (imports === undefined || imports.length === 0) return '';
+
+	return imports.map((source) => `import ${JSON.stringify(source)};`).join('\n') + '\n';
+}
+
+/**
+ * Scan plugin for host plugins that transform `.tsrx` ids directly.
+ *
+ * @param {{
+ *   name: string,
+ *   filter: RegExp,
+ *   compile: DepScanCompile,
+ *   imports?: string[],
+ *   moduleType?: string,
+ * }} options
+ * @returns {DepScanTransformPlugin}
+ */
+export function createDepScanTransformPlugin({
+	name,
+	filter,
+	compile,
+	imports,
+	moduleType = 'tsx',
+}) {
+	const prelude = render_prelude(imports);
+
+	return {
+		name,
+		transform: {
+			filter: { id: filter },
+			async handler(/** @type {string} */ code, /** @type {string} */ id) {
+				try {
+					const { code: compiled } = await compile(code, id);
+					return { code: prelude + compiled, moduleType };
+				} catch {
+					return { code: '', moduleType };
+				}
+			},
+		},
+	};
+}
+
+/**
+ * Scan plugin for host plugins that rewrite `.tsrx` ids to a virtual
+ * `<path>.tsx` form, which the scanner resolves but never loads.
+ *
+ * @param {{
+ *   name: string,
+ *   isVirtual: (id: string) => boolean,
+ *   toRealPath: (id: string) => string,
+ *   compile: DepScanCompile,
+ *   imports?: string[],
+ *   moduleType?: string,
+ * }} options
+ * @returns {DepScanLoadPlugin}
+ */
+export function createDepScanLoadPlugin({
+	name,
+	isVirtual,
+	toRealPath,
+	compile,
+	imports,
+	moduleType = 'tsx',
+}) {
+	const prelude = render_prelude(imports);
+
+	return {
+		name,
+		async load(/** @type {string} */ id) {
+			// Both callbacks are written against plain paths, so drop any query
+			// suffix once here rather than leaving each caller to remember.
+			const path = id.split('?')[0];
+
+			if (!isVirtual(path)) return null;
+
+			const real_path = toRealPath(path);
+
+			try {
+				// The read is inside the try along with the compile: a virtual id
+				// pointing at a file that has since moved is just as survivable as
+				// one that fails to parse, and the host plugin's own `load()` will
+				// report either at request time.
+				const source = await readFile(real_path, 'utf-8');
+				const { code } = await compile(source, real_path);
+				return { code: prelude + code, moduleType };
+			} catch {
+				return { code: '', moduleType };
+			}
+		},
+	};
+}