@tsrx/core 0.0.1

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tsrx/core",
+  "description": "Core compiler infrastructure for tsrx-based frameworks",
+  "license": "MIT",
+  "author": "Dominic Gannaway",
+  "version": "0.0.1",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ripple-TS/ripple.git",
+    "directory": "packages/tsrx"
+  },
+  "exports": {
+    ".": {
+      "default": "./src/index.js"
+    },
+    "./types": {
+      "types": "./types/index.d.ts"
+    },
+    "./types/estree": {
+      "types": "./types/estree.d.ts"
+    },
+    "./types/estree-jsx": {
+      "types": "./types/estree-jsx.d.ts"
+    },
+    "./types/acorn": {
+      "types": "./types/acorn.d.ts"
+    }
+  },
+  "dependencies": {
+    "@jridgewell/sourcemap-codec": "catalog:default",
+    "@sveltejs/acorn-typescript": "catalog:default",
+    "acorn": "catalog:default",
+    "esrap": "catalog:default",
+    "is-reference": "catalog:default",
+    "magic-string": "catalog:default",
+    "zimmerframe": "catalog:default",
+    "@types/estree": "catalog:default",
+    "@types/estree-jsx": "catalog:default"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:default",
+    "@typescript-eslint/types": "catalog:default",
+    "typescript": "catalog:default",
+    "@volar/language-core": "catalog:default",
+    "vscode-languageserver-types": "catalog:default"
+  },
+  "files": [
+    "src",
+    "types"
+  ]
+}

package/src/analyze/css-analyze.js

@@ -0,0 +1,160 @@
+/** @import * as AST from 'estree' */
+
+import { walk } from 'zimmerframe';
+
+/**
+ * True if is `:global` without arguments
+ * @param {AST.CSS.SimpleSelector} simple_selector
+ */
+function is_global_block_selector(simple_selector) {
+	return (
+		simple_selector.type === 'PseudoClassSelector' &&
+		simple_selector.name === 'global' &&
+		simple_selector.args === null
+	);
+}
+
+/**
+ * True if is `:global(...)` or `:global` and no pseudo class that is scoped.
+ * @param {AST.CSS.RelativeSelector} relative_selector
+ */
+function is_global(relative_selector) {
+	const first = relative_selector.selectors[0];
+
+	return (
+		first?.type === 'PseudoClassSelector' &&
+		first.name === 'global' &&
+		(first.args === null ||
+			// Only these two selector types keep the whole selector global, because e.g.
+			// :global(button).x means that the selector is still scoped because of the .x
+			relative_selector.selectors.every(
+				(selector) =>
+					selector.type === 'PseudoClassSelector' || selector.type === 'PseudoElementSelector',
+			))
+	);
+}
+
+/**
+ * Analyze CSS and set metadata for global selectors
+ * @param {AST.CSS.Node} css - The CSS AST
+ */
+export function analyze_css(css) {
+	walk(css, /** @type {{ rule: AST.CSS.Rule | null }} */ ({ rule: null }), {
+		Rule(node, context) {
+			node.metadata.parent_rule = context.state.rule;
+
+			// Check for :global blocks
+			// A global block is when the selector starts with :global and has no local selectors before it
+			for (const complex_selector of node.prelude.children) {
+				let is_global_block = false;
+
+				for (
+					let selector_idx = 0;
+					selector_idx < complex_selector.children.length;
+					selector_idx++
+				) {
+					const child = complex_selector.children[selector_idx];
+					const idx = child.selectors.findIndex(is_global_block_selector);
+
+					if (is_global_block) {
+						// All selectors after :global are unscoped
+						child.metadata.is_global_like = true;
+					}
+
+					// Only set is_global_block if this is the FIRST RelativeSelector and it starts with :global
+					if (selector_idx === 0 && idx === 0) {
+						// `child` starts with `:global` and is the first selector in the chain
+						is_global_block = true;
+						node.metadata.is_global_block = is_global_block;
+					} else if (idx === 0) {
+						// :global appears later in the selector chain (e.g., `div :global p`)
+						// Set is_global_block for marking subsequent selectors as global-like
+						is_global_block = true;
+					} else if (idx !== -1) {
+						// `:global` is not at the start - this is invalid but we'll let it through for now
+						// The transform phase will handle removal
+					}
+				}
+			}
+
+			// Pass the current rule as state to nested nodes
+			const state = { rule: node };
+			context.visit(node.prelude, state);
+			context.visit(node.block, state);
+		},
+
+		ComplexSelector(node, context) {
+			// Set the rule metadata before analyzing children
+			node.metadata.rule = context.state.rule;
+
+			context.next(); // analyze relevant selectors first
+
+			{
+				const global = node.children.find(is_global);
+
+				if (global) {
+					const is_nested = context.path.at(-2)?.type === 'PseudoClassSelector';
+					if (
+						is_nested &&
+						!(/** @type {AST.CSS.PseudoClassSelector} */ (global.selectors[0]).args)
+					) {
+						throw new Error(`A :global selector cannot be inside a pseudoclass.`);
+					}
+
+					const idx = node.children.indexOf(global);
+					const first = /** @type {AST.CSS.PseudoClassSelector} */ (global.selectors[0]);
+					if (first.args !== null && idx !== 0 && idx !== node.children.length - 1) {
+						// ensure `:global(...)` is not used in the middle of a selector (but multiple `global(...)` in sequence are ok)
+						for (let i = idx + 1; i < node.children.length; i++) {
+							if (!is_global(node.children[i])) {
+								throw new Error(
+									`:global(...) can be at the start or end of a selector sequence, but not in the middle.`,
+								);
+							}
+						}
+					}
+				}
+			}
+
+			// Set is_global metadata
+			node.metadata.is_global = node.children.every(
+				({ metadata }) => metadata.is_global || metadata.is_global_like,
+			);
+
+			node.metadata.used ||= node.metadata.is_global;
+		},
+
+		PseudoClassSelector(node, context) {
+			// Walk into :is(), :where(), :has(), and :not() to initialize metadata for nested selectors
+			if (
+				(node.name === 'is' ||
+					node.name === 'where' ||
+					node.name === 'has' ||
+					node.name === 'not') &&
+				node.args
+			) {
+				context.next();
+			}
+		},
+		RelativeSelector(node, context) {
+			// Check if this selector is a :global selector
+			node.metadata.is_global = node.selectors.length >= 1 && is_global(node);
+
+			// Check for :root and other global-like selectors
+			if (
+				node.selectors.length >= 1 &&
+				node.selectors.every(
+					(selector) =>
+						selector.type === 'PseudoClassSelector' || selector.type === 'PseudoElementSelector',
+				)
+			) {
+				const first = node.selectors[0];
+				node.metadata.is_global_like ||=
+					(first.type === 'PseudoClassSelector' && first.name === 'host') ||
+					(first.type === 'PseudoClassSelector' && first.name === 'root');
+			}
+
+			context.next();
+		},
+	});
+}

package/src/analyze/validation.js

@@ -0,0 +1,167 @@
+/**
+@import * as AST from 'estree';
+@import { AnalysisContext, CompileError } from '../../types/index';
+ */
+
+import { error } from '../errors.js';
+
+const invalid_nestings = {
+	// <p> cannot contain block-level elements
+	p: new Set([
+		'address',
+		'article',
+		'aside',
+		'blockquote',
+		'details',
+		'div',
+		'dl',
+		'fieldset',
+		'figcaption',
+		'figure',
+		'footer',
+		'form',
+		'h1',
+		'h2',
+		'h3',
+		'h4',
+		'h5',
+		'h6',
+		'header',
+		'hgroup',
+		'hr',
+		'main',
+		'menu',
+		'nav',
+		'ol',
+		'p',
+		'pre',
+		'section',
+		'table',
+		'ul',
+	]),
+	// <span> cannot contain block-level elements
+	span: new Set([
+		'address',
+		'article',
+		'aside',
+		'blockquote',
+		'details',
+		'div',
+		'dl',
+		'fieldset',
+		'figcaption',
+		'figure',
+		'footer',
+		'form',
+		'h1',
+		'h2',
+		'h3',
+		'h4',
+		'h5',
+		'h6',
+		'header',
+		'hgroup',
+		'hr',
+		'main',
+		'menu',
+		'nav',
+		'ol',
+		'p',
+		'pre',
+		'section',
+		'table',
+		'ul',
+	]),
+	// Interactive elements cannot be nested
+	a: new Set(['a', 'button']),
+	button: new Set(['a', 'button']),
+	// Form elements
+	label: new Set(['label']),
+	form: new Set(['form']),
+	// Headings cannot be nested within each other
+	h1: new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']),
+	h2: new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']),
+	h3: new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']),
+	h4: new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']),
+	h5: new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']),
+	h6: new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']),
+	// Table structure
+	table: new Set(['table', 'tr', 'td', 'th']), // Can only contain caption, colgroup, thead, tbody, tfoot
+	thead: new Set(['caption', 'colgroup', 'thead', 'tbody', 'tfoot', 'td', 'th']), // Can only contain tr
+	tbody: new Set(['caption', 'colgroup', 'thead', 'tbody', 'tfoot', 'td', 'th']), // Can only contain tr
+	tfoot: new Set(['caption', 'colgroup', 'thead', 'tbody', 'tfoot', 'td', 'th']), // Can only contain tr
+	tr: new Set(['caption', 'colgroup', 'thead', 'tbody', 'tfoot', 'tr']), // Can only contain td and th
+	td: new Set(['td', 'th']), // Cannot nest td/th elements
+	th: new Set(['td', 'th']), // Cannot nest td/th elements
+	// Media elements
+	picture: new Set(['picture']),
+	// Main landmark - only one per document, cannot be nested
+	main: new Set(['main']),
+	// Other semantic restrictions
+	figcaption: new Set(['figcaption']),
+	dt: new Set([
+		'header',
+		'footer',
+		'article',
+		'aside',
+		'nav',
+		'section',
+		'h1',
+		'h2',
+		'h3',
+		'h4',
+		'h5',
+		'h6',
+	]),
+	// No interactive content inside summary
+	summary: new Set(['summary']),
+};
+
+/**
+ * @param {AST.Element} element
+ * @returns {string | null}
+ */
+function get_element_tag(element) {
+	return element.id.type === 'Identifier' ? element.id.name : null;
+}
+
+/**
+ * @param {AST.Element} element
+ * @param {AnalysisContext} context
+ * @param {CompileError[]} [errors]
+ */
+export function validate_nesting(element, context, errors) {
+	const tag = get_element_tag(element);
+
+	if (tag === null) {
+		return;
+	}
+
+	for (let i = context.path.length - 1; i >= 0; i--) {
+		const parent = context.path[i];
+		if (parent.type === 'Element') {
+			const parent_tag = get_element_tag(parent);
+			if (parent_tag === null) {
+				continue;
+			}
+
+			if (parent_tag in invalid_nestings) {
+				const validation_set =
+					invalid_nestings[/** @type {keyof typeof invalid_nestings} */ (parent_tag)];
+				if (validation_set.has(tag)) {
+					error(
+						`Invalid HTML nesting: <${tag}> cannot be a descendant of <${parent_tag}>.`,
+						context.state.analysis.module.filename,
+						element,
+						errors,
+						context.state.analysis.comments,
+					);
+				} else {
+					// if my parent has a set of invalid children
+					// and i'm not in it, then i'm valid
+					return;
+				}
+			}
+		}
+	}
+}

package/src/comment-utils.js

@@ -0,0 +1,91 @@
+/**
+ * @import * as AST from 'estree'
+ */
+
+/**
+ * Check if a comment is a TypeScript pragma (line comment)
+ * @param {AST.CommentWithLocation} comment
+ * @returns {boolean}
+ */
+export function is_ts_pragma(comment) {
+	if (comment.type !== 'Line') return false;
+
+	const pragmas = ['@ts-ignore', '@ts-expect-error', '@ts-nocheck', '@ts-check'];
+	return pragmas.some((pragma) => comment.value.trimStart().startsWith(pragma));
+}
+
+/**
+ * Check if a comment is a triple-slash directive
+ * /// <reference path="..." />
+ * @param {AST.CommentWithLocation} comment
+ * @returns {boolean}
+ */
+export function is_triple_slash_directive(comment) {
+	if (comment.type !== 'Line') return false;
+
+	// Triple slash directives start with / after the // is stripped
+	// So the value should start with / followed by <reference, <amd-module, or <amd-dependency
+	const value = comment.value.trim();
+	return /^\/\s*<(reference|amd-module|amd-dependency)/.test(value);
+}
+
+/**
+ * Check if a comment is a JSDoc comment with TypeScript annotations
+ * Examples: block comments containing `@type`, `@typedef`, `@param`, `@returns`, etc.
+ * @param {AST.CommentWithLocation} comment
+ * @returns {boolean}
+ */
+export function is_jsdoc_ts_annotation(comment) {
+	if (comment.type !== 'Block') return false;
+
+	// JSDoc comments start with /** which means the value starts with * after /* is stripped
+	if (!comment.value.startsWith('*')) return false;
+
+	// Check if it contains TypeScript-relevant tags
+	const tsAnnotations = [
+		'@type',
+		'@typedef',
+		'@param',
+		'@returns',
+		'@template',
+		'@extends',
+		'@implements',
+		'@satisfies',
+		'@overload',
+		'@import',
+	];
+
+	return tsAnnotations.some((annotation) => comment.value.includes(annotation));
+}
+
+/**
+ * Check if a comment should be preserved in to_ts mode
+ * @param {AST.CommentWithLocation} comment
+ * @returns {boolean}
+ */
+export function should_preserve_comment(comment) {
+	return (
+		is_ts_pragma(comment) || is_triple_slash_directive(comment) || is_jsdoc_ts_annotation(comment)
+	);
+}
+
+/**
+ * Format a comment for output
+ * @param {AST.CommentWithLocation} comment
+ * @returns {string}
+ */
+export function format_comment(comment) {
+	if (comment.type === 'Line') {
+		// Check if it's a triple-slash directive (value starts with /)
+		if (comment.value.trimStart().startsWith('/')) {
+			return `/// ${comment.value.trimStart().slice(1)}`;
+		}
+		return `// ${comment.value.trim()}`;
+	} else {
+		// Block comment - check if it's a JSDoc (value starts with *)
+		if (comment.value.startsWith('*')) {
+			return `/** ${comment.value.trim().slice(1)} */`;
+		}
+		return `/* ${comment.value.trim()} */`;
+	}
+}

package/src/constants.js

@@ -0,0 +1,21 @@
+export const TEMPLATE_FRAGMENT = 1;
+export const TEMPLATE_USE_IMPORT_NODE = 1 << 1;
+export const IS_CONTROLLED = 1 << 2;
+export const IS_INDEXED = 1 << 3;
+export const TEMPLATE_SVG_NAMESPACE = 1 << 5;
+export const TEMPLATE_MATHML_NAMESPACE = 1 << 6;
+
+export const HYDRATION_START = '[';
+export const HYDRATION_END = ']';
+export const HYDRATION_ERROR = {};
+
+export const BLOCK_OPEN = `<!--${HYDRATION_START}-->`;
+export const BLOCK_CLOSE = `<!--${HYDRATION_END}-->`;
+export const EMPTY_COMMENT = `<!---->`;
+
+export const ELEMENT_NODE = 1;
+export const TEXT_NODE = 3;
+export const COMMENT_NODE = 8;
+export const DOCUMENT_FRAGMENT_NODE = 11;
+
+export const DEFAULT_NAMESPACE = 'html';

package/src/errors.js

@@ -0,0 +1,82 @@
+/**
+@import * as AST from 'estree';
+@import { CompileError } from '../types/index';
+*/
+
+/**
+ *
+ * @param {string} message
+ * @param {string | null} filename
+ * @param {AST.Node | AST.NodeWithLocation} node
+ * @param {CompileError[]} [errors]
+ * @param {AST.CommentWithLocation[]} [comments]
+ * @returns {void}
+ */
+export function error(message, filename, node, errors, comments) {
+	if (errors && comments && is_error_suppressed(node, comments)) {
+		return;
+	}
+
+	const error = /** @type {CompileError} */ (new Error(message));
+
+	// same as the acorn compiler error
+	error.pos = node.start ?? undefined;
+	error.raisedAt = node.end ?? undefined;
+
+	// custom properties
+	error.fileName = filename;
+	error.end = node.end ?? undefined;
+	error.loc = !node.loc
+		? undefined
+		: {
+				start: {
+					line: node.loc.start.line,
+					column: node.loc.start.column,
+				},
+				end: {
+					line: node.loc.end.line,
+					column: node.loc.end.column,
+				},
+			};
+
+	if (errors) {
+		error.type = 'usage';
+		errors.push(error);
+		return;
+	}
+
+	error.type = 'fatal';
+	throw error;
+}
+
+/**
+ * @param {AST.CommentWithLocation} comment
+ * @return {boolean}
+ */
+function is_error_suppress_comment(comment) {
+	const text = comment.value.trim();
+	return (
+		text.startsWith('@tsrx-ignore') ||
+		text.startsWith('@tsrx-expect-error') ||
+		text.startsWith('@ripple-ignore') ||
+		text.startsWith('@ripple-expect-error')
+	);
+}
+
+/**
+ * @param {AST.Node | AST.NodeWithLocation} node
+ * @param {AST.CommentWithLocation[]} comments
+ */
+function is_error_suppressed(node, comments) {
+	if (node.loc) {
+		const node_start_line = node.loc.start.line;
+		for (const comment of comments) {
+			if (comment.type === 'Line' && comment.loc.start.line === node_start_line - 1) {
+				if (is_error_suppress_comment(comment)) {
+					return true;
+				}
+			}
+		}
+	}
+	return false;
+}

package/src/helpers.d.ts

@@ -0,0 +1,11 @@
+export type RequireAllOrNone<T, K extends keyof T> =
+	| (T & Required<Pick<T, K>>)
+	| (T & { [P in K]?: never });
+
+export type RequiredPresent<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+
+export type Nullable<T> = T | null;
+
+export type Nullish<T> = T | null | undefined;
+
+export type NestedArray<T> = (T | NestedArray<T>)[];

package/src/identifier-utils.js

@@ -0,0 +1,80 @@
+export const IDENTIFIER_OBFUSCATION_PREFIX = '_$_';
+export const STYLE_IDENTIFIER = IDENTIFIER_OBFUSCATION_PREFIX + encode_utf16_char('#') + 'style';
+export const SERVER_IDENTIFIER = IDENTIFIER_OBFUSCATION_PREFIX + encode_utf16_char('#') + 'server';
+export const CSS_HASH_IDENTIFIER = IDENTIFIER_OBFUSCATION_PREFIX + 'hash';
+
+const DECODE_UTF16_REGEX = /_u([0-9a-fA-F]{4})_/g;
+
+/**
+ * @param {string} char
+ * @returns {string}
+ */
+function encode_utf16_char(char) {
+	return `_u${('0000' + char.charCodeAt(0).toString(16)).slice(-4)}_`;
+}
+
+/**
+ * Finds the next uppercase character or returns name.length
+ * @param {string} name
+ * @param {number} start
+ * @returns {number}
+ */
+function find_next_uppercase(name, start) {
+	for (let i = start; i < name.length; i++) {
+		if (name[i] === name[i].toUpperCase()) {
+			return i;
+		}
+	}
+	return name.length;
+}
+
+/**
+ * @param {string} encoded
+ * @returns {string}
+ */
+function decode_utf16_string(encoded) {
+	return encoded.replace(DECODE_UTF16_REGEX, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+}
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+export function obfuscate_identifier(name) {
+	const first_char = name[0];
+	let start = 0;
+	if (first_char === '@' || first_char === '#') {
+		const encoded = encode_utf16_char(first_char);
+		name = encoded + name.slice(1);
+		start = encoded.length;
+	} else if (first_char === first_char.toUpperCase()) {
+		start = 1;
+	}
+	const index = find_next_uppercase(name, start);
+
+	const first_part = name.slice(0, index);
+	const second_part = name.slice(index);
+
+	return (
+		IDENTIFIER_OBFUSCATION_PREFIX +
+		(second_part ? second_part + '__' + first_part : first_part + '__')
+	);
+}
+
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function is_identifier_obfuscated(name) {
+	return name.startsWith(IDENTIFIER_OBFUSCATION_PREFIX);
+}
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+export function deobfuscate_identifier(name) {
+	name = name.replaceAll(IDENTIFIER_OBFUSCATION_PREFIX, '');
+	const parts = name.split('__');
+	return decode_utf16_string((parts[1] ? parts[1] : '') + parts[0]);
+}