@macroforge/mcp-server 0.1.33 → 0.1.35

package/docs/concepts/derive-system.md

@@ -1,55 +1,37 @@
 # The Derive System
-
-*The derive system is inspired by Rust's derive macros. It allows you to automatically implement common patterns by annotating your classes with `@derive`.*
-
-## Syntax Reference
-
-Macroforge uses JSDoc comments for all macro annotations. This ensures compatibility with standard TypeScript tooling.
-
-### The @derive Statement
-
-The `@derive` decorator triggers macro expansion on a class or interface:
-
-<InteractiveMacro code={`/** @derive(Debug) */
+ *The derive system is inspired by Rust's derive macros. It allows you to automatically implement common patterns by annotating your classes with `@derive`.*
+ ## Syntax Reference
+ Macroforge uses JSDoc comments for all macro annotations. This ensures compatibility with standard TypeScript tooling.
+ ### The @derive Statement
+ The `@derive` decorator triggers macro expansion on a class or interface:
+ **Source:**
+```
+/** @derive(Debug) */
 class MyClass {
   value: string;
-}`} />
-
-Syntax rules:
-
-- Must be inside a JSDoc comment (`/** */`)
-
-- Must appear immediately before the class/interface declaration
-
-- Multiple macros can be comma-separated: `@derive(A, B, C)`
-
-- Multiple `@derive` statements can be stacked
-
-<InteractiveMacro code={`/** @derive(Debug, Clone) */
+}
+```  Syntax rules:
+ - Must be inside a JSDoc comment (`/** */`)
+ - Must appear immediately before the class/interface declaration
+ - Multiple macros can be comma-separated: `@derive(A, B, C)`
+ - Multiple `@derive` statements can be stacked
+ **Source:**
+```
+/** @derive(Debug, Clone) */
 class User {
   name: string;
   email: string;
-}`} />
-
-### The import macro Statement
-
-To use macros from external packages, you must declare them with `import macro`:
-
-```typescript
+}
+```  ### The import macro Statement
+ To use macros from external packages, you must declare them with `import macro`:
+ ```
 /** import macro { MacroName } from "package-name"; */
-```
-
-Syntax rules:
-
-- Must be inside a JSDoc comment (`/** */`)
-
-- Can appear anywhere in the file (typically at the top)
-
-- Multiple macros can be imported: `import macro &#123; A, B &#125; from "pkg";`
-
-- Multiple import statements can be used for different packages
-
-```typescript
+``` Syntax rules:
+ - Must be inside a JSDoc comment (`/** */`)
+ - Can appear anywhere in the file (typically at the top)
+ - Multiple macros can be imported: `import macro { A, B } from "pkg";`
+ - Multiple import statements can be used for different packages
+ ```
 /** import macro { JSON, Validate } from "@my/macros"; */
 /** import macro { Builder } from "@other/macros"; */
 
@@ -58,88 +40,110 @@ class User {
   name: string;
   email: string;
 }
+```  **Built-in macros Built-in macros (Debug, Clone, Default, Hash, Ord, PartialEq, PartialOrd, Serialize, Deserialize) do not require an import statement. ### Field Attributes
+ Macros can define field-level attributes to customize behavior per field:
+ ****Before:**
 ```
+/** @derive(Debug, Serialize) */
+class User {
+    /** @debug({ rename: "userId" }) */
+    /** @serde({ rename: "user_id" }) */
+    id: number;
 
-<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:
-
-<MacroExample before={data.examples.fieldAttributes.before} after={data.examples.fieldAttributes.after} />
-
-Syntax rules:
-
-- Must be inside a JSDoc comment immediately before the field
-
-- Options use object literal syntax: `@attr(&#123; key: value &#125;)`
-
-- Boolean options: `@attr(&#123; skip: true &#125;)`
-
-- String options: `@attr(&#123; rename: "newName" &#125;)`
-
-- Multiple attributes can be on separate lines or combined
-
-Common field attributes by macro:
-
-| Debug 
-| `@debug` 
-| `skip`, `rename` 
-
-| Clone 
-| `@clone` 
-| `skip`, `clone_with` 
-
-| Serialize/Deserialize 
-| `@serde` 
-| `skip`, `rename`, `flatten`, `default` 
-
-| Hash 
-| `@hash` 
-| `skip` 
-
-| PartialEq/Ord 
-| `@eq`, `@ord` 
-| `skip`
-
-## How It Works
-
-1. **Declaration**: You write `@derive(MacroName)` before a class
-
-2. **Discovery**: Macroforge finds all derive decorators in your code
-
-3. **Expansion**: Each named macro receives the class AST and generates code
-
-4. **Injection**: Generated methods/properties are added to the class
-
-## What Can Be Derived
-
-The derive system works on:
-
-- **Classes**: The primary target for derive macros
-
-- **Interfaces**: Macros generate companion namespace functions
-
-- **Enums**: Macros generate namespace functions for enum values
-
-- **Type aliases**: Both object types and union types are supported
-
-## Built-in vs Custom Macros
-
-Macroforge comes with built-in macros that work out of the box. You can also create custom macros in Rust and use them via the `import macro` statement.
-
-| Built-in 
-| No 
-| Debug, Clone, Default, Hash, Ord, PartialEq, PartialOrd, Serialize, Deserialize 
-
-| Custom 
-| Yes 
-| Any macro from an external package
+    name: string;
 
-## Next Steps
+    /** @debug({ skip: true }) */
+    /** @serde({ skip: true }) */
+    password: string;
 
-- [Explore built-in macros]({base}/docs/builtin-macros)
+    /** @serde({ flatten: true }) */
+    metadata: Record<string, unknown>;
+}
+```  
+**After:**
+```
+import { SerializeContext } from 'macroforge/serde';
 
-- [Create custom macros]({base}/docs/custom-macros)
+class User {
+    id: number;
+
+    name: string;
+
+    password: string;
+
+    metadata: Record<string, unknown>;
+
+    toString(): string {
+        const parts: string[] = [];
+        parts.push('userId: ' + this.id);
+        parts.push('name: ' + this.name);
+        parts.push('metadata: ' + this.metadata);
+        return 'User { ' + parts.join(', ') + ' }';
+    }
+
+    toStringifiedJSON(): string {
+        const ctx = SerializeContext.create();
+        return JSON.stringify(this.__serialize(ctx));
+    }
+
+    toObject(): Record<string, unknown> {
+        const ctx = SerializeContext.create();
+        return this.__serialize(ctx);
+    }
+
+    __serialize(ctx: SerializeContext): Record<string, unknown> {
+        const existingId = ctx.getId(this);
+        if (existingId !== undefined) {
+            return {
+                __ref: existingId
+            };
+        }
+        const __id = ctx.register(this);
+        const result: Record<string, unknown> = {
+            __type: 'User',
+            __id
+        };
+        result['user_id'] = this.id;
+        result['name'] = this.name;
+        {
+            const __flattened = __serializeRecord<string, unknown>(this.metadata, ctx);
+            const { __type: _, __id: __, ...rest } = __flattened as any;
+            Object.assign(result, rest);
+        }
+        return result;
+    }
+}
+``` Syntax rules:
+ - Must be inside a JSDoc comment immediately before the field
+ - Options use object literal syntax: `@attr({ key: value })`
+ - Boolean options: `@attr({ skip: true })`
+ - String options: `@attr({ rename: "newName" })`
+ - Multiple attributes can be on separate lines or combined
+ Common field attributes by macro:
+ | Macro | Attribute | Options |
+| --- | --- | --- |
+| Debug | `@debug` | `skip`, `rename` |
+| Clone | `@clone` | `skip`, `clone_with` |
+| Serialize/Deserialize | `@serde` | `skip`, `rename`, `flatten`, `default` |
+| Hash | `@hash` | `skip` |
+| PartialEq/Ord | `@eq`, `@ord` | `skip` |
+ ## How It Works
+ 1. **Declaration**: You write `@derive(MacroName)` before a class
+ 2. **Discovery**: Macroforge finds all derive decorators in your code
+ 3. **Expansion**: Each named macro receives the class AST and generates code
+ 4. **Injection**: Generated methods/properties are added to the class
+ ## What Can Be Derived
+ The derive system works on:
+ - **Classes**: The primary target for derive macros
+ - **Interfaces**: Macros generate companion namespace functions
+ - **Enums**: Macros generate namespace functions for enum values
+ - **Type aliases**: Both object types and union types are supported
+ ## Built-in vs Custom Macros
+ Macroforge comes with built-in macros that work out of the box. You can also create custom macros in Rust and use them via the `import macro` statement.
+ | Type | Import Required | Examples |
+| --- | --- | --- |
+| Built-in | No | Debug, Clone, Default, Hash, Ord, PartialEq, PartialOrd, Serialize, Deserialize |
+| Custom | Yes | Any macro from an external package |
+ ## Next Steps
+ - [Explore built-in macros](../../docs/builtin-macros)
+ - [Create custom macros](../../docs/custom-macros)

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

@@ -1,85 +1,53 @@
 # How Macros Work
-
-*Macroforge performs compile-time code generation by parsing your TypeScript, expanding macros, and outputting transformed code. This happens before your code runs, resulting in zero runtime overhead.*
-
-## Compile-Time Expansion
-
-Unlike runtime solutions that use reflection or proxies, Macroforge expands macros at compile time:
-
-1. **Parse**: Your TypeScript code is parsed into an AST using SWC
-
-2. **Find**: Macroforge finds `@derive` decorators and their associated items
-
-3. **Expand**: Each macro generates new code based on the class structure
-
-4. **Output**: The transformed TypeScript is written out, ready for normal compilation
-
-<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
-
-## Zero Runtime Overhead
-
-Because code generation happens at compile time, there's no:
-
-- Runtime reflection or metadata
-
-- Proxy objects or wrappers
-
-- Additional dependencies in your bundle
-
-- Performance cost at runtime
-
-The generated code is plain TypeScript that compiles to efficient JavaScript.
-
-## Source Mapping
-
-Macroforge tracks the relationship between your source code and the expanded output. This means:
-
-- Errors in generated code point back to your source
-
-- Debugging works correctly
-
-- IDE features like "go to definition" work as expected
-
-<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
-
-<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
-
-Macroforge integrates at two key points:
-
-### IDE (TypeScript Plugin)
-
-The TypeScript plugin intercepts language server calls to provide:
-
-- Diagnostics that reference your source, not expanded code
-
-- Completions for generated methods
-
-- Hover information showing what macros generate
-
-### Build (Vite Plugin)
-
-The Vite plugin runs macro expansion during the build process:
-
-- Transforms files before they reach the TypeScript compiler
-
-- Generates type declaration files (.d.ts)
-
-- Produces metadata for debugging
-
-## Next Steps
-
-- [Learn about the derive system]({base}/docs/concepts/derive-system)
-
-- [Explore the architecture]({base}/docs/concepts/architecture)
+ *Macroforge performs compile-time code generation by parsing your TypeScript, expanding macros, and outputting transformed code. This happens before your code runs, resulting in zero runtime overhead.*
+ ## Compile-Time Expansion
+ Unlike runtime solutions that use reflection or proxies, Macroforge expands macros at compile time:
+ 1. **Parse**: Your TypeScript code is parsed into an AST using SWC
+ 2. **Find**: Macroforge finds `@derive` decorators and their associated items
+ 3. **Expand**: Each macro generates new code based on the class structure
+ 4. **Output**: The transformed TypeScript is written out, ready for normal compilation
+ **Before:**
+```
+/** @derive(Debug) */
+class User {
+    name: string;
+}
+```  
+**After:**
+```
+class User {
+    name: string;
+
+    toString(): string {
+        const parts: string[] = [];
+        parts.push('name: ' + this.name);
+        return 'User { ' + parts.join(', ') + ' }';
+    }
+}
+``` ## Zero Runtime Overhead
+ Because code generation happens at compile time, there's no:
+ - Runtime reflection or metadata
+ - Proxy objects or wrappers
+ - Additional dependencies in your bundle
+ - Performance cost at runtime
+ The generated code is plain TypeScript that compiles to efficient JavaScript.
+ ## Source Mapping
+ Macroforge tracks the relationship between your source code and the expanded output. This means:
+ - Errors in generated code point back to your source
+ - Debugging works correctly
+ - IDE features like "go to definition" work as expected
+ > with @derive decorators  <div class="font-semibold text-foreground">SWC Parser TypeScript → AST  <div class="font-semibold text-foreground">Macro Expansion Engine Finds @derive decorators, runs macros, generates new AST nodes  <div class="font-semibold text-foreground">Code Generator AST → TypeScript  <div class="font-semibold text-foreground">Expanded TypeScript ready for normal compilation  ## Integration Points
+ Macroforge integrates at two key points:
+ ### IDE (TypeScript Plugin)
+ The TypeScript plugin intercepts language server calls to provide:
+ - Diagnostics that reference your source, not expanded code
+ - Completions for generated methods
+ - Hover information showing what macros generate
+ ### Build (Vite Plugin)
+ The Vite plugin runs macro expansion during the build process:
+ - Transforms files before they reach the TypeScript compiler
+ - Generates type declaration files (.d.ts)
+ - Produces metadata for debugging
+ ## Next Steps
+ - [Learn about the derive system](../docs/concepts/derive-system)
+ - [Explore the architecture](../docs/concepts/architecture)

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

@@ -1,22 +1,13 @@
 # Custom Macros
-
-*Macroforge allows you to create custom derive macros in Rust. Your macros have full access to the class AST and can generate any TypeScript code.*
-
-## Overview
-
-Custom macros are written in Rust and compiled to native Node.js addons. The process involves:
-
-1. Creating a Rust crate with NAPI bindings
-
-2. Defining macro functions with `#[ts_macro_derive]`
-
-3. Using `macroforge_ts_quote` to generate TypeScript code
-
-4. Building and publishing as an npm package
-
-## Quick Example
-
-```rust
+ *Macroforge allows you to create custom derive macros in Rust. Your macros have full access to the class AST and can generate any TypeScript code.*
+ ## Overview
+ Custom macros are written in Rust and compiled to native Node.js addons. The process involves:
+ 1. Creating a Rust crate with NAPI bindings
+ 2. Defining macro functions with `#[ts_macro_derive]`
+ 3. Using `macroforge_ts_quote` to generate TypeScript code
+ 4. Building and publishing as an npm package
+ ## Quick Example
+ ```
 use macroforge_ts::macros::{ts_macro_derive, body};
 use macroforge_ts::ts_syn::{Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input};
 
@@ -45,13 +36,9 @@ pub fn derive_json(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
         )),
     }
 }
-```
-
-## Using Custom Macros
-
-Once your macro package is published, users can import and use it:
-
-```typescript
+``` ## Using Custom Macros
+ Once your macro package is published, users can import and use it:
+ ```
 /** import macro { JSON } from "@my/macros"; */
 
 /** @derive(JSON) */
@@ -67,17 +54,8 @@ class User {
 
 const user = new User("Alice", 30);
 console.log(user.toJSON()); // { name: "Alice", age: 30 }
-```
-
->
-> The `import macro` comment tells Macroforge which package provides the macro.
-
-## Getting Started
-
-Follow these guides to create your own macros:
-
-- [Set up a Rust macro crate]({base}/docs/custom-macros/rust-setup)
-
-- [Learn the #[ts_macro_derive] attribute]({base}/docs/custom-macros/ts-macro-derive)
-
-- [Learn the template syntax]({base}/docs/custom-macros/ts-quote)
+``` > **Note:** The import macro comment tells Macroforge which package provides the macro. ## Getting Started
+ Follow these guides to create your own macros:
+ - [Set up a Rust macro crate](../docs/custom-macros/rust-setup)
+ - [Learn the #[ts_macro_derive] attribute](../docs/custom-macros/ts-macro-derive)
+ - [Learn the template syntax](../docs/custom-macros/ts-quote)

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

@@ -1,32 +1,20 @@
 # Rust Setup
-
-*Create a new Rust crate that will contain your custom macros. This crate compiles to a native Node.js addon.*
-
-## Prerequisites
-
-- Rust toolchain (1.88 or later)
-
-    - Node.js 24 or later
-
-    - NAPI-RS CLI: `cargo install macroforge_ts`
-
-## Create the Project
-
-```bash
+ *Create a new Rust crate that will contain your custom macros. This crate compiles to a native Node.js addon.*
+ ## Prerequisites
+ - Rust toolchain (1.88 or later)
+ - Node.js 24 or later
+ - NAPI-RS CLI: `cargo install macroforge_ts`
+ ## Create the Project
+ ```
 # Create a new directory
 mkdir my-macros
 cd my-macros
 
 # Initialize with NAPI-RS
 napi new --platform --name my-macros
-```
-
-## Configure Cargo.toml
-
-Update your `Cargo.toml` with the required dependencies:
-
-`Cargo.toml`
-```toml
+``` ## Configure Cargo.toml
+ Update your `Cargo.toml` with the required dependencies:
+ ```
 [package]
 name = "my-macros"
 version = "0.1.0"
@@ -46,21 +34,13 @@ napi-build = "2"
 [profile.release]
 lto = true
 strip = true
-```
-
-## Create build.rs
-
-`build.rs`
-```rust
+``` ## Create build.rs
+ ```
 fn main() {
     napi_build::setup();
 }
-```
-
-## Create src/lib.rs
-
-`src/lib.rs`
-```rust
+``` ## Create src/lib.rs
+ ```
 use macroforge_ts::macros::{ts_macro_derive, body};
 use macroforge_ts::ts_syn::{
     Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input,
@@ -91,12 +71,8 @@ pub fn derive_json(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
         )),
     }
 }
-```
-
-## Create package.json
-
-`package.json`
-```json
+``` ## Create package.json
+ ```
 {
   "name": "@my-org/macros",
   "version": "0.1.0",
@@ -121,11 +97,8 @@ pub fn derive_json(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
     "@napi-rs/cli": "^3.0.0-alpha.0"
   }
 }
-```
-
-## Build the Package
-
-```bash
+``` ## Build the Package
+ ```
 # Build the native addon
 npm run build
 
@@ -133,13 +106,7 @@ npm run build
 # - index.js (JavaScript bindings)
 # - index.d.ts (TypeScript types)
 # - *.node (native binary)
-```
-
->
-> For cross-platform builds, use GitHub Actions with the NAPI-RS CI template.
-
-## Next Steps
-
-- <a href="{base}/docs/custom-macros/ts-macro-derive" >Learn the #[ts_macro_derive] attribute</a >
-
-    - <a href="{base}/docs/custom-macros/ts-quote" >Master the template syntax</a >
+```  **Tip For cross-platform builds, use GitHub Actions with the NAPI-RS CI template. ## Next Steps
+ - [Learn the #[ts_macro_derive] attribute](../../docs/custom-macros/ts-macro-derive)
+ - [Master the template syntax](../../docs/custom-macros/ts-quote)
+**