@tsrx/core 0.1.45 → 0.1.47

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.47",
   "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,19 @@ 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,
+	has_location,
 	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';
 
@@ -159,7 +168,6 @@ export {
 	plan_switch_lift as planSwitchLift,
 	return_value_body_to_expression as returnValueBodyToExpression,
 	rewrite_loop_continues_to_bare_returns as rewriteLoopContinuesToBareReturns,
-	to_jsx_attribute as toJsxAttribute,
 	validate_at_most_one_ref_attribute as validateAtMostOneRefAttribute,
 	wrap_edge_whitespace as wrapEdgeWhitespace,
 } from './transform/jsx/index.js';
@@ -181,7 +189,7 @@ export {
 } from './transform/style-ref.js';
 export {
 	add_extra_source_mappings_from_matching_expression,
-	clone_expression_node,
+	clone_ast_node,
 	clone_identifier,
 	clone_jsx_name,
 	contains_component_jsx,
@@ -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/parse/index.js

@@ -8,6 +8,7 @@
 import * as acorn from 'acorn';
 import { tsPlugin } from '@sveltejs/acorn-typescript';
 import { walk } from 'zimmerframe';
+import { has_location } from '../utils/ast.js';
 
 /**
  * @typedef {(BaseParser: typeof acorn.Parser) => typeof acorn.Parser} AcornPlugin
@@ -607,8 +608,8 @@ export function get_comment_handlers(source, comments, index = 0) {
 						}
 
 						const ancestorElements = path
-							.filter((ancestor) => isNativeTemplateNode(ancestor) && ancestor.loc)
-							.map((ancestor) => /** @type {AST.NodeWithLocation} */ (ancestor))
+							.filter(has_location)
+							.filter(isNativeTemplateNode)
 							.sort((a, b) => a.loc.start.line - b.loc.start.line);
 
 						const targetAncestor = ancestorElements.find(

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--;
 				}