@macroforge/mcp-server 0.1.17 → 0.1.20

package/docs/builtin-macros/serialize.md

@@ -4,37 +4,14 @@
 
 ## Basic Usage
 
-```typescript
-/** @derive(Serialize) */
-class User {
-  name: string;
-  age: number;
-  createdAt: Date;
-
-  constructor(name: string, age: number) {
-    this.name = name;
-    this.age = age;
-    this.createdAt = new Date();
-  }
-}
+<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
 
+```typescript
 const user = new User("Alice", 30);
 console.log(JSON.stringify(user));
 // {"name":"Alice","age":30,"createdAt":"2024-01-15T10:30:00.000Z"}
 ```
 
-## Generated Code
-
-```typescript
-toJSON(): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-  result["name"] = this.name;
-  result["age"] = this.age;
-  result["createdAt"] = this.createdAt.toISOString();
-  return result;
-}
-```
-
 ## Automatic Type Handling
 
 Serialize automatically handles various TypeScript types:
@@ -57,32 +34,15 @@ Serialize automatically handles various TypeScript types:
 | Nested objects 
 | Calls `toJSON()` if available
 
-```typescript
-/** @derive(Serialize) */
-class DataContainer {
-  items: string[];
-  metadata: Map<string, number>;
-  tags: Set<string>;
-  nested: User;
-}
-```
-
 ## Serde Options
 
 Use the `@serde` decorator for fine-grained control over serialization:
 
 ### Renaming Fields
 
-```typescript
-/** @derive(Serialize) */
-class User {
-  /** @serde({ rename: "user_id" }) */
-  id: string;
-
-  /** @serde({ rename: "full_name" }) */
-  name: string;
-}
+<MacroExample before={data.examples.rename.before} after={data.examples.rename.after} />
 
+```typescript
 const user = new User();
 user.id = "123";
 user.name = "Alice";
@@ -92,19 +52,7 @@ console.log(JSON.stringify(user));
 
 ### Skipping Fields
 
-```typescript
-/** @derive(Serialize) */
-class User {
-  name: string;
-  email: string;
-
-  /** @serde({ skip: true }) */
-  password: string;
-
-  /** @serde({ skip_serializing: true }) */
-  internalId: string;
-}
-```
+<MacroExample before={data.examples.skip.before} after={data.examples.skip.after} />
 
 <Alert type="tip" title="skip vs skip_serializing">
 Use `skip: true` to exclude from both serialization and deserialization.
@@ -115,15 +63,13 @@ Use `skip_serializing: true` to only skip during serialization.
 
 Apply a naming convention to all fields at the container level:
 
-```typescript
-/** @derive(Serialize) */
+<InteractiveMacro code={`/** @derive(Serialize) */
 /** @serde({ rename_all: "camelCase" }) */
 class ApiResponse {
-  user_name: string;    // becomes "userName"
-  created_at: Date;     // becomes "createdAt"
-  is_active: boolean;   // becomes "isActive"
-}
-```
+  user_name: string;
+  created_at: Date;
+  is_active: boolean;
+}`} />
 
 Supported conventions:
 
@@ -139,8 +85,7 @@ Supported conventions:
 
 ### Flattening Nested Objects
 
-```typescript
-/** @derive(Serialize) */
+<InteractiveMacro code={`/** @derive(Serialize) */
 class Address {
   city: string;
   zip: string;
@@ -152,8 +97,9 @@ class User {
 
   /** @serde({ flatten: true }) */
   address: Address;
-}
+}`} />
 
+```typescript
 const user = new User();
 user.name = "Alice";
 user.address = { city: "NYC", zip: "10001" };
@@ -191,25 +137,9 @@ console.log(JSON.stringify(user));
 
 Serialize also works with interfaces. For interfaces, a namespace is generated with a `toJSON` function:
 
-```typescript
-/** @derive(Serialize) */
-interface ApiResponse {
-  status: number;
-  message: string;
-  timestamp: Date;
-}
-
-// Generated:
-// export namespace ApiResponse {
-//   export function toJSON(self: ApiResponse): Record<string, unknown> {
-//     const result: Record<string, unknown> = {};
-//     result["status"] = self.status;
-//     result["message"] = self.message;
-//     result["timestamp"] = self.timestamp.toISOString();
-//     return result;
-//   }
-// }
+<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
 
+```typescript
 const response: ApiResponse = {
   status: 200,
   message: "OK",
@@ -224,35 +154,23 @@ console.log(JSON.stringify(ApiResponse.toJSON(response)));
 
 Serialize also works with enums. The `toJSON` function returns the underlying enum value (string or number):
 
-```typescript
-/** @derive(Serialize) */
-enum Status {
-  Active = "active",
-  Inactive = "inactive",
-  Pending = "pending",
-}
-
-// Generated:
-// export namespace Status {
-//   export function toJSON(value: Status): string | number {
-//     return value;
-//   }
-// }
+<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
 
+```typescript
 console.log(Status.toJSON(Status.Active));  // "active"
 console.log(Status.toJSON(Status.Pending)); // "pending"
 ```
 
 Works with numeric enums too:
 
-```typescript
-/** @derive(Serialize) */
+<InteractiveMacro code={`/** @derive(Serialize) */
 enum Priority {
   Low = 1,
   Medium = 2,
   High = 3,
-}
+}`} />
 
+```typescript
 console.log(Priority.toJSON(Priority.High)); // 3
 ```
 
@@ -260,25 +178,9 @@ console.log(Priority.toJSON(Priority.High)); // 3
 
 Serialize works with type aliases. For object types, fields are serialized with full type handling:
 
-```typescript
-/** @derive(Serialize) */
-type UserProfile = {
-  id: string;
-  name: string;
-  createdAt: Date;
-};
-
-// Generated:
-// export namespace UserProfile {
-//   export function toJSON(value: UserProfile): Record<string, unknown> {
-//     const result: Record<string, unknown> = {};
-//     result["id"] = value.id;
-//     result["name"] = value.name;
-//     result["createdAt"] = value.createdAt.toISOString();
-//     return result;
-//   }
-// }
+<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
 
+```typescript
 const profile: UserProfile = {
   id: "123",
   name: "Alice",
@@ -291,10 +193,10 @@ console.log(JSON.stringify(UserProfile.toJSON(profile)));
 
 For union types, the value is returned directly:
 
-```typescript
-/** @derive(Serialize) */
-type ApiStatus = "loading" | "success" | "error";
+<InteractiveMacro code={`/** @derive(Serialize) */
+type ApiStatus = "loading" | "success" | "error";`} />
 
+```typescript
 console.log(ApiStatus.toJSON("success")); // "success"
 ```
 
@@ -302,13 +204,13 @@ console.log(ApiStatus.toJSON("success")); // "success"
 
 Use both Serialize and Deserialize for complete JSON round-trip support:
 
-```typescript
-/** @derive(Serialize, Deserialize) */
+<InteractiveMacro code={`/** @derive(Serialize, Deserialize) */
 class User {
   name: string;
   createdAt: Date;
-}
+}`} />
 
+```typescript
 // Serialize
 const user = new User();
 user.name = "Alice";

package/docs/concepts/architecture.md

@@ -4,21 +4,12 @@
 
 ## Overview
 
-```text
-┌─────────────────────────────────────────────────────────┐
-│                    Node.js / Vite                        │
-├─────────────────────────────────────────────────────────┤
-│                   NAPI-RS Bindings                       │
-├─────────────────────────────────────────────────────────┤
-│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐   │
-│  │   ts_syn    │  │   ts_quote   │  │ts_macro_derive│   │
-│  │  (parsing)  │  │ (templating) │  │  (proc-macro) │   │
-│  └─────────────┘  └──────────────┘  └───────────────┘   │
-├─────────────────────────────────────────────────────────┤
-│                    SWC Core                              │
-│            (TypeScript parsing & codegen)                │
-└─────────────────────────────────────────────────────────┘
-```
+<ArchitectureDiagram layers={[
+{ title: "Node.js / Vite" },
+{ title: "NAPI-RS Bindings" },
+{ title: "Macro Crates", items: ["macroforge_ts_syn", "macroforge_ts_quote", "macroforge_ts_macros"] },
+{ title: "SWC Core", items: ["TypeScript parsing & codegen"] }
+]} />
 
 ## Core Components
 
@@ -32,7 +23,7 @@ The foundation layer provides:
 
 - Code generation (AST → source code)
 
-### ts_syn
+### macroforge_ts_syn
 
 A Rust crate that provides:
 
@@ -42,7 +33,7 @@ A Rust crate that provides:
 
 - Derive input structures (class fields, decorators, etc.)
 
-### ts_quote
+### macroforge_ts_quote
 
 Template-based code generation similar to Rust's `quote!`:
 
@@ -52,7 +43,7 @@ Template-based code generation similar to Rust's `quote!`:
 
 - Control flow: `{"{#for}"}`, `{"{#if}"}`, `{"{$let}"}`
 
-### ts_macro_derive
+### macroforge_ts_macros
 
 The procedural macro attribute for defining derive macros:
 
@@ -74,33 +65,16 @@ Bridges Rust and Node.js:
 
 ## Data Flow
 
-```text
-1. Source Code (TypeScript with @derive)
-   │
-   ▼
-2. NAPI-RS receives JavaScript string
-   │
-   ▼
-3. SWC parses to AST
-   │
-   ▼
-4. Macro expander finds @derive decorators
-   │
-   ▼
-5. For each macro:
-   │  a. Extract class/interface data
-   │  b. Run macro function
-   │  c. Generate new AST nodes
-   │
-   ▼
-6. Merge generated nodes into AST
-   │
-   ▼
-7. SWC generates source code
-   │
-   ▼
-8. Return to JavaScript with source mapping
-```
+<Flowchart steps={[
+{ title: "1. Source Code", description: "TypeScript with @derive" },
+{ title: "2. NAPI-RS", description: "receives JavaScript string" },
+{ title: "3. SWC Parser", description: "parses to AST" },
+{ title: "4. Macro Expander", description: "finds @derive decorators" },
+{ title: "5. For Each Macro", description: "extract data, run macro, generate AST nodes" },
+{ title: "6. Merge", description: "generated nodes into AST" },
+{ title: "7. SWC Codegen", description: "generates source code" },
+{ title: "8. Return", description: "to JavaScript with source mapping" }
+]} />
 
 ## Performance Characteristics
 
@@ -117,19 +91,14 @@ Bridges Rust and Node.js:
 For custom macro development, `macroforge_ts` re-exports everything you need:
 
 ```rust
-// All available via macroforge_ts::*
-pub extern crate ts_syn;         // AST types, parsing
-pub extern crate ts_quote;       // Code generation templates
-pub extern crate ts_macro_derive; // #[ts_macro_derive] attribute
-pub extern crate inventory;       // Macro registration
-pub extern crate serde_json;      // Serialization
-pub extern crate napi;            // Node.js bindings
-pub extern crate napi_derive;     // NAPI proc-macros
-
-// SWC modules
-pub use ts_syn::swc_core;
-pub use ts_syn::swc_common;
-pub use ts_syn::swc_ecma_ast;
+// Convenient re-exports for macro development
+use macroforge_ts::macros::{ts_macro_derive, body, ts_template, above, below, signature};
+use macroforge_ts::ts_syn::{Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input};
+
+// Also available: raw crate access and SWC modules
+use macroforge_ts::swc_core;
+use macroforge_ts::swc_common;
+use macroforge_ts::swc_ecma_ast;
 ```
 
 ## Next Steps

package/docs/concepts/derive-system.md

@@ -10,13 +10,10 @@ Macroforge uses JSDoc comments for all macro annotations. This ensures compatibi
 
 The `@derive` decorator triggers macro expansion on a class or interface:
 
-```typescript
-/** @derive(MacroName) */
-class MyClass { }
-
-/** @derive(Debug, Clone, PartialEq) */
-class AnotherClass { }
-```
+<InteractiveMacro code={`/** @derive(Debug) */
+class MyClass {
+  value: string;
+}`} />
 
 Syntax rules:
 
@@ -28,16 +25,11 @@ Syntax rules:
 
 - Multiple `@derive` statements can be stacked
 
-```typescript
-// Single derive with multiple macros
-/** @derive(Debug, Clone) */
-class User { }
-
-// Multiple derive statements (equivalent)
-/** @derive(Debug) */
-/** @derive(Clone) */
-class User { }
-```
+<InteractiveMacro code={`/** @derive(Debug, Clone) */
+class User {
+  name: string;
+  email: string;
+}`} />
 
 ### The import macro Statement
 
@@ -68,36 +60,15 @@ class User {
 }
 ```
 
->
-> Built-in macros (Debug, Clone, Default, Hash, Ord, PartialEq, PartialOrd, Serialize, Deserialize) do not require an import statement.
+<Alert type="note" title="Built-in macros">
+Built-in macros (Debug, Clone, Default, Hash, Ord, PartialEq, PartialOrd, Serialize, Deserialize) do not require an import statement.
+</Alert>
 
 ### Field Attributes
 
 Macros can define field-level attributes to customize behavior per field:
 
-```typescript
-/** @attributeName(options) */
-```
-
-The attribute name and available options depend on the macro. Common patterns:
-
-```typescript
-/** @derive(Debug, Serialize) */
-class User {
-  /** @debug({ rename: "userId" }) */
-  /** @serde({ rename: "user_id" }) */
-  id: number;
-
-  name: string;
-
-  /** @debug({ skip: true }) */
-  /** @serde({ skip: true }) */
-  password: string;
-
-  /** @serde({ flatten: true }) */
-  metadata: Record<string, unknown>;
-}
-```
+<MacroExample before={data.examples.fieldAttributes.before} after={data.examples.fieldAttributes.after} />
 
 Syntax rules:
 
@@ -149,10 +120,11 @@ The derive system works on:
 
 - **Classes**: The primary target for derive macros
 
-- **Interfaces**: Some macros can generate companion functions
+- **Interfaces**: Macros generate companion namespace functions
+
+- **Enums**: Macros generate namespace functions for enum values
 
-> **Warning:**
-> Enums are not currently supported by the derive system.
+- **Type aliases**: Both object types and union types are supported
 
 ## Built-in vs Custom Macros
 

package/docs/concepts/how-macros-work.md

@@ -14,22 +14,7 @@ Unlike runtime solutions that use reflection or proxies, Macroforge expands macr
 
 4. **Output**: The transformed TypeScript is written out, ready for normal compilation
 
-```typescript
-// Your source code
-/** @derive(Debug) */
-class User {
-  name: string;
-}
-
-// After macro expansion
-class User {
-  name: string;
-
-  toString(): string {
-    return \`User { name: \${this.name} }\`;
-  }
-}
-```
+<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
 
 ## Zero Runtime Overhead
 
@@ -55,43 +40,19 @@ Macroforge tracks the relationship between your source code and the expanded out
 
 - IDE features like "go to definition" work as expected
 
-> **Note:**
-> The TypeScript plugin uses source mapping to show errors at the `@derive` decorator position, not in the generated code.
+<Alert type="info" title="Error positioning">
+The TypeScript plugin uses source mapping to show errors at the `@derive` decorator position, not in the generated code.
+</Alert>
 
 ## Execution Flow
 
-```text
-┌─────────────────────────────────────────────────────────┐
-│                    Your Source Code                      │
-│              (with @derive decorators)                   │
-└───────────────────────┬─────────────────────────────────┘
-                        │
-                        ▼
-┌─────────────────────────────────────────────────────────┐
-│                   SWC Parser                             │
-│            (TypeScript → AST)                            │
-└───────────────────────┬─────────────────────────────────┘
-                        │
-                        ▼
-┌─────────────────────────────────────────────────────────┐
-│                Macro Expansion Engine                    │
-│    - Finds @derive decorators                            │
-│    - Runs registered macros                              │
-│    - Generates new AST nodes                             │
-└───────────────────────┬─────────────────────────────────┘
-                        │
-                        ▼
-┌─────────────────────────────────────────────────────────┐
-│                 Code Generator                           │
-│            (AST → TypeScript)                            │
-└───────────────────────┬─────────────────────────────────┘
-                        │
-                        ▼
-┌─────────────────────────────────────────────────────────┐
-│                 Expanded TypeScript                      │
-│         (ready for normal compilation)                   │
-└─────────────────────────────────────────────────────────┘
-```
+<Flowchart steps={[
+{ title: "Your Source Code", description: "with @derive decorators" },
+{ title: "SWC Parser", description: "TypeScript → AST" },
+{ title: "Macro Expansion Engine", description: "Finds @derive decorators, runs macros, generates new AST nodes" },
+{ title: "Code Generator", description: "AST → TypeScript" },
+{ title: "Expanded TypeScript", description: "ready for normal compilation" }
+]} />
 
 ## Integration Points
 

package/docs/custom-macros/custom-overview.md

@@ -10,15 +10,14 @@ Custom macros are written in Rust and compiled to native Node.js addons. The pro
 
 2. Defining macro functions with `#[ts_macro_derive]`
 
-3. Using `ts_quote` to generate TypeScript code
+3. Using `macroforge_ts_quote` to generate TypeScript code
 
 4. Building and publishing as an npm package
 
 ## Quick Example
 
 ```rust
-use macroforge_ts::ts_macro_derive::ts_macro_derive;
-use macroforge_ts::ts_quote::body;
+use macroforge_ts::macros::{ts_macro_derive, body};
 use macroforge_ts::ts_syn::{Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input};
 
 #[ts_macro_derive(
@@ -79,6 +78,6 @@ Follow these guides to create your own macros:
 
 - [Set up a Rust macro crate]({base}/docs/custom-macros/rust-setup)
 
-- [Use the ts_macro_derive attribute]({base}/docs/custom-macros/ts-macro-derive)
+- [Learn the #[ts_macro_derive] attribute]({base}/docs/custom-macros/ts-macro-derive)
 
-- [Learn the ts_quote template syntax]({base}/docs/custom-macros/ts-quote)
+- [Learn the template syntax]({base}/docs/custom-macros/ts-quote)

package/docs/custom-macros/rust-setup.md

@@ -61,8 +61,7 @@ fn main() {
 
 `src/lib.rs`
 ```rust
-use macroforge_ts::ts_macro_derive::ts_macro_derive;
-use macroforge_ts::ts_quote::body;
+use macroforge_ts::macros::{ts_macro_derive, body};
 use macroforge_ts::ts_syn::{
     Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input,
 };
@@ -141,6 +140,6 @@ npm run build
 
 ## Next Steps
 
-- [Learn the ts_macro_derive attribute]({base}/docs/custom-macros/ts-macro-derive)
+- [Learn the #[ts_macro_derive] attribute]({base}/docs/custom-macros/ts-macro-derive)
 
-- [Master the ts_quote template syntax]({base}/docs/custom-macros/ts-quote)
+- [Master the template syntax]({base}/docs/custom-macros/ts-quote)

package/docs/custom-macros/ts-macro-derive.md

@@ -5,7 +5,7 @@
 ## Basic Syntax
 
 ```rust
-use macroforge_ts::ts_macro_derive::ts_macro_derive;
+use macroforge_ts::macros::ts_macro_derive;
 use macroforge_ts::ts_syn::{TsStream, MacroforgeError};
 
 #[ts_macro_derive(MacroName)]
@@ -70,7 +70,7 @@ pub fn my_macro(mut input: TsStream) -> Result<TsStream, MacroforgeError>
 Use `parse_ts_macro_input!` to convert the token stream:
 
 ```rust
-use macroforge_ts::ts_syn::{DeriveInput, Data, parse_ts_macro_input};
+use macroforge_ts::ts_syn::{Data, DeriveInput, parse_ts_macro_input};
 
 #[ts_macro_derive(MyMacro)]
 pub fn my_macro(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
@@ -256,8 +256,7 @@ pub fn class_only(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
 ## Complete Example
 
 ```rust
-use macroforge_ts::ts_macro_derive::ts_macro_derive;
-use macroforge_ts::ts_quote::body;
+use macroforge_ts::macros::{ts_macro_derive, body};
 use macroforge_ts::ts_syn::{
     Data, DeriveInput, FieldIR, MacroforgeError, TsStream, parse_ts_macro_input,
 };
@@ -304,4 +303,4 @@ pub fn derive_validate(mut input: TsStream) -> Result<TsStream, MacroforgeError>
 
 ## Next Steps
 
-- [Learn the ts_quote template syntax]({base}/docs/custom-macros/ts-quote)
+- [Learn the template syntax]({base}/docs/custom-macros/ts-quote)

package/docs/custom-macros/ts-quote.md

@@ -1,6 +1,6 @@
-# Template Syntax (ts_quote)
+# Template Syntax
 
-*The `ts_quote` crate provides template-based code generation for TypeScript. The `ts_template!` macro uses Rust-inspired syntax for control flow and interpolation, making it easy to generate complex TypeScript code.*
+*The `macroforge_ts_quote` crate provides template-based code generation for TypeScript. The `ts_template!` macro uses Rust-inspired syntax for control flow and interpolation, making it easy to generate complex TypeScript code.*
 
 ## Available Macros