Library/Fn/OXC/

Transformer.rs

//! OXC TypeScript Transformer module
//!
//! This module provides TypeScript to JavaScript transformation using the OXC
//! transformer. It handles TypeScript type stripping, decorator transformation,
//! and ECMAScript version transpilation.
//!
//! DIAGNOSTIC LOGGING:
//! - Tracks transformer lifecycle and memory access
//! - Logs allocator addresses to detect use-after-free

use std::{
	path::Path,
	sync::atomic::{AtomicUsize, Ordering},
};

use oxc_allocator::Allocator;
use oxc_ast::ast::Program;
use oxc_semantic::SemanticBuilder;
use oxc_span::SourceType;
use oxc_transformer::{
	CompilerAssumptions,
	EnvOptions,
	JsxOptions,
	JsxRuntime,
	TransformOptions,
	Transformer,
	TypeScriptOptions,
};
use tracing::{debug, info, trace, warn};

/// Transformer configuration options
#[derive(Debug, Clone)]
pub struct TransformerConfig {
	/// Target ECMAScript version (e.g., "es2024")
	pub target:String,

	/// Module format (commonjs, esmodule, etc.)
	pub module_format:String,

	/// Whether to emit decorator metadata
	pub emit_decorator_metadata:bool,

	/// Whether to use define for class fields (VSCode compatibility)
	pub use_define_for_class_fields:bool,

	/// Whether to support JSX
	pub jsx:bool,

	/// Whether to enable tree-shaking
	pub tree_shaking:bool,

	/// Whether to enable minification
	pub minify:bool,
}

impl Default for TransformerConfig {
	fn default() -> Self {
		Self {
			target:"es2024".to_string(),

			module_format:"commonjs".to_string(),

			emit_decorator_metadata:true,

			use_define_for_class_fields:false,

			jsx:false,

			tree_shaking:false,

			minify:false,
		}
	}
}

impl TransformerConfig {
	/// Create a new transformer configuration
	pub fn new(
		target:String,

		_module_format:String,

		_emit_decorator_metadata:bool,

		use_define_for_class_fields:bool,

		jsx:bool,

		_tree_shaking:bool,

		_minify:bool,
	) -> Self {
		Self {
			target,

			module_format:_module_format,

			emit_decorator_metadata:_emit_decorator_metadata,

			use_define_for_class_fields,

			jsx,

			tree_shaking:_tree_shaking,

			minify:_minify,
		}
	}
}

/// Transform a parsed AST from TypeScript to JavaScript
///
/// # Arguments
/// * `allocator` - The allocator used for the AST
/// * `program` - The parsed program AST (mutable)
/// * `source_path` - The source file path
/// * `source_type` - The source type (TypeScript, JSX, etc.)
/// * `config` - Transformer configuration options
///
/// # Returns
/// Result containing transformation errors if any
static TRANSFORM_COUNT:AtomicUsize = AtomicUsize::new(0);

#[tracing::instrument(skip(allocator, program, config))]
pub fn transform<'a>(
	allocator:&'a Allocator,

	program:&mut Program<'a>,

	source_path:&str,

	_source_type:SourceType,

	config:&TransformerConfig,
) -> Result<(), Vec<String>> {
	let transform_id = TRANSFORM_COUNT.fetch_add(1, Ordering::SeqCst);

	info!("[Transform #{transform_id}] Starting transformation of: {}", source_path);

	trace!("[Transform #{transform_id}] Allocator address: {:p}", allocator);

	trace!("[Transform #{transform_id}] Program address: {:p}", program);

	trace!(
		"[Transform #{transform_id}] Program body ptr before: {:p}, len: {}",
		program.body.as_ptr(),
		program.body.len()
	);

	debug!(
		"[Transform #{transform_id}] Config: target={}, module={}, use_define={}",
		config.target, config.module_format, config.use_define_for_class_fields
	);

	// Build semantic information required for transformations
	let semantic_start = std::time::Instant::now();

	let semantic_ret = SemanticBuilder::new().build(program);

	info!(
		"[Transform #{transform_id}] Semantic build completed in {:?}",
		semantic_start.elapsed()
	);

	if !semantic_ret.errors.is_empty() {
		let errors:Vec<String> = semantic_ret.errors.iter().map(|e| e.to_string()).collect();

		warn!("[Transform #{transform_id}] Semantic errors: {:?}", errors);

		return Err(errors);
	}

	// Extract the unified scoping (symbol table + scope tree) from semantic.
	// OXC 0.127 collapsed the separate `SymbolTable` + `ScopeTree` accessors
	// into a single `Scoping` value returned by `into_scoping()`. The older
	// `into_symbol_table_and_scope_tree()` (0.48-era API) no longer exists,
	// and `Transformer::build_with_symbols_and_scopes` has likewise been
	// replaced by `build_with_scoping` below.
	let scoping = semantic_ret.semantic.into_scoping();

	trace!(
		"[Transform #{transform_id}] Extracted scoping: {} symbols, {} scopes",
		scoping.symbols_len(),
		scoping.scopes_len()
	);

	// Configure TypeScript transformation
	// Set only_remove_type_imports to true to preserve all value exports
	// This ensures modules with runtime code (like profiling.ts) emit JavaScript
	let mut typescript_options = TypeScriptOptions::default();

	typescript_options.only_remove_type_imports = true;

	trace!("[Transform #{transform_id}] TypeScript options configured (only_remove_type_imports=true)");

	// Configure JSX transformation if enabled
	let jsx_options = if config.jsx {
		JsxOptions { runtime:JsxRuntime::Automatic, ..JsxOptions::default() }
	} else {
		// Disable JSX by setting a dummy runtime
		JsxOptions { runtime:JsxRuntime::Classic, ..JsxOptions::default() }
	};

	trace!("[Transform #{transform_id}] JSX options configured");

	// Configure environment options based on target
	let env_options_start = std::time::Instant::now();

	let env_options = EnvOptions::from_target(&config.target).unwrap_or_default();

	trace!(
		"[Transform #{transform_id}] Env options from target '{}' in {:?}",
		config.target,
		env_options_start.elapsed()
	);

	// Configure compiler assumptions for VSCode compatibility.
	// The `use_define_for_class_fields` flag from TypeScript:
	// - false => loose mode (direct assignment) => set_public_class_fields = true
	// - true => strict mode (defineProperty) => set_public_class_fields = false
	let mut assumptions = CompilerAssumptions::default();

	assumptions.set_public_class_fields = !config.use_define_for_class_fields;

	trace!(
		"[Transform #{transform_id}] Compiler assumptions configured (set_public_class_fields={})",
		assumptions.set_public_class_fields
	);

	// Create transform options with all VSCode compatibility settings
	let transform_options = TransformOptions {
		typescript:typescript_options,

		jsx:jsx_options,

		env:env_options,

		assumptions,
		..TransformOptions::default()
	};

	trace!("[Transform #{transform_id}] TransformOptions configured with plugins");

	trace!("[Transform #{transform_id}] TransformOptions created");

	// Create transformer and apply transformation using OXC 0.127 API.
	let transformer_start = std::time::Instant::now();

	let transformer = Transformer::new(allocator, Path::new(source_path), &transform_options);

	info!(
		"[Transform #{transform_id}] Transformer created in {:?}",
		transformer_start.elapsed()
	);

	trace!("[Transform #{transform_id}] Transformer allocator address: {:p}", allocator);

	let build_start = std::time::Instant::now();

	let transform_ret = transformer.build_with_scoping(scoping, program);

	info!(
		"[Transform #{transform_id}] build_with_scoping completed in {:?}",
		build_start.elapsed()
	);

	trace!(
		"[Transform #{transform_id}] Program body ptr after: {:p}, len: {}",
		program.body.as_ptr(),
		program.body.len()
	);

	if !transform_ret.errors.is_empty() {
		let errors:Vec<String> = transform_ret.errors.iter().map(|e| e.to_string()).collect();

		warn!("[Transform #{transform_id}] Transformation errors: {:?}", errors);

		return Err(errors);
	}

	info!(
		"[Transform #{transform_id}] SUCCESS: Transformation completed for {}",
		source_path
	);

	Ok(())
}