@tsrx/core 0.1.47 → 0.1.49

package/package.json

@@ -3,7 +3,7 @@
   "description": "Core compiler infrastructure for TSRX syntax",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.1.47",
+  "version": "0.1.49",
   "type": "module",
   "repository": {
     "type": "git",

package/src/index.js

@@ -149,6 +149,7 @@ export { normalize_css_property_name as normalizeCssPropertyName } from './utils
 export { escape, escape_script as escapeScript } from './utils/escaping.js';
 
 // Transform
+export { with_deferred_imports as withDeferredImports } from './transform/imports.js';
 export {
 	add_jsx_setup_declaration as addJsxSetupDeclaration,
 	clone_switch_helper_invocation as cloneSwitchHelperInvocation,
@@ -203,7 +204,6 @@ export {
 	is_component_jsx_name,
 	is_jsx_child,
 	set_loc,
-	to_text_expression,
 } from './transform/jsx/ast-builders.js';
 export {
 	render_stylesheets as renderStylesheets,

package/src/plugin.js

@@ -273,6 +273,8 @@ export function TSRXPlugin(config) {
 			#controlFlowBlockAllowsNativeReturn = false;
 			#parsingJSXSwitchCaseScriptStatementDepth = 0;
 			#templateControlFlowBlockDepth = 0;
+			/** @type {AST.NodeWithLocation | null}	*/
+			#lastClauseKeywordSpan = null;
 			#templateControlFlowTryDepth = 0;
 			/** @type {Parse.Parser['context']} */
 			context = [b_stat];
@@ -1518,43 +1520,57 @@ export function TSRXPlugin(config) {
 					const previous_reading_header = this.#readingJSXControlFlowHeader;
 					this.#readingJSXControlFlowHeader = true;
 					try {
-						node = this.#finishJSXControlFlowExpression(
-							this.parseStatement(null),
-							'JSXForExpression',
-							start,
-							startLoc,
+						node = /** @type {AST.JSXForExpression} */ (
+							this.#finishJSXControlFlowExpression(
+								this.parseStatement(null),
+								'JSXForExpression',
+								start,
+								startLoc,
+							)
 						);
 					} finally {
 						this.#readingJSXControlFlowHeader = previous_reading_header;
 						this.#templateControlFlowBlockDepth--;
 					}
 					if (
-						/** @type {any} */ (node).statementType !== 'ForOfStatement' &&
-						/** @type {any} */ (node).statementType !== 'ForInStatement' &&
-						/** @type {any} */ (node).statementType !== 'ForStatement'
+						node.statementType !== 'ForOfStatement' &&
+						node.statementType !== 'ForInStatement' &&
+						node.statementType !== 'ForStatement'
 					) {
 						this.raise(start, 'Expected `for` after `@`.');
 					}
-					if (/** @type {any} */ (node).body?.type !== 'BlockStatement') {
-						this.raise(
-							/** @type {any} */ (node).body?.start ?? start,
-							'Expected `{` after JSX control-flow directive.',
-						);
+					if (node.body?.type !== 'BlockStatement') {
+						this.raise(node.body?.start ?? start, 'Expected `{` after JSX control-flow directive.');
 					}
 					if (this.#eatJSXForEmptyKeyword()) {
 						if (this.type !== tt.braceL) {
 							this.raise(this.start, 'Expected `{` after JSX control-flow directive.');
 						}
+						const emptyKeyword = this.#lastClauseKeywordSpan;
+						let empty;
 						this.#templateControlFlowBlockDepth++;
 						try {
-							/** @type {any} */ (node).empty = this.parseBlock();
+							empty = this.parseBlock();
 						} finally {
 							this.#templateControlFlowBlockDepth--;
 						}
+						node.empty = empty;
+						node.emptyKeyword = emptyKeyword;
+						// `@empty { … }` is part of the `@for` statement, but the node was
+						// already finished at the end of the for BODY (the clause is parsed
+						// after `#finishJSXControlFlowExpression`, unlike `@else`/`@catch`,
+						// which their own `parseStatement` consumes first). Extend it, or
+						// every consumer that slices by range — editor mappings, the
+						// playground's AST/position tracking, formatters, diagnostics —
+						// truncates the statement before its `@empty` clause.
+						node.end = empty.end;
+						/** @type {AST.NodeWithLocation} */ (node).loc.end =
+							/** @type {AST.NodeWithLocation} */ (empty).loc.end;
+						if (node.range) node.range[1] = /** @type {number} */ (empty.end);
 					} else if (this.#isUnprefixedDirectiveClauseContinuation('empty', ['{'])) {
 						this.raise(this.start, 'Expected `@empty` after `@for` block.');
 					} else {
-						/** @type {any} */ (node).empty = null;
+						node.empty = null;
 					}
 					return node;
 				}
@@ -1584,6 +1600,7 @@ export function TSRXPlugin(config) {
 			 * @param {string} keyword
 			 */
 			#eatJSXDirectiveClauseKeyword(keyword) {
+				this.#lastClauseKeywordSpan = null;
 				const keywordStart = skip_whitespace_from(this.input, this.start);
 				if (this.input.charCodeAt(keywordStart) !== CharCode.at) {
 					return false;
@@ -1596,6 +1613,19 @@ export function TSRXPlugin(config) {
 					return false;
 				}
 
+				// The clause keyword is the only authored spelling of `@empty`/`@else`/
+				// `@catch` and friends: the clause node itself starts at its `{`, so
+				// without this span nothing in the tree points at the keyword and
+				// tooling cannot resolve a cursor placed on it.
+				const keywordEnd = wordStart + keyword.length;
+				this.#lastClauseKeywordSpan = {
+					start: keywordStart,
+					end: keywordEnd,
+					loc: {
+						start: acorn.getLineInfo(this.input, keywordStart),
+						end: acorn.getLineInfo(this.input, keywordEnd),
+					},
+				};
 				this.pos = wordStart;
 				this.start = wordStart;
 				this.startLoc = acorn.getLineInfo(this.input, wordStart);
@@ -1714,6 +1744,7 @@ export function TSRXPlugin(config) {
 				node.alternate = null;
 
 				if (this.#eatJSXDirectiveClauseKeyword('else')) {
+					node.alternateKeyword = this.#lastClauseKeywordSpan;
 					node.alternate = this.#eatJSXDirectiveBareClauseKeyword('if')
 						? this.#parseTemplateIfStatement()
 						: /** @type {AST.Statement} */ (this.#parseTemplateControlFlowStatement());
@@ -1758,6 +1789,9 @@ export function TSRXPlugin(config) {
 							this.startNodeAt(clauseStart, clauseStartLoc)
 						);
 						current.consequent = [];
+						// `@case`/`@default` is the arm's only authored keyword; the node
+						// itself starts before the leading whitespace.
+						current.keyword = this.#lastClauseKeywordSpan;
 						const previous_reading_header = this.#readingJSXControlFlowHeader;
 						this.#readingJSXControlFlowHeader = true;
 						try {
@@ -3377,6 +3411,8 @@ export function TSRXPlugin(config) {
 				let node = /** @type {ESTreeJSX.JSXExpressionContainer} */ (this.startNode());
 				this.#jsxExpressionContainerDepth++;
 				let pushed_context_baseline = false;
+				/** @type {number} */
+				let context_baseline;
 				try {
 					this.next();
 
@@ -3384,7 +3420,8 @@ export function TSRXPlugin(config) {
 					// context is on the stack. A control-flow directive parsed inside this
 					// container must not strip anything below this floor (see
 					// `#filterTemplateScriptContexts`).
-					this.#expressionContainerContextBaselines.push(this.context.length);
+					context_baseline = this.context.length;
+					this.#expressionContainerContextBaselines.push(context_baseline);
 					this.#expressionContainerPathBaselines.push(this.#path.length);
 					pushed_context_baseline = true;
 
@@ -3401,6 +3438,18 @@ export function TSRXPlugin(config) {
 						this.next();
 					}
 					if (!consumeBraceAfterScope) {
+						// A control-flow directive expression restores the context stack from
+						// a snapshot taken inside this container
+						// (`#parseTemplateControlFlowBlock`), so the container's closing `}`
+						// — read while that stale snapshot was active — pops the wrong entry
+						// and leaves stale brace contexts above the enclosing tag's contexts.
+						// Once the `}` has been read the stack must be back at one below the
+						// baseline (the container's own brace context popped); drop anything
+						// above that so the token after `}` (e.g. the `>` finishing the
+						// enclosing opening tag) tokenizes in the right context.
+						if (this.type === tt.braceR && this.context.length >= context_baseline) {
+							this.context.length = context_baseline - 1;
+						}
 						this.expect(tt.braceR);
 					}
 				} finally {
@@ -3719,6 +3768,7 @@ export function TSRXPlugin(config) {
 						node.handler = null;
 
 						if (this.#eatJSXDirectiveClauseKeyword('pending')) {
+							node.pendingKeyword = this.#lastClauseKeywordSpan;
 							node.pending = this.#parseTemplateControlFlowReturnBlock();
 						} else if (this.#isUnprefixedDirectiveClauseContinuation('pending', ['{'])) {
 							this.raise(this.start, 'Expected `@pending` after `@try` block.');
@@ -3729,6 +3779,7 @@ export function TSRXPlugin(config) {
 						const clauseStart = this.start;
 						const clauseStartLoc = this.startLoc;
 						if (this.#eatJSXDirectiveClauseKeyword('catch')) {
+							node.handlerKeyword = this.#lastClauseKeywordSpan;
 							if (this.type === tt._catch || this.value === 'catch') {
 								this.next();
 							}
@@ -4688,6 +4739,67 @@ export function TSRXPlugin(config) {
 				this.parseTemplateBody(body);
 			}
 
+			/**
+			 * Parse the argument list of a deferred dynamic import,
+			 * `import.defer(specifier, options?)`, starting at the opening paren.
+			 *
+			 * This mirrors Acorn's ES2025 `import(...)` grammar (optional `options`
+			 * argument, optional trailing comma), which neither inherited parser
+			 * produces here: acorn-typescript's `parseDynamicImport` emits legacy
+			 * `arguments`, and Acorn's own only enables the `options` shape at
+			 * `ecmaVersion >= 16` while TSRX parses at 13.
+			 *
+			 * @param {AST.ImportExpression} node
+			 * @returns {AST.ImportExpression}
+			 */
+			parseDeferredDynamicImport(node) {
+				this.next(); // `(`
+				node.source = this.parseMaybeAssign();
+				node.options = null;
+
+				if (!this.eat(tt.parenR)) {
+					this.expect(tt.comma);
+					if (!this.afterTrailingComma(tt.parenR)) {
+						node.options = this.parseMaybeAssign();
+						if (!this.eat(tt.parenR)) {
+							this.expect(tt.comma);
+							if (!this.afterTrailingComma(tt.parenR)) this.unexpected();
+						}
+					}
+				}
+
+				return this.finishNode(node, 'ImportExpression');
+			}
+
+			/**
+			 * Recognize the deferred dynamic-import form
+			 * `import.defer(specifier, options?)` before Acorn parses `import.<name>`
+			 * as an `import.meta` member access. Ordinary `import()` and `import.meta`
+			 * fall through to Acorn unchanged, so the proposal never alters their
+			 * existing AST shape.
+			 * @type {Parse.Parser['parseExprImport']}
+			 */
+			parseExprImport(forNew) {
+				if (
+					!forNew &&
+					this.lookahead().type === tt.dot &&
+					this.isContextualWithState('defer', this.lookahead(2))
+				) {
+					const node = /** @type {AST.ImportExpression} */ (this.startNode());
+					if (this.containsEsc) {
+						this.raiseRecoverable(this.start, 'Escape sequence in keyword import');
+					}
+					this.next(); // `import`
+					this.next(); // `.`
+					this.next(); // `defer`
+					node.phase = 'defer';
+					if (this.type !== tt.parenL) this.unexpected();
+					return this.parseDeferredDynamicImport(node);
+				}
+
+				return super.parseExprImport(forNew);
+			}
+
 			/**
 			 * Parse proposal-style imports from an inline module declaration:
 			 * `import { foo } from server;`
@@ -4698,54 +4810,77 @@ export function TSRXPlugin(config) {
 			 * @type {Parse.Parser['parseImport']}
 			 */
 			parseImport(node) {
-				const tokenIsIdentifier = /** @type {any} */ (Parser.acornTypeScript).tokenIsIdentifier;
-				const parser = /** @type {any} */ (this);
-				const import_node = /** @type {any} */ (node);
-				let enterHead = parser.lookahead();
-				import_node.importKind = 'value';
-				parser.importOrExportOuterKind = 'value';
+				const tokenIsIdentifier = Parser.acornTypeScript.tokenIsIdentifier;
+				let enterHead = this.lookahead();
+				let deferred = false;
+				let defer_start = -1;
+				node.importKind = 'value';
+				this.importOrExportOuterKind = 'value';
 				if (tokenIsIdentifier(enterHead.type) || this.match(tt.star) || this.match(tt.braceL)) {
-					let ahead = parser.lookahead(2);
-					if (
+					let ahead = this.lookahead(2);
+					// `defer` and `type` are only phase/kind modifiers when the following
+					// token cannot continue a default import (`, `/`from`) or an
+					// import-equals declaration (`=`); otherwise they are ordinary bindings.
+					const head_modifies =
 						ahead.type !== tt.comma &&
-						!parser.isContextualWithState('from', ahead) &&
-						ahead.type !== tt.eq &&
-						parser.ts_eatContextualWithState('type', 1, enterHead)
-					) {
-						parser.importOrExportOuterKind = 'type';
-						import_node.importKind = 'type';
-						enterHead = parser.lookahead();
-						ahead = parser.lookahead(2);
+						!this.isContextualWithState('from', ahead) &&
+						ahead.type !== tt.eq;
+					// The namespace-only restriction is checked after parsing the clause,
+					// which also gives invalid named/default deferred imports a focused
+					// diagnostic.
+					if (head_modifies && this.isContextualWithState('defer', enterHead)) {
+						deferred = true;
+						defer_start = enterHead.start;
+						node.phase = 'defer';
+						this.ts_eatContextualWithState('defer', 1, enterHead);
+						enterHead = this.lookahead();
+						ahead = this.lookahead(2);
+					} else if (head_modifies && this.ts_eatContextualWithState('type', 1, enterHead)) {
+						this.importOrExportOuterKind = 'type';
+						node.importKind = 'type';
+						enterHead = this.lookahead();
+						ahead = this.lookahead(2);
 					}
 					if (tokenIsIdentifier(enterHead.type) && ahead.type === tt.eq) {
 						this.next();
-						const importNode = parser.tsParseImportEqualsDeclaration(node);
-						parser.importOrExportOuterKind = 'value';
+						const importNode = this.tsParseImportEqualsDeclaration(node);
+						this.importOrExportOuterKind = 'value';
 						return importNode;
 					}
 				}
 				this.next();
 				if (this.type === tt.string) {
-					import_node.specifiers = [];
-					import_node.source = this.parseExprAtom();
+					node.specifiers = [];
+					node.source = /** @type {AST.Literal} */ (this.parseExprAtom());
 				} else {
-					import_node.specifiers = this.parseImportSpecifiers();
+					node.specifiers = this.parseImportSpecifiers();
 					this.expectContextual('from');
 					if (this.type === tt.string) {
-						import_node.source = this.parseExprAtom();
+						node.source = /** @type {AST.Literal} */ (this.parseExprAtom());
 					} else if (tokenIsIdentifier(this.type)) {
 						const source = this.parseIdent(false);
 						source.metadata ??= { path: [] };
-						import_node.source = source;
+						node.source = source;
 					} else {
 						this.unexpected();
 					}
 				}
-				parser.parseMaybeImportAttributes(node);
+				if (
+					deferred &&
+					(node.specifiers.length !== 1 ||
+						node.specifiers[0].type !== 'ImportNamespaceSpecifier' ||
+						node.source.type !== 'Literal')
+				) {
+					this.raise(
+						defer_start,
+						'`import defer` only supports a namespace import from a string literal.',
+					);
+				}
+				this.parseMaybeImportAttributes(node);
 				this.semicolon();
 				this.finishNode(node, 'ImportDeclaration');
-				parser.importOrExportOuterKind = 'value';
-				return import_node;
+				this.importOrExportOuterKind = 'value';
+				return node;
 			}
 
 			/**

package/src/transform/await.js

@@ -1,6 +1,10 @@
+/** @import * as AST from 'estree' */
+
+import { child_nodes, is_ast_node } from '../utils/ast.js';
+
 /**
- * @param {any[]} body_nodes
- * @returns {any | null}
+ * @param {AST.Node[]} body_nodes
+ * @returns {AST.TSRXAwaitNode | null}
  */
 export function find_first_top_level_await_in_tsrx_function_body(body_nodes) {
 	for (const node of body_nodes) {
@@ -12,12 +16,12 @@ export function find_first_top_level_await_in_tsrx_function_body(body_nodes) {
 }
 
 /**
- * @param {any} node
+ * @param {AST.Node | AST.Node[] | null | undefined} node
  * @param {boolean} inside_nested_function
- * @returns {any | null}
+ * @returns {AST.TSRXAwaitNode | null}
  */
 export function find_first_top_level_await(node, inside_nested_function) {
-	if (!node || typeof node !== 'object') {
+	if (!node) {
 		return null;
 	}
 
@@ -45,17 +49,15 @@ export function find_first_top_level_await(node, inside_nested_function) {
 	if (
 		node.type === 'AwaitExpression' ||
 		(node.type === 'ForOfStatement' && node.await === true) ||
-		(node.type === 'JSXForExpression' && node.await === true)
+		(node.type === 'JSXForExpression' &&
+			node.statementType === 'ForOfStatement' &&
+			node.await === true)
 	) {
 		return node;
 	}
 
-	for (const key of Object.keys(node)) {
-		if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata') {
-			continue;
-		}
-
-		const found = find_first_top_level_await(node[key], false);
+	for (const child of child_nodes(node)) {
+		const found = find_first_top_level_await(child, false);
 		if (found) return found;
 	}
 

package/src/transform/imports.js

@@ -0,0 +1,96 @@
+/** @import * as AST from 'estree' */
+
+/**
+ * Add TSRX import-phase support to an esrap TS/TSX visitor set. esrap 2.3
+ * understands the rest of ImportDeclaration but does not print its Stage 3
+ * `phase` field yet, so delegating would silently turn a deferred import into
+ * an eager one.
+ *
+ * @template {Record<string, any>} T
+ * @param {T} visitors
+ * @returns {T}
+ */
+export function with_deferred_imports(visitors) {
+	const print_import_declaration = visitors.ImportDeclaration;
+	const print_import_expression = visitors.ImportExpression;
+	if (
+		typeof print_import_declaration !== 'function' ||
+		typeof print_import_expression !== 'function'
+	) {
+		throw new TypeError('Deferred imports require a complete esrap TS or TSX visitor set.');
+	}
+
+	return /** @type {T} */ ({
+		...visitors,
+		/**
+		 * @param {AST.ImportDeclaration} node
+		 * @param {import('esrap').Context} context
+		 */
+		ImportDeclaration(node, context) {
+			const import_node = /** @type {AST.ImportDeclaration & { phase?: 'defer' | null }} */ (node);
+			if (import_node.phase !== 'defer') {
+				print_import_declaration(node, context);
+				return;
+			}
+
+			const [specifier] = node.specifiers;
+			if (node.specifiers.length !== 1 || specifier.type !== 'ImportNamespaceSpecifier') {
+				throw new Error('`import defer` only supports a namespace import.');
+			}
+
+			if (node.loc) context.location(node.loc.start.line, node.loc.start.column);
+			context.write('import defer ');
+			if (specifier.loc) {
+				context.location(specifier.loc.start.line, specifier.loc.start.column);
+			}
+			context.write('* as ');
+			context.visit(specifier.local);
+			context.write(' from ');
+			context.visit(node.source);
+
+			const attributes =
+				/** @type {Array<{ key: AST.Identifier | AST.Literal, value: AST.Literal }>} */ (
+					/** @type {any} */ (node).attributes ?? /** @type {any} */ (node).assertions ?? []
+				);
+			if (attributes.length > 0) {
+				context.write(' with { ');
+				for (let index = 0; index < attributes.length; index++) {
+					context.visit(attributes[index].key);
+					context.write(': ');
+					context.visit(attributes[index].value);
+					if (index + 1 !== attributes.length) context.write(', ');
+				}
+				context.write(' }');
+			}
+
+			context.write(';');
+			if (node.loc) context.location(node.loc.end.line, node.loc.end.column);
+		},
+		/**
+		 * @param {AST.ImportExpression} node
+		 * @param {import('esrap').Context} context
+		 */
+		ImportExpression(node, context) {
+			const import_node = /** @type {AST.ImportExpression & { phase?: 'defer' | null }} */ (node);
+			if (import_node.phase !== 'defer') {
+				print_import_expression(node, context);
+				return;
+			}
+
+			if (node.loc) context.location(node.loc.start.line, node.loc.start.column);
+			context.write('import.defer(');
+			context.visit(node.source);
+
+			const options =
+				node.options ??
+				/** @type {AST.Expression | undefined} */ (/** @type {any} */ (node).arguments?.[0]);
+			if (options) {
+				context.write(', ');
+				context.visit(options);
+			}
+
+			context.write(')');
+			if (node.loc) context.location(node.loc.end.line, node.loc.end.column);
+		},
+	});
+}

package/src/transform/jsx/ast-builders.js

@@ -2,7 +2,7 @@
 /** @import * as ESTreeJSX from 'estree-jsx' */
 
 import * as b from '../../utils/builders.js';
-import { has_location } from '../../utils/ast.js';
+import { has_location, is_ast_node } from '../../utils/ast.js';
 
 /**
  * AST-building utilities shared across every JSX target (React, Preact,
@@ -16,7 +16,7 @@ import { has_location } from '../../utils/ast.js';
  *
  * @template {AST.Node} T
  * @param {T} node
- * @param {AST.Node | AST.NodeWithLocation | undefined} source_node
+ * @param {AST.Node | AST.NodeWithLocation | null | undefined} source_node
  * @returns {T}
  */
 export function set_loc(node, source_node) {
@@ -127,14 +127,6 @@ export function add_extra_source_mappings_from_matching_expression(generated, so
 	}
 }
 
-/**
- * @param {unknown} value
- * @returns {value is AST.Node}
- */
-function is_ast_node(value) {
-	return !!value && typeof value === 'object' && 'type' in value;
-}
-
 /**
  * @returns {AST.Literal}
  */
@@ -385,77 +377,6 @@ export function flatten_switch_consequent(consequent) {
 	return result;
 }
 
-/**
- * @param {AST.Expression | null | undefined} expression
- * @returns {boolean}
- */
-function is_static_string_expression(expression) {
-	if (!expression) {
-		return false;
-	}
-	if (expression.type === 'Literal') {
-		return typeof expression.value === 'string';
-	}
-	if (expression.type === 'TemplateLiteral') {
-		return expression.expressions.length === 0;
-	}
-	return false;
-}
-
-/**
- * Build `expr == null ? '' : expr + ''` — the text-coerce form used when a
- * Ripple `{expr}` child must render as a string in JSX (React/Preact drop
- * booleans; Solid's default child semantics don't either). Solid uses this
- * via `to_jsx_child`; React/Preact wrap it in a JSXExpressionContainer.
- *
- * When the expression is statically a non-null string at the AST level —
- * a string `Literal` (`"hello"`, `'hello'`) or a `TemplateLiteral` with no
- * interpolations (`` `hello` ``) — the coercion is provably a no-op and
- * the literal is emitted as-is. Identifiers and any other expression type still
- * get the ternary because the AST alone can't prove they're non-null strings.
- *
- * @param {AST.Expression} expression
- * @param {AST.Node | AST.NodeWithLocation} [source_node]
- * @returns {AST.Expression}
- */
-export function to_text_expression(expression, source_node = expression) {
-	if (is_static_string_expression(expression)) {
-		return set_loc(clone_ast_node(expression), source_node);
-	}
-	return set_loc(
-		/** @type {AST.Expression} */ ({
-			type: 'ConditionalExpression',
-			test: {
-				type: 'BinaryExpression',
-				operator: '==',
-				left: clone_ast_node(expression),
-				right: create_null_literal(),
-				metadata: { path: [] },
-			},
-			consequent: {
-				type: 'Literal',
-				value: '',
-				raw: "''",
-				metadata: { path: [] },
-			},
-			alternate: {
-				type: 'BinaryExpression',
-				operator: '+',
-				left: clone_ast_node(expression),
-				right: {
-					type: 'Literal',
-					value: '',
-					raw: "''",
-					metadata: { path: [] },
-				},
-				metadata: { path: [] },
-			},
-			metadata: { path: [] },
-		}),
-		source_node,
-	);
-}
-
 /**
  * Deep-clone an AST subtree.
  *