@tsrx/core 0.1.45 → 0.1.46

package/README.md

@@ -27,9 +27,10 @@ pnpm add @tsrx/core
 ## Usage
 
 ```js
-import { parseModule } from '@tsrx/core';
+import { analyzeTsrx, parseModule } from '@tsrx/core';
 
 const ast = parseModule(source, 'App.tsrx');
+const analysis = analyzeTsrx(ast, 'App.tsrx');
 ```
 
 The parser produces an ESTree-compatible AST, augmented with the TSRX node types
@@ -54,6 +55,10 @@ here and keeps package docs focused on the core parser API.
 
 - **`parseModule(source, filename, options?)`** — parse a TSRX module into an
   ESTree AST.
+- **`analyzeTsrx(ast, filename, options?)`** — run target-neutral semantic
+  validation before framework analysis or transformation. Pass `collect: true`,
+  `typeOnly: true`, or `to_ts: true` to collect non-fatal diagnostics for
+  editor/type-only output.
 - **Scope analysis** — `createScopes`, `Scope`, `ScopeRoot`, binding tracking
   (`import`, `prop`, `let`, `const`, `function`, `for_pattern`, …).
 - **AST utilities** — pattern walkers, identifier extraction, builders, location

package/package.json

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

package/src/analyze/index.js

@@ -0,0 +1,177 @@
+/**
+@import * as AST from 'estree';
+@import { TSRXAnalysisOptions, TSRXAnalysisResult, TSRXAnalysisState } from '../../types/index';
+ */
+
+import { walk } from 'zimmerframe';
+import {
+	is_code_block_function_body,
+	is_statement_position,
+	is_tsrx_render_output_node,
+} from '../utils/ast.js';
+import { validate_forgotten_statement_container } from './validation.js';
+
+/**
+ * Wrappers that preserve an expression's value and therefore do not turn a
+ * template into a used value on their own. Looking through them keeps strict
+ * builds and `preserveParens` type-only builds on the same diagnostic path.
+ *
+ * @param {AST.Node} parent
+ * @param {AST.Node} child
+ * @returns {boolean}
+ */
+function is_transparent_expression_wrapper(parent, child) {
+	return (
+		(parent.type === 'ParenthesizedExpression' ||
+			parent.type === 'TSAsExpression' ||
+			parent.type === 'TSSatisfiesExpression' ||
+			parent.type === 'TSNonNullExpression' ||
+			parent.type === 'TSInstantiationExpression' ||
+			parent.type === 'TSTypeAssertion' ||
+			parent.type === 'ChainExpression') &&
+		/** @type {{ expression?: AST.Node }} */ (parent).expression === child
+	);
+}
+
+/**
+ * A template is unused only when it is itself the statement being executed.
+ * Templates nested in assignments, returns, arguments, operands, or other
+ * value-producing expressions may be consumed later and are valid.
+ *
+ * @param {AST.Node} node
+ * @param {AST.Node[]} path
+ * @returns {boolean}
+ */
+function is_free_floating_template(node, path) {
+	let child = node;
+
+	for (let i = path.length - 1; i >= 0; i -= 1) {
+		const parent = path[i];
+
+		if (is_transparent_expression_wrapper(parent, child)) {
+			child = parent;
+			continue;
+		}
+
+		if (parent.type === 'ExpressionStatement' && parent.expression === child) {
+			return true;
+		}
+
+		if (is_statement_position(parent, child)) {
+			return true;
+		}
+
+		return false;
+	}
+
+	return false;
+}
+
+/**
+ * @param {AST.Function} node
+ * @param {{ next: (state?: TSRXAnalysisState) => unknown, state: TSRXAnalysisState }} context
+ */
+function visit_function(node, { next, state }) {
+	next({
+		...state,
+		function: node,
+		function_body_is_code_block: is_code_block_function_body(node.body, node),
+		inside_template_output: false,
+	});
+}
+
+/**
+ * @param {AST.Node} node
+ * @param {{ next: (state?: TSRXAnalysisState) => unknown, path: AST.Node[], state: TSRXAnalysisState }} context
+ */
+function visit_render_output(node, { next, path, state }) {
+	if (!is_tsrx_render_output_node(node)) {
+		next();
+		return;
+	}
+
+	if (
+		state.function &&
+		!(state.function_body_is_code_block && state.function.body === node) &&
+		!state.inside_template_output &&
+		is_free_floating_template(node, path)
+	) {
+		validate_forgotten_statement_container(
+			node,
+			state.filename,
+			state.collect ? state.errors : undefined,
+			state.comments,
+		);
+	}
+
+	// A JSXCodeBlock contains ordinary setup statements in `body` as well as
+	// the retained output in `render`. Reset the template context while walking
+	// both fields so free-floating output in setup is still diagnosed. The
+	// render node itself is retained by the code block, and establishes template
+	// context for its own descendants when this visitor reaches it.
+	next({ ...state, inside_template_output: node.type !== 'JSXCodeBlock' });
+}
+
+/**
+ * @param {AST.ClassDeclaration | AST.ClassExpression} _node
+ * @param {{ next: (state?: TSRXAnalysisState) => unknown, state: TSRXAnalysisState }} context
+ */
+function visit_class(_node, { next, state }) {
+	next({
+		...state,
+		function: null,
+		function_body_is_code_block: false,
+		inside_template_output: false,
+	});
+}
+
+const visitors = {
+	FunctionDeclaration: visit_function,
+	FunctionExpression: visit_function,
+	ArrowFunctionExpression: visit_function,
+
+	// A class body is not part of the surrounding function's execution context.
+	// Method/function nodes establish their own context when reached.
+	ClassDeclaration: visit_class,
+	ClassExpression: visit_class,
+
+	JSXElement: visit_render_output,
+	JSXFragment: visit_render_output,
+	JSXStyleElement: visit_render_output,
+	JSXCodeBlock: visit_render_output,
+	JSXIfExpression: visit_render_output,
+	JSXForExpression: visit_render_output,
+	JSXSwitchExpression: visit_render_output,
+	JSXTryExpression: visit_render_output,
+};
+
+/**
+ * Run target-neutral semantic validation over a parsed TSRX module. Parsing
+ * remains syntax-only; every target invokes this pass before target analysis or
+ * transformation. Type-only/Volar callers collect diagnostics and continue.
+ *
+ * @param {AST.Program} ast
+ * @param {string | null | undefined} filename
+ * @param {TSRXAnalysisOptions} [options]
+ * @returns {TSRXAnalysisResult}
+ */
+export function analyze_tsrx(ast, filename, options = {}) {
+	const errors = options.errors ?? [];
+	const comments = options.comments ?? [];
+	const collect = !!(options.collect || options.loose || options.typeOnly || options.to_ts);
+
+	/** @type {TSRXAnalysisState} */
+	const state = {
+		filename: filename ?? null,
+		collect,
+		errors,
+		comments,
+		function: null,
+		function_body_is_code_block: false,
+		inside_template_output: false,
+	};
+
+	walk(ast, state, visitors);
+
+	return { ast, errors, comments };
+}

package/src/analyze/validation.js

@@ -28,6 +28,8 @@ export const TSRX_WHILE_STATEMENT_ERROR =
 	'While loops are not supported in TSRX templates. Move the while loop into a function.';
 export const TSRX_DO_WHILE_STATEMENT_ERROR =
 	'Do...while loops are not supported in TSRX templates. Move the do...while loop into a function.';
+export const TSRX_FORGOTTEN_STATEMENT_CONTAINER_ERROR =
+	"This TSRX template output is unused. Return it, assign it to a value that is rendered, or make it part of the rendered output of a function '@{...}' body.";
 
 const invalid_nestings = {
 	// <p> cannot contain block-level elements
@@ -201,6 +203,23 @@ export function validate_tsrx_return_statement(node, filename, errors, comments)
 	);
 }
 
+/**
+ * @param {AST.Node} node
+ * @param {string | null | undefined} filename
+ * @param {CompileError[]} [errors]
+ * @param {AST.CommentWithLocation[]} [comments]
+ */
+export function validate_forgotten_statement_container(node, filename, errors, comments) {
+	error(
+		TSRX_FORGOTTEN_STATEMENT_CONTAINER_ERROR,
+		filename ?? null,
+		node,
+		errors,
+		comments,
+		DIAGNOSTIC_CODES.FORGOTTEN_STATEMENT_CONTAINER,
+	);
+}
+
 /**
  * @param {AST.ReturnStatement} node
  * @param {string | null | undefined} filename

package/src/index.js

@@ -87,10 +87,18 @@ export {
 	build_assignment_value as buildAssignmentValue,
 	is_class_node as isClassNode,
 	is_function_node as isFunctionNode,
+	is_function_or_class_node as isFunctionOrClassNode,
 	is_function_or_component_node as isFunctionOrComponentNode,
 	is_inside_component as isInsideComponent,
+	is_template_directive as isTemplateDirective,
+	is_tsrx_render_output_node as isTsrxRenderOutputNode,
+	is_code_block_function_body as isCodeBlockFunctionBody,
+	is_statement_position as isStatementPosition,
 } from './utils/ast.js';
 
+// Shared TSRX semantic analysis
+export { analyze_tsrx as analyzeTsrx } from './analyze/index.js';
+
 // Builders (namespace re-export — members mirror AST node kinds)
 export * as builders from './utils/builders.js';
 
@@ -244,6 +252,7 @@ export { analyze_css as analyzeCss } from './analyze/css-analyze.js';
 export { prune_css as pruneCss } from './analyze/prune.js';
 export {
 	TSRX_DO_WHILE_STATEMENT_ERROR,
+	TSRX_FORGOTTEN_STATEMENT_CONTAINER_ERROR,
 	TSRX_FOR_IN_STATEMENT_ERROR,
 	TSRX_FOR_STATEMENT_ERROR,
 	TSRX_IF_BREAK_ERROR,
@@ -264,6 +273,7 @@ export {
 	validate_tsrx_loop_return_statement as validateTsrxLoopReturnStatement,
 	validate_tsrx_return_statement as validateTsrxReturnStatement,
 	validate_tsrx_unsupported_loop_statement as validateTsrxUnsupportedLoopStatement,
+	validate_forgotten_statement_container as validateForgottenStatementContainer,
 	validate_nesting as validateNesting,
 	is_template_value_position as isTemplateValuePosition,
 } from './analyze/validation.js';

package/src/plugin.js

@@ -11,8 +11,7 @@ import { regex_newline_characters } from './utils/patterns.js';
 import { error } from './errors.js';
 import { DIAGNOSTIC_CODES } from './diagnostics.js';
 import { TSRX_RETURN_STATEMENT_ERROR } from './analyze/validation.js';
-const FORGOTTEN_STATEMENT_CONTAINER_ERROR =
-	"This function body contains TSRX template output, but it is a normal JavaScript block. Add '@' before the opening brace to use a TSRX statement container.";
+import { is_tsrx_render_output_node } from './utils/ast.js';
 
 const CharCode = Object.freeze({
 	tab: 9,
@@ -1162,104 +1161,6 @@ export function TSRXPlugin(config) {
 				return this.#isCodeBlockStart(index);
 			}
 
-			/**
-			 * @param {AST.Node | null | undefined} node
-			 */
-			#isRenderOutputNode(node) {
-				if (!node) return false;
-				switch (node.type) {
-					case 'JSXElement':
-					case 'JSXFragment':
-					case 'JSXStyleElement':
-					case 'JSXCodeBlock':
-					case 'JSXIfExpression':
-					case 'JSXForExpression':
-					case 'JSXSwitchExpression':
-					case 'JSXTryExpression':
-						return true;
-				}
-				return false;
-			}
-
-			/**
-			 * @param {AST.Node | null | undefined} node
-			 */
-			#isForgottenStatementContainerOutputNode(node) {
-				return this.#isRenderOutputNode(node) && node?.type !== 'JSXCodeBlock';
-			}
-
-			/**
-			 * @param {AST.Node | null | undefined} node
-			 */
-			#isIgnoredForgottenStatementContainerStatement(node) {
-				return !node || node.type === 'EmptyStatement';
-			}
-
-			/**
-			 * A normal function body that directly contains a bare JSX/control-flow node
-			 * almost always means the author wrote `{ ... <div /> }` but intended
-			 * `@{ ... <div /> }`. Only report when adding `@` would produce a valid
-			 * statement container: setup statements first, followed by one final render
-			 * output. Report only direct body children so ordinary nested callbacks/branches
-			 * are diagnosed by their own function body, not their parent.
-			 * @param {AST.Node} node
-			 */
-			#reportForgottenStatementContainerBody(node) {
-				if (!this.#collect) {
-					return;
-				}
-
-				const body = /** @type {{ body?: AST.Node }} */ (node).body;
-				if (body?.type !== 'BlockStatement') {
-					return;
-				}
-
-				const statements = /** @type {AST.BlockStatement} */ (body).body || [];
-				const has_return_type = Boolean(/** @type {{ returnType?: AST.Node }} */ (node).returnType);
-				if (!has_return_type) {
-					return;
-				}
-
-				let target = null;
-				let target_index = -1;
-				for (let index = 0; index < statements.length; index++) {
-					const statement = statements[index];
-					const output =
-						this.#isForgottenStatementContainerOutputNode(statement) ||
-						(statement.type === 'ExpressionStatement' &&
-							this.#isForgottenStatementContainerOutputNode(statement.expression))
-							? statement
-							: null;
-
-					if (!output) {
-						continue;
-					}
-
-					if (target_index !== -1) {
-						return;
-					}
-					target_index = index;
-					target = output;
-				}
-
-				if (!target) {
-					return;
-				}
-
-				for (const statement of statements.slice(target_index + 1)) {
-					if (!this.#isIgnoredForgottenStatementContainerStatement(statement)) {
-						return;
-					}
-				}
-
-				this.#report_recoverable_error_range(
-					/** @type {number} */ (target.start),
-					/** @type {number} */ (target.end),
-					FORGOTTEN_STATEMENT_CONTAINER_ERROR,
-					DIAGNOSTIC_CODES.FORGOTTEN_STATEMENT_CONTAINER,
-				);
-			}
-
 			/**
 			 * Inside a code block (`@{ … }` or a directive's `{ }`), decides whether the
 			 * next thing is the single bare render node (`<tag …>`, `<>…</>`, or an
@@ -1500,7 +1401,7 @@ export function TSRXPlugin(config) {
 				}
 
 				const last = flat[flat.length - 1];
-				if (this.#isRenderOutputNode(last)) {
+				if (is_tsrx_render_output_node(last)) {
 					node.render = last;
 					node.body = /** @type {AST.Statement[]} */ (flat.slice(0, -1));
 				} else {
@@ -3455,9 +3356,7 @@ export function TSRXPlugin(config) {
 						this.exitScope();
 						return node;
 					}
-					const parsed = super.parseFunctionBody(node, isArrowFunction, isMethod, forInit, ...args);
-					this.#reportForgottenStatementContainerBody(parsed);
-					return parsed;
+					return super.parseFunctionBody(node, isArrowFunction, isMethod, forInit, ...args);
 				} finally {
 					this.#functionBodyDepth--;
 				}

package/src/transform/jsx/index.js

@@ -61,6 +61,10 @@ import {
 } from '../jsx-interleave.js';
 import { is_hoist_safe_jsx_node } from '../jsx-hoist.js';
 import { lower_server_module_for_types } from './server-module.js';
+import {
+	is_function_or_class_node as is_function_or_class_boundary,
+	is_template_directive as is_jsx_control_flow_expression,
+} from '../../utils/ast.js';
 
 const TEMPLATE_FRAGMENT_ERROR =
 	'JSX fragment syntax is not needed in TSRX templates. TSRX renders in immediate mode, so everything is already a fragment. Use `<>...</>` only in expression position.';
@@ -114,20 +118,6 @@ function report_jsx_fragment_in_tsrx_error(node, transform_context) {
  * @typedef {{ source_name: string, read: () => any }} LazyBinding
  */
 
-/**
- * @param {any} node
- * @returns {boolean}
- */
-function is_function_or_class_boundary(node) {
-	return (
-		node?.type === 'FunctionDeclaration' ||
-		node?.type === 'FunctionExpression' ||
-		node?.type === 'ArrowFunctionExpression' ||
-		node?.type === 'ClassDeclaration' ||
-		node?.type === 'ClassExpression'
-	);
-}
-
 /**
  * @param {any} node
  * @param {boolean} [inside_function]
@@ -264,22 +254,6 @@ function expand_child_code_blocks(node, seen = new Set()) {
 	return out;
 }
 
-/**
- * A `@`-prefixed JSX control-flow expression (`@if`/`@for`/`@switch`/`@try`).
- * These are the only control-flow nodes that can appear in expression position;
- * the plain statement forms (`IfStatement`, `SwitchStatement`, …) never do.
- * @param {any} node
- * @returns {boolean}
- */
-function is_jsx_control_flow_expression(node) {
-	return (
-		node?.type === 'JSXIfExpression' ||
-		node?.type === 'JSXForExpression' ||
-		node?.type === 'JSXSwitchExpression' ||
-		node?.type === 'JSXTryExpression'
-	);
-}
-
 /**
  * Wrap a render-output node in a native TSRX fragment so it flows through the
  * same single-child render path as a `<> … </>` output. This is a compiler

package/src/transform/style-ref.js

@@ -1,6 +1,7 @@
 /** @import * as AST from 'estree' */
 
 import * as b from '../utils/builders.js';
+import { is_function_or_class_node as is_function_or_class_boundary } from '../utils/ast.js';
 import { clone_expression_node, clone_identifier } from './jsx/ast-builders.js';
 
 const regex_backslash_and_following_character = /\\(.)/g;
@@ -236,20 +237,6 @@ function is_style_element(node) {
 	return !!node && node.type === 'JSXStyleElement';
 }
 
-/**
- * @param {any} node
- * @returns {boolean}
- */
-function is_function_or_class_boundary(node) {
-	return (
-		node?.type === 'FunctionDeclaration' ||
-		node?.type === 'FunctionExpression' ||
-		node?.type === 'ArrowFunctionExpression' ||
-		node?.type === 'ClassDeclaration' ||
-		node?.type === 'ClassExpression'
-	);
-}
-
 /**
  * @param {any} css
  * @returns {Map<string, any>}

package/src/utils/ast.js

@@ -22,7 +22,7 @@ import * as b from './builders.js';
 
 /**
  * @param {AST.Node} node
- * @returns {boolean}
+ * @returns {node is AST.Function}
  */
 export function is_function_node(node) {
 	return (
@@ -32,6 +32,14 @@ export function is_function_node(node) {
 	);
 }
 
+/**
+ * @param {AST.Node | null | undefined} node
+ * @returns {node is AST.Function | AST.ClassDeclaration | AST.ClassExpression}
+ */
+export function is_function_or_class_node(node) {
+	return !!node && (is_function_node(node) || is_class_node(node));
+}
+
 /**
  * @param {AST.Node} node
  * @returns {boolean}
@@ -48,6 +56,87 @@ export function is_class_node(node) {
 	return node.type === 'ClassExpression' || node.type === 'ClassDeclaration';
 }
 
+/**
+ * A parsed `@if`/`@for`/`@switch`/`@try` control-flow directive.
+ *
+ * @param {AST.Node | null | undefined} node
+ * @returns {node is AST.JSXTemplateDirective}
+ */
+export function is_template_directive(node) {
+	return (
+		node?.type === 'JSXIfExpression' ||
+		node?.type === 'JSXForExpression' ||
+		node?.type === 'JSXSwitchExpression' ||
+		node?.type === 'JSXTryExpression'
+	);
+}
+
+/**
+ * Any source AST node that can be the rendered output of a TSRX template or
+ * statement container.
+ *
+ * @param {AST.Node | null | undefined} node
+ * @returns {node is AST.TSRXRenderOutput}
+ */
+export function is_tsrx_render_output_node(node) {
+	return !!(
+		node &&
+		(node.type === 'JSXElement' ||
+			node.type === 'JSXFragment' ||
+			node.type === 'JSXStyleElement' ||
+			node.type === 'JSXCodeBlock' ||
+			is_template_directive(node))
+	);
+}
+
+/**
+ * @param {AST.Node | null | undefined} node
+ * @param {AST.Node | null | undefined} parent
+ * @returns {node is AST.JSXCodeBlock}
+ */
+export function is_code_block_function_body(node, parent) {
+	return !!(
+		node &&
+		node.type === 'JSXCodeBlock' &&
+		parent &&
+		is_function_node(parent) &&
+		parent.body === node
+	);
+}
+
+/**
+ * Returns whether `child` directly occupies a statement slot of `parent`.
+ * Parser-native TSRX output nodes can appear in these slots without an
+ * `ExpressionStatement` wrapper, notably as braceless control-flow bodies.
+ *
+ * @param {AST.Node} parent
+ * @param {AST.Node} child
+ * @returns {boolean}
+ */
+export function is_statement_position(parent, child) {
+	switch (parent.type) {
+		case 'Program':
+		case 'BlockStatement':
+			return parent.body.includes(/** @type {AST.Statement} */ (child));
+		case 'SwitchCase':
+			return parent.consequent.includes(/** @type {AST.Statement} */ (child));
+		case 'JSXCodeBlock':
+			return parent.body.includes(/** @type {AST.Statement} */ (child));
+		case 'IfStatement':
+			return parent.consequent === child || parent.alternate === child;
+		case 'ForStatement':
+		case 'ForInStatement':
+		case 'ForOfStatement':
+		case 'WhileStatement':
+		case 'DoWhileStatement':
+		case 'LabeledStatement':
+		case 'WithStatement':
+			return parent.body === child;
+		default:
+			return false;
+	}
+}
+
 /**
  * Returns the closest native TSRX function in an ancestry path. By default,
  * function and class boundaries stop the search so callers only match direct

package/types/index.d.ts

@@ -445,6 +445,14 @@ declare module 'estree' {
 		| JSXSwitchExpression
 		| JSXTryExpression;
 
+	/** Any node that can be the rendered output of a TSRX template or statement container. */
+	type TSRXRenderOutput =
+		| ESTreeJSX.JSXElement
+		| ESTreeJSX.JSXFragment
+		| JSXStyleElement
+		| JSXCodeBlock
+		| JSXTemplateDirective;
+
 	interface ParenthesizedExpression extends AST.BaseNode {
 		type: 'ParenthesizedExpression';
 		expression: AST.Expression;
@@ -1269,6 +1277,30 @@ export interface AnalyzeOptions extends ParseOptions, Pick<CompileOptions, 'mode
 	to_ts?: boolean;
 }
 
+/** Options for the target-neutral TSRX semantic analysis pass. */
+export interface TSRXAnalysisOptions extends ParseOptions {
+	typeOnly?: boolean;
+	to_ts?: boolean;
+}
+
+/** Traversal state used by the target-neutral TSRX semantic analysis pass. */
+export interface TSRXAnalysisState {
+	filename: string | null;
+	collect: boolean;
+	errors: CompileError[];
+	comments: AST.CommentWithLocation[];
+	function: AST.Function | null;
+	function_body_is_code_block: boolean;
+	inside_template_output: boolean;
+}
+
+/** Result of target-neutral TSRX semantic analysis. */
+export interface TSRXAnalysisResult {
+	ast: AST.Program;
+	errors: CompileError[];
+	comments: AST.CommentWithLocation[];
+}
+
 /**
  * Result of parsing operation
  */