macroforge_ts 0.1.80

//! # TypeScript Macro Host
//!
//! The macro host module provides the core infrastructure for TypeScript macro
//! expansion. It handles the complete lifecycle of macro processing: registration,
//! dispatch, execution, and patch application.
//!
//! ## Architecture Overview
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────────┐
//! │                      MacroExpander                               │
//! │  (Main entry point - coordinates the expansion process)         │
//! └─────────────────────────────────────────────────────────────────┘
//!                              │
//!                              ▼
//! ┌─────────────────────────────────────────────────────────────────┐
//! │                     MacroDispatcher                              │
//! │  (Routes macro calls to implementations with ABI checking)       │
//! └─────────────────────────────────────────────────────────────────┘
//!                              │
//!                              ▼
//! ┌─────────────────────────────────────────────────────────────────┐
//! │                      MacroRegistry                               │
//! │  (Thread-safe storage of registered macros using DashMap)        │
//! └─────────────────────────────────────────────────────────────────┘
//!                              │
//!                              ▼
//! ┌─────────────────────────────────────────────────────────────────┐
//! │                    PatchApplicator                               │
//! │  (Applies generated patches with source mapping)                 │
//! └─────────────────────────────────────────────────────────────────┘
//! ```
//!
//! ## Module Organization
//!
//! - [`config`] - Configuration loading and management (`macroforge.config.ts`)
//! - [`derived`] - Inventory-based registration for built-in derive macros
//! - [`dispatch`] - Macro call routing and ABI version checking
//! - [`error`] - Error types (`MacroError`) and `Result` type alias
//! - [`expand`] - The main `MacroExpander` that orchestrates expansion
//! - [`macros`] - Helper macros for macro registration
//! - [`package_registry`] - Global registry for macro package registrars
//! - [`patch_applicator`] - Applies code patches with source mapping
//! - [`registry`] - Thread-safe macro storage (`MacroRegistry`)
//! - [`traits`] - Core traits (`Macroforge`, `MacroPackage`)
//!
//! ## Key Types
//!
//! - [`MacroExpander`] - Main entry point for macro expansion
//! - [`MacroDispatcher`] - Routes macros to implementations
//! - [`MacroRegistry`] - Stores registered macros
//! - [`Macroforge`] - Trait that all macros must implement
//! - [`MacroConfig`] - Configuration options
//! - [`MacroError`] - Error type for macro operations
//!
//! ## Usage Example
//!
//! ```rust,no_run
//! use macroforge_ts::host::{MacroExpander, Result};
//!
//! fn example() -> Result<()> {
//!     // Create a new expander (registers all built-in macros)
//!     let expander = MacroExpander::new()?;
//!
//!     // Parse TypeScript source code
//!     let source = r#"
//!         /** @derive(Debug) */
//!         class User { name: string; }
//!     "#;
//!
//!     // Expand macros (handles parsing internally)
//!     let result = expander.expand_source(source, "file.ts")?;
//!     println!("Expanded: {}", result.code);
//!     Ok(())
//! }
//! ```

/// Configuration loading and management.
pub mod config;

/// Compile-time `@buildtime` evaluation — sandboxed JS execution during
/// source transformation, Zig-comptime style.
pub mod buildtime;

/// Declarative (pattern-matching) macros — the `$name(...)` macro system.
pub mod declarative;

/// Inventory-based registration for built-in derive macros.
pub mod derived;

/// Macro call dispatching with ABI version checking.
pub mod dispatch;

/// Error types for macro operations.
pub mod error;

/// The main macro expansion engine.
pub mod expand;

/// Unified import registry for macro expansion.
pub mod import_registry;

/// Helper macros for macro registration.
pub mod macros;

/// Global registry for macro package registrars.
pub mod package_registry;

/// Patch application with source mapping.
pub mod patch_applicator;

/// Thread-safe macro storage.
pub mod registry;

/// Project-wide TypeScript scanner for type awareness.
pub mod scanner;

/// Core traits for macro implementations.
pub mod traits;

/// Type resolution against the project-wide registry.
pub mod type_resolver;

// Primary exports for convenience
pub use config::{
    CONFIG_CACHE, ForeignTypeConfig, ImportInfo, MacroConfig, MacroforgeConfig,
    MacroforgeConfigLoader, clear_config_cache,
};
pub use dispatch::MacroDispatcher;
pub use error::{MacroError, Result};
#[cfg(feature = "swc")]
pub use expand::{ImportCollectionResult, collect_import_sources};
pub use expand::{MacroExpander, MacroExpansion};
pub use import_registry::{
    ImportRegistry, clear_foreign_types, clear_registry, install_registry, set_foreign_types,
    with_foreign_types, with_foreign_types_mut, with_registry, with_registry_mut,
};
pub use package_registry::MacroPackageRegistration;
pub use patch_applicator::{PatchApplicator, PatchCollector};
pub use registry::MacroRegistry;
pub use traits::Macroforge;

// Re-export commonly used types from the ABI module for convenience.
// These types are needed when implementing custom macros.
pub use crate::ts_syn::abi::{Diagnostic, DiagnosticLevel, MacroKind, MacroResult, Patch};