macroforge_ts 0.1.80

TypeScript macro expansion engine - write compile-time macros in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

//! # `@buildtime` evaluation
//!
//! Compile-time JavaScript execution for macroforge. Semantically modelled
//! on Zig's `comptime`: a declaration annotated with `/** @buildtime */` is
//! evaluated in a sandboxed JS context during source transformation, its
//! result is serialized back to a TypeScript literal, and the original
//! declaration is replaced with that literal. Subsequent passes (declarative
//! macros, derive macros) see the spliced-in result, not the original
//! expression.
//!
//! This module holds the backend-agnostic pieces: the [`BuildtimeSandbox`]
//! trait, value and error types, capability enforcement, and the serializer
//! that converts sandbox values to TS source. The only backend today is
//! Boa ([`backends::boa`]) — a pure-Rust JS engine that compiles to both
//! native targets and wasm32-unknown-unknown, which is what the Vite
//! plugin ships. Earlier prototypes included QuickJS, V8, and deno_core
//! backends; they've been dropped in favour of Boa for portability.
//!
//! ## High-level flow
//!
//! ```text
//! source.ts
//!     │
//!     ▼
//! discovery::find_declarations      ← walks the OXC AST for /** @buildtime */
//!     │
//!     ▼
//! prepass::evaluate                 ← for each decl: synthetic module → sandbox
//!     │
//!     ▼
//! serialize::value_to_ts_source     ← SandboxValue → TS literal
//!     │
//!     ▼
//! Patch::Replace { span, code }     ← fed to the existing PatchApplicator
//! ```

pub mod backends;
pub mod capabilities;
pub mod discovery;
pub mod host_fs;
pub mod prepass;
#[cfg(feature = "oxc")]
pub mod purity;
pub mod sandbox;
pub mod serialize;

#[cfg(test)]
mod tests;

pub use capabilities::{CapabilityError, CapabilitySet, PathPattern};
pub use discovery::{BuildtimeDecl, BuildtimeKind, Visibility, discover};
pub use prepass::{PrepassOutput, run_prepass};
#[cfg(feature = "oxc")]
pub use purity::{Purity, analyze as analyze_purity};
pub use sandbox::{BuildtimeSandbox, EvalResult, SandboxError, SandboxOptions, SandboxValue};
pub use serialize::{SerializeError, value_to_ts_source};

/// Returns the default sandbox backend for the current build.
///
/// Currently only the Boa backend is available; it compiles for every
/// target macroforge runs on. Returns `None` if the `buildtime-boa`
/// feature is disabled — callers treat that as a no-op pre-pass.
#[must_use]
pub fn default_backend() -> Option<Box<dyn BuildtimeSandbox>> {
    #[cfg(feature = "buildtime-boa")]
    {
        Some(Box::new(backends::boa::BoaSandbox::new()))
    }
    #[cfg(not(feature = "buildtime-boa"))]
    {
        None
    }
}