@macroforge/mcp-server 0.1.42 → 0.1.49

package/docs/concepts/derive-system.md

@@ -1,161 +1,214 @@
 # 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 <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@derive</code>.*
- ## Syntax Reference
- Macroforge uses JSDoc comments for all macro annotations. This ensures compatibility with standard TypeScript tooling.
- ### The @derive Statement
- The <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@derive</code> 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 &#123;
+class MyClass {
     value: string;
-&#125;
-```  Syntax rules:
- - Must be inside a JSDoc comment (<code class="shiki-inline"><span class="line"><span style="--shiki-dark:#6A737D;--shiki-light:#6A737D">/** */</code>)
- - Must appear immediately before the class/interface declaration
- - Multiple macros can be comma-separated: <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@<span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">derive<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">(<span style="--shiki-dark:#79B8FF;--shiki-light:#005CC5">A<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">, <span style="--shiki-dark:#79B8FF;--shiki-light:#005CC5">B<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">, <span style="--shiki-dark:#79B8FF;--shiki-light:#005CC5">C<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">)</code>
- - Multiple <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@derive</code> 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 &#123;
+class User {
     name: string;
     email: string;
-&#125;
-```  ### The import macro Statement
- To use macros from external packages, you must declare them with <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#F97583;--shiki-light:#D73A49">import<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E"> macro</code>:
- ```
-/**&nbsp;import&nbsp;macro&nbsp;&#123;&nbsp;MacroName&nbsp;&#125;&nbsp;from&nbsp;"package-name";&nbsp;*/
-``` Syntax rules:
- - Must be inside a JSDoc comment (<code class="shiki-inline"><span class="line"><span style="--shiki-dark:#6A737D;--shiki-light:#6A737D">/** */</code>)
- - Can appear anywhere in the file (typically at the top)
- - Multiple macros can be imported: <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#F97583;--shiki-light:#D73A49">import<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E"> macro { A, B } <span style="--shiki-dark:#F97583;--shiki-light:#D73A49">from<span style="--shiki-dark:#9ECBFF;--shiki-light:#032F62"> "pkg"<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">;</code>
- - Multiple import statements can be used for different packages
- ```
-/**&nbsp;import&nbsp;macro&nbsp;&#123;&nbsp;JSON,&nbsp;Validate&nbsp;&#125;&nbsp;from&nbsp;"@my/macros";&nbsp;*/
-/**&nbsp;import&nbsp;macro&nbsp;&#123;&nbsp;Builder&nbsp;&#125;&nbsp;from&nbsp;"@other/macros";&nbsp;*/
-
-/**&nbsp;@derive(JSON,&nbsp;Validate,&nbsp;Builder)&nbsp;*/
-class&nbsp;User&nbsp;&#123;
-&nbsp;&nbsp;name:&nbsp;string;
-&nbsp;&nbsp;email:&nbsp;string;
-&#125;
-```  **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:
- **<div><div class="flex items-center justify-between gap-2 px-4 py-2 bg-muted rounded-t-lg border border-b-0 border-border"> 
-**Before:**
+}
+```
+
+### 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;
+}
+```
+
+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 &#123;
-    /** @debug(&#123; rename: "userId" &#125;) */
-    /** @serde(&#123; rename: "user_id" &#125;) */
+class User {
+    /** @debug({ rename: "userId" }) */
+    /** @serde({ rename: "user_id" }) */
     id: number;
 
     name: string;
 
-    /** @debug(&#123; skip: true &#125;) */
-    /** @serde(&#123; skip: true &#125;) */
+    /** @debug({ skip: true }) */
+    /** @serde({ skip: true }) */
     password: string;
 
-    metadata: Record&#x3C;string, unknown>;
-&#125;
-``` <div class="flex items-center justify-between gap-2 px-4 py-2 bg-muted rounded-t-lg border border-b-0 border-border"> 
-**After:**
+    metadata: Record<string, unknown>;
+}
+```
+
+After (Generated)
+
 ```
-import &#123; SerializeContext &#125; from 'macroforge/serde';
+import { SerializeContext as __mf_SerializeContext } from 'macroforge/serde';
 
-class User &#123;
+class User {
     id: number;
 
     name: string;
 
     password: string;
 
-    metadata: Record&#x3C;string, unknown>;
+    metadata: Record<string, unknown>;
 
-    static toString(value: User): string &#123;
+    static toString(value: User): string {
         return userToString(value);
-    &#125;
+    }
     /** 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 &#123;
+    static serialize(value: User): string {
         return userSerialize(value);
-    &#125;
+    }
     /** @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&#x3C;string, unknown> &#123;
+    static serializeWithContext(value: User, ctx: __mf_SerializeContext): Record<string, unknown> {
         return userSerializeWithContext(value, ctx);
-    &#125;
-&#125;
+    }
+}
 
-export function userToString(value: User): string &#123;
+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 &#123; ' + parts.join(', ') + ' &#125;';
-&#125;
+    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 &#123;
-    const ctx = SerializeContext.create();
+): string {
+    const ctx = __mf_SerializeContext.create();
     return JSON.stringify(userSerializeWithContext(value, ctx));
-&#125; /** @internal Serializes with an existing context for nested/cyclic object graphs.
+} /** @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&#x3C;string, unknown> &#123;
+    ctx: __mf_SerializeContext
+): Record<string, unknown> {
     const existingId = ctx.getId(value);
-    if (existingId !== undefined) &#123;
-        return &#123; __ref: existingId &#125;;
-    &#125;
+    if (existingId !== undefined) {
+        return { __ref: existingId };
+    }
     const __id = ctx.register(value);
-    const result: Record&#x3C;string, unknown> = &#123; __type: 'User', __id &#125;;
+    const result: Record<string, unknown> = { __type: 'User', __id };
     result['user_id'] = value.id;
     result['name'] = value.name;
     result['metadata'] = value.metadata;
     return result;
-&#125;
-``` Syntax rules:
- - Must be inside a JSDoc comment immediately before the field
- - Options use object literal syntax: <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@<span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">attr<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">({ key: value })</code>
- - Boolean options: <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@<span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">attr<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">({ skip: <span style="--shiki-dark:#79B8FF;--shiki-light:#005CC5">true<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E"> })</code>
- - String options: <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@<span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">attr<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">({ rename: <span style="--shiki-dark:#9ECBFF;--shiki-light:#032F62">"newName"<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E"> })</code>
- - 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 <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@<span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">derive<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">(MacroName)</code> 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 <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#F97583;--shiki-light:#D73A49">import<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E"> macro</code> 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)
+}
+```
+
+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,58 +1,109 @@
 # 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 <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@derive</code> 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
- <div><div class="flex items-center justify-between gap-2 px-4 py-2 bg-muted rounded-t-lg border border-b-0 border-border"> 
-**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 &#123;
+class User {
     name: string;
-&#125;
-``` <div class="flex items-center justify-between gap-2 px-4 py-2 bg-muted rounded-t-lg border border-b-0 border-border"> 
-**After:**
+}
 ```
-class User &#123;
+
+After (Generated)
+
+```
+class User {
     name: string;
 
-    static toString(value: User): string &#123;
+    static toString(value: User): string {
         return userToString(value);
-    &#125;
-&#125;
+    }
+}
 
-export function userToString(value: User): string &#123;
+export function userToString(value: User): string {
     const parts: string[] = [];
     parts.push('name: ' + value.name);
-    return 'User &#123; ' + parts.join(', ') + ' &#125;';
-&#125;
-``` ## 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)
+    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
+
+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 <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">#[ts_macro_derive]</code>
- 3. Using <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">macroforge_ts_quote</code> to generate TypeScript code
- 4. Building and publishing as an npm package
- ## Quick Example
- ```
-use&nbsp;macroforge_ts::macros::&#123;ts_macro_derive,&nbsp;body&#125;;
-use&nbsp;macroforge_ts::ts_syn::&#123;Data,&nbsp;DeriveInput,&nbsp;MacroforgeError,&nbsp;TsStream,&nbsp;parse_ts_macro_input&#125;;
+
+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(
-&nbsp;&nbsp;&nbsp;&nbsp;JSON,
-&nbsp;&nbsp;&nbsp;&nbsp;description&nbsp;=&nbsp;"Generates&nbsp;toJSON()&nbsp;returning&nbsp;a&nbsp;plain&nbsp;object"
+    JSON,
+    description = "Generates toJSON() returning a plain object"
 )]
-pub&nbsp;fn&nbsp;derive_json(mut&nbsp;input:&nbsp;TsStream)&nbsp;->&nbsp;Result&#x3C;TsStream,&nbsp;MacroforgeError>&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;let&nbsp;input&nbsp;=&nbsp;parse_ts_macro_input!(input&nbsp;as&nbsp;DeriveInput);
-
-&nbsp;&nbsp;&nbsp;&nbsp;match&nbsp;&#x26;input.data&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Data::Class(class)&nbsp;=>&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Ok(body!&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;toJSON():&nbsp;Record&#x3C;string,&nbsp;unknown>&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#123;#for&nbsp;field&nbsp;in&nbsp;class.field_names()&#125;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;@&#123;field&#125;:&nbsp;this.@&#123;field&#125;,
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#123;/for&#125;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#125;;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#125;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#125;)
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#125;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;_&nbsp;=>&nbsp;Err(MacroforgeError::new(
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;input.decorator_span(),
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"@derive(JSON)&nbsp;only&nbsp;works&nbsp;on&nbsp;classes",
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;)),
-&nbsp;&nbsp;&nbsp;&nbsp;&#125;
-&#125;
-``` ## Using Custom Macros
- Once your macro package is published, users can import and use it:
- ```
-/**&nbsp;import&nbsp;macro&nbsp;&#123;&nbsp;JSON&nbsp;&#125;&nbsp;from&nbsp;"@my/macros";&nbsp;*/
-
-/**&nbsp;@derive(JSON)&nbsp;*/
-class&nbsp;User&nbsp;&#123;
-&nbsp;&nbsp;name:&nbsp;string;
-&nbsp;&nbsp;age:&nbsp;number;
-
-&nbsp;&nbsp;constructor(name:&nbsp;string,&nbsp;age:&nbsp;number)&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;this.name&nbsp;=&nbsp;name;
-&nbsp;&nbsp;&nbsp;&nbsp;this.age&nbsp;=&nbsp;age;
-&nbsp;&nbsp;&#125;
-&#125;
-
-const&nbsp;user&nbsp;=&nbsp;new&nbsp;User("Alice",&nbsp;30);
-console.log(user.toJSON());&nbsp;//&nbsp;&#123;&nbsp;name:&nbsp;"Alice",&nbsp;age:&nbsp;30&nbsp;&#125;
-``` > **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)