@macroforge/mcp-server 0.1.40 → 0.1.49

package/docs/concepts/derive-system.md

@@ -1,48 +1,85 @@
 # 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:
- **Source:**
+
+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
+
+TypeScript
+
 ```
 /** @derive(Debug) */
 class MyClass {
-  value: string;
+    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
- **Source:**
+```
+
+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
+
+TypeScript
+
 ```
 /** @derive(Debug, Clone) */
 class User {
-  name: string;
-  email: string;
+    name: string;
+    email: string;
+}
+```
+
+### The import macro Statement
+
+To use macros from external packages, you must declare them with `import macro`:
+
+TypeScript
+
+```
+/** 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 { A, B } from "pkg";`
+*   Multiple import statements can be used for different packages
+
+TypeScript
+
+```
+/** import macro { JSON, Validate } from "@my/macros"; */
+/** import macro { Builder } from "@other/macros"; */
+
+/** @derive(JSON, Validate, Builder) */
+class User {
+  name: string;
+  email: string;
 }
-```  ### 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 { 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"; */
-
-/** @derive(JSON, Validate, Builder) */
-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:**
+```
+
+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 (Your Code)
+
 ```
 /** @derive(Debug, Serialize) */
 class User {
@@ -56,85 +93,122 @@ class User {
     /** @serde({ skip: true }) */
     password: string;
 
-    /** @serde({ flatten: true }) */
     metadata: Record<string, unknown>;
 }
-```  
-**After:**
 ```
-import { SerializeContext } from "macroforge/serde";
+
+After (Generated)
+
+```
+import { SerializeContext as __mf_SerializeContext } from 'macroforge/serde';
 
 class User {
-  
-  
-  id: number;
+    id: number;
 
-  name: string;
+    name: string;
 
-  
-  
-  password: string;
+    password: string;
 
-  
-  metadata: Record<string, unknown>;
+    metadata: Record<string, unknown>;
 
-  static toString(value: User): string {
-    return userToString(value);
-}
-/** Serializes a value to a JSON string.
+    static toString(value: User): string {
+        return userToString(value);
+    }
+    /** Serializes a value to a JSON string.
 @param value - The value to serialize
 @returns JSON string representation with cycle detection metadata  */
 
-  static serialize(value: User): string {
-    return userSerialize(value);
-}
-/** @internal Serializes with an existing context for nested/cyclic object graphs.
+    static serialize(value: User): string {
+        return userSerialize(value);
+    }
+    /** @internal Serializes with an existing context for nested/cyclic object graphs.
 @param value - The value to serialize
 @param ctx - The serialization context  */
 
-  static serializeWithContext(value: User, ctx: SerializeContext): Record<string, unknown> {
-    return userSerializeWithContext(value, ctx);
-}
+    static serializeWithContext(value: User, ctx: __mf_SerializeContext): Record<string, unknown> {
+        return userSerializeWithContext(value, ctx);
+    }
 }
 
-export function userToString(value: User): string {const parts: string[]= []; parts.push("userId: " + value.id); parts.push("name: " + value.name); parts.push("metadata: " + value.metadata); return "User { " + parts.join(", " )+ " }" ; }
+export function userToString(value: User): string {
+    const parts: string[] = [];
+    parts.push('userId: ' + value.id);
+    parts.push('name: ' + value.name);
+    parts.push('metadata: ' + value.metadata);
+    return 'User { ' + parts.join(', ') + ' }';
+}
 
 /** Serializes a value to a JSON string.
 @param value - The value to serialize
-@returns JSON string representation with cycle detection metadata */export function userSerialize(value: User): string {const ctx = SerializeContext.create(); return JSON.stringify(userSerializeWithContext(value, ctx));}/** @internal Serializes with an existing context for nested/cyclic object graphs.
+@returns JSON string representation with cycle detection metadata */ export function userSerialize(
+    value: User
+): string {
+    const ctx = __mf_SerializeContext.create();
+    return JSON.stringify(userSerializeWithContext(value, ctx));
+} /** @internal Serializes with an existing context for nested/cyclic object graphs.
 @param value - The value to serialize
-@param ctx - The serialization context */export function userSerializeWithContext(value: User, ctx: SerializeContext): Record<string, unknown>{const existingId = ctx.getId(value); if(existingId!== undefined){return {__ref: existingId};}const __id = ctx.register(value); const result: Record<string, unknown>= {__type: "User" , __id,}; result["user_id" ]= value.id; result["name" ]= value.name; {const __flattened = record<string, unknown>SerializeWithContext(value.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)
+@param ctx - The serialization context */
+export function userSerializeWithContext(
+    value: User,
+    ctx: __mf_SerializeContext
+): Record<string, unknown> {
+    const existingId = ctx.getId(value);
+    if (existingId !== undefined) {
+        return { __ref: existingId };
+    }
+    const __id = ctx.register(value);
+    const result: Record<string, unknown> = { __type: 'User', __id };
+    result['user_id'] = value.id;
+    result['name'] = value.name;
+    result['metadata'] = value.metadata;
+    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,19 +1,27 @@
 # 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
- **Before:**
+
+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 (Your Code)
+
 ```
 /** @derive(Debug) */
 class User {
     name: string;
 }
-```  
-**After:**
+```
+
+After (Generated)
+
 ```
 class User {
     name: string;
@@ -28,30 +36,74 @@ export function userToString(value: User): string {
     parts.push('name: ' + value.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)
+```
+
+## 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
+
+Error positioning
+
+The TypeScript plugin uses source mapping to show errors at the `@derive` decorator position, not in the generated code.
+
+## Execution Flow
+
+Your Source Code
+
+with @derive decorators
+
+SWC Parser
+
+TypeScript → AST
+
+Macro Expansion Engine
+
+Finds @derive decorators, runs macros, generates new AST nodes
+
+Code Generator
+
+AST → TypeScript
+
+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,61 +1,83 @@
 # 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
- ```
-use macroforge_ts::macros::{ts_macro_derive, body};
-use macroforge_ts::ts_syn::{Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input};
+
+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
+
+```
+use macroforge_ts::macros::{ts_macro_derive, body};
+use macroforge_ts::ts_syn::{Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input};
 
 #[ts_macro_derive(
-    JSON,
-    description = "Generates toJSON() returning a plain object"
+    JSON,
+    description = "Generates toJSON() returning a plain object"
 )]
-pub fn derive_json(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
-    let input = parse_ts_macro_input!(input as DeriveInput);
-
-    match &input.data {
-        Data::Class(class) => {
-            Ok(body! {
-                toJSON(): Record<string, unknown> {
-                    return {
-                        {#for field in class.field_names()}
-                            @{field}: this.@{field},
-                        {/for}
-                    };
-                }
-            })
-        }
-        _ => Err(MacroforgeError::new(
-            input.decorator_span(),
-            "@derive(JSON) only works on classes",
-        )),
-    }
-}
-``` ## Using Custom Macros
- Once your macro package is published, users can import and use it:
- ```
-/** import macro { JSON } from "@my/macros"; */
-
-/** @derive(JSON) */
-class User {
-  name: string;
-  age: number;
-
-  constructor(name: string, age: number) {
-    this.name = name;
-    this.age = age;
-  }
-}
-
-const user = new User("Alice", 30);
-console.log(user.toJSON()); // { name: "Alice", age: 30 }
-``` > **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)
+pub fn derive_json(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
+    let input = parse_ts_macro_input!(input as DeriveInput);
+
+    match &input.data {
+        Data::Class(class) => {
+            Ok(body! {
+                toJSON(): Record<string, unknown> {
+                    return {
+                        {#for field in class.field_names()}
+                            @{field}: this.@{field},
+                        {/for}
+                    };
+                }
+            })
+        }
+        _ => Err(MacroforgeError::new(
+            input.decorator_span(),
+            "@derive(JSON) only works on classes",
+        )),
+    }
+}
+```
+
+## Using Custom Macros
+
+Once your macro package is published, users can import and use it:
+
+TypeScript
+
+```
+/** import macro { JSON } from "@my/macros"; */
+
+/** @derive(JSON) */
+class User {
+  name: string;
+  age: number;
+
+  constructor(name: string, age: number) {
+    this.name = name;
+    this.age = age;
+  }
+}
+
+const user = new User("Alice", 30);
+console.log(user.toJSON()); // { name: "Alice", age: 30 }
+```
+
+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)