ripple 0.2.196 → 0.2.197

package/package.json

@@ -3,7 +3,7 @@
   "description": "Ripple is an elegant TypeScript UI framework",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.2.196",
+  "version": "0.2.197",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",
@@ -92,6 +92,6 @@
     "vscode-languageserver-types": "^3.17.5"
   },
   "peerDependencies": {
-    "ripple": "0.2.196"
+    "ripple": "0.2.197"
   }
 }

package/src/compiler/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.includes(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/compiler/errors.js

@@ -6,7 +6,7 @@
 /**
  *
  * @param {string} message
- * @param {string} filename
+ * @param {string | null} filename
  * @param {AST.Node} node
  * @param {RippleCompileError[]} [errors]
  * @returns {void}

package/src/compiler/identifier-utils.js

@@ -13,11 +13,26 @@ 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 decoded_utf16_string(encoded) {
+function decode_utf16_string(encoded) {
 	return encoded.replace(DECODE_UTF16_REGEX, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
 }
 
@@ -26,8 +41,13 @@ function decoded_utf16_string(encoded) {
  * @returns {string}
  */
 export function obfuscate_identifier(name) {
+	const first_char = name[0];
 	let start = 0;
-	if (name[0] === name[0].toUpperCase()) {
+	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);
@@ -56,20 +76,5 @@ export function is_identifier_obfuscated(name) {
 export function deobfuscate_identifier(name) {
 	name = name.replaceAll(IDENTIFIER_OBFUSCATION_PREFIX, '');
 	const parts = name.split('__');
-	return decoded_utf16_string((parts[1] ? parts[1] : '') + parts[0]);
-}
-
-/**
- * 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;
+	return decode_utf16_string((parts[1] ? parts[1] : '') + parts[0]);
 }

package/src/compiler/index.d.ts

@@ -87,7 +87,7 @@ export interface RippleCompileError extends Error {
 	raisedAt: number | undefined;
 	end: number | undefined;
 	loc: AST.SourceLocation | undefined;
-	fileName: string | undefined;
+	fileName: string | null;
 	type: 'fatal' | 'usage';
 }
 
@@ -104,13 +104,18 @@ export interface CompileOptions extends SharedCompileOptions {
 
 export interface ParseOptions {
 	loose?: boolean;
+	errors?: RippleCompileError[];
+	comments?: AST.CommentWithLocation[];
 }
 
 export interface AnalyzeOptions extends ParseOptions, Pick<CompileOptions, 'mode'> {
+	errors?: RippleCompileError[];
 	to_ts?: boolean;
 }
 
-export interface VolarCompileOptions extends ParseOptions, SharedCompileOptions {}
+export interface VolarCompileOptions
+	extends Omit<ParseOptions, 'errors' | 'comments'>,
+		SharedCompileOptions {}
 
 export function parse(source: string, options?: ParseOptions): AST.Program;
 

package/src/compiler/index.js

@@ -12,7 +12,7 @@ import { convert_source_map_to_mappings } from './phases/3-transform/segments.js
  * @returns {AST.Program}
  */
 export function parse(source) {
-	return parse_module(source, undefined);
+	return parse_module(source, undefined, undefined);
 }
 
 /**
@@ -23,7 +23,7 @@ export function parse(source) {
  * @returns {object}
  */
 export function compile(source, filename, options = {}) {
-	const ast = parse_module(source, undefined);
+	const ast = parse_module(source, filename, undefined);
 	const analysis = analyze(ast, filename, options);
 	const result =
 		options.mode === 'server'
@@ -34,7 +34,7 @@ export function compile(source, filename, options = {}) {
 }
 
 /** @import { PostProcessingChanges, LineOffsets } from './phases/3-transform/client/index.js' */
-/** @import { VolarMappingsResult, VolarCompileOptions, CompileOptions } from 'ripple/compiler' */
+/** @import { VolarMappingsResult, VolarCompileOptions, CompileOptions, RippleCompileError } from 'ripple/compiler' */
 
 /**
  * Compile Ripple component to Volar virtual code with TypeScript mappings
@@ -43,9 +43,16 @@ export function compile(source, filename, options = {}) {
  * @param {VolarCompileOptions} [options] - Compiler options
  * @returns {VolarMappingsResult} Volar mappings object
  */
-export function compile_to_volar_mappings(source, filename, options) {
-	const ast = parse_module(source, options);
-	const analysis = analyze(ast, filename, { to_ts: true, loose: !!options?.loose });
+export function compile_to_volar_mappings(source, filename, options = {}) {
+	const errors = /** @type {RippleCompileError[]} */ ([]);
+	const comments = /** @type {AST.CommentWithLocation[]} */ ([]);
+	const ast = parse_module(source, filename, { ...options, errors, comments });
+	const analysis = analyze(ast, filename, {
+		to_ts: true,
+		loose: !!options?.loose,
+		errors,
+		comments,
+	});
 	const transformed = transform_client(
 		filename,
 		source,