@macroforge/mcp-server 0.1.39 → 0.1.42

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

@@ -3,122 +3,122 @@
  ## Overview
  | Macro | Generates | Description |
 | --- | --- | --- |
-| [`Debug`](../docs/builtin-macros/debug) | `toString(): string` | Human-readable string representation |
-| [`Clone`](../docs/builtin-macros/clone) | `clone(): T` | Creates a deep copy of the object |
-| [`Default`](../docs/builtin-macros/default) | `static default(): T` | Creates an instance with default values |
-| [`Hash`](../docs/builtin-macros/hash) | `hashCode(): number` | Generates a hash code for the object |
-| [`PartialEq`](../docs/builtin-macros/partial-eq) | `equals(other: T): boolean` | Value equality comparison |
-| [`Ord`](../docs/builtin-macros/ord) | `compare(other: T): number` | Total ordering comparison (-1, 0, 1) |
-| [`PartialOrd`](../docs/builtin-macros/partial-ord) | `partialCompare(other: T): number | null` | Partial ordering comparison |
-| [`Serialize`](../docs/builtin-macros/serialize) | `toJSON(): Record<string, unknown>` | JSON serialization with type handling |
-| [`Deserialize`](../docs/builtin-macros/deserialize) | `static fromJSON(data: unknown): T` | JSON deserialization with validation |
+| [Debug](../docs/builtin-macros/debug) | toString(): string | Human-readable string representation |
+| [Clone](../docs/builtin-macros/clone) | clone(): T | Creates a deep copy of the object |
+| [Default](../docs/builtin-macros/default) | static default(): T | Creates an instance with default values |
+| [Hash](../docs/builtin-macros/hash) | hashCode(): number | Generates a hash code for the object |
+| [PartialEq](../docs/builtin-macros/partial-eq) | equals(other: T): boolean | Value equality comparison |
+| [Ord](../docs/builtin-macros/ord) | compare(other: T): number | Total ordering comparison (-1, 0, 1) |
+| [PartialOrd](../docs/builtin-macros/partial-ord) | partialCompare(other: T): number | null | Partial ordering comparison |
+| [Serialize](../docs/builtin-macros/serialize) | toJSON(): Record<string, unknown> | JSON serialization with type handling |
+| [Deserialize](../docs/builtin-macros/deserialize) | static fromJSON(data: unknown): T | JSON deserialization with validation |
  ## Using Built-in Macros
- Built-in macros don't require imports. Just use them with `@derive`:
+ Built-in macros don't require imports. Just use them with <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@derive</code>:
  ```
-/** @derive(Debug, Clone, PartialEq) */
-class User &#123;
-  name: string;
-  age: number;
+/**&nbsp;@derive(Debug,&nbsp;Clone,&nbsp;PartialEq)&nbsp;*/
+class&nbsp;User&nbsp;&#123;
+&nbsp;&nbsp;name:&nbsp;string;
+&nbsp;&nbsp;age:&nbsp;number;
 
-  constructor(name: string, age: number) &#123;
-    this.name = name;
-    this.age = age;
-  &#125;
+&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;
 ``` ## Interface Support
- All built-in macros work with interfaces. For interfaces, methods are generated as functions in a namespace with the same name, using `self` as the first parameter:
+ All built-in macros work with interfaces. For interfaces, methods are generated as functions in a namespace with the same name, using <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">self</code> as the first parameter:
  ```
-/** @derive(Debug, Clone, PartialEq) */
-interface Point &#123;
-  x: number;
-  y: number;
+/**&nbsp;@derive(Debug,&nbsp;Clone,&nbsp;PartialEq)&nbsp;*/
+interface&nbsp;Point&nbsp;&#123;
+&nbsp;&nbsp;x:&nbsp;number;
+&nbsp;&nbsp;y:&nbsp;number;
 &#125;
 
-// Generated namespace:
-// namespace Point &#123;
-//   export function toString(self: Point): string &#123; ... &#125;
-//   export function clone(self: Point): Point &#123; ... &#125;
-//   export function equals(self: Point, other: Point): boolean &#123; ... &#125;
-//   export function hashCode(self: Point): number &#123; ... &#125;
-// &#125;
+//&nbsp;Generated&nbsp;namespace:
+//&nbsp;namespace&nbsp;Point&nbsp;&#123;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;toString(self:&nbsp;Point):&nbsp;string&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;clone(self:&nbsp;Point):&nbsp;Point&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;equals(self:&nbsp;Point,&nbsp;other:&nbsp;Point):&nbsp;boolean&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;hashCode(self:&nbsp;Point):&nbsp;number&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&#125;
 
-const point: Point = &#123; x: 10, y: 20 &#125;;
+const&nbsp;point:&nbsp;Point&nbsp;=&nbsp;&#123;&nbsp;x:&nbsp;10,&nbsp;y:&nbsp;20&nbsp;&#125;;
 
-// Use the namespace functions
-console.log(Point.toString(point));     // "Point &#123; x: 10, y: 20 &#125;"
-const copy = Point.clone(point);        // &#123; x: 10, y: 20 &#125;
-console.log(Point.equals(point, copy)); // true
+//&nbsp;Use&nbsp;the&nbsp;namespace&nbsp;functions
+console.log(Point.toString(point));&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;"Point&nbsp;&#123;&nbsp;x:&nbsp;10,&nbsp;y:&nbsp;20&nbsp;&#125;"
+const&nbsp;copy&nbsp;=&nbsp;Point.clone(point);&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;&#123;&nbsp;x:&nbsp;10,&nbsp;y:&nbsp;20&nbsp;&#125;
+console.log(Point.equals(point,&nbsp;copy));&nbsp;//&nbsp;true
 ``` ## Enum Support
  All built-in macros work with enums. For enums, methods are generated as functions in a namespace with the same name:
  ```
-/** @derive(Debug, Clone, PartialEq, Serialize, Deserialize) */
-enum Status &#123;
-  Active = "active",
-  Inactive = "inactive",
-  Pending = "pending",
+/**&nbsp;@derive(Debug,&nbsp;Clone,&nbsp;PartialEq,&nbsp;Serialize,&nbsp;Deserialize)&nbsp;*/
+enum&nbsp;Status&nbsp;&#123;
+&nbsp;&nbsp;Active&nbsp;=&nbsp;"active",
+&nbsp;&nbsp;Inactive&nbsp;=&nbsp;"inactive",
+&nbsp;&nbsp;Pending&nbsp;=&nbsp;"pending",
 &#125;
 
-// Generated namespace:
-// namespace Status &#123;
-//   export function toString(value: Status): string &#123; ... &#125;
-//   export function clone(value: Status): Status &#123; ... &#125;
-//   export function equals(a: Status, b: Status): boolean &#123; ... &#125;
-//   export function hashCode(value: Status): number &#123; ... &#125;
-//   export function toJSON(value: Status): string | number &#123; ... &#125;
-//   export function fromJSON(data: unknown): Status &#123; ... &#125;
-// &#125;
+//&nbsp;Generated&nbsp;namespace:
+//&nbsp;namespace&nbsp;Status&nbsp;&#123;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;toString(value:&nbsp;Status):&nbsp;string&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;clone(value:&nbsp;Status):&nbsp;Status&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;equals(a:&nbsp;Status,&nbsp;b:&nbsp;Status):&nbsp;boolean&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;hashCode(value:&nbsp;Status):&nbsp;number&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;toJSON(value:&nbsp;Status):&nbsp;string&nbsp;|&nbsp;number&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;fromJSON(data:&nbsp;unknown):&nbsp;Status&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&#125;
 
-// Use the namespace functions
-console.log(Status.toString(Status.Active));     // "Status.Active"
-console.log(Status.equals(Status.Active, Status.Active)); // true
-const json = Status.toJSON(Status.Pending);      // "pending"
-const parsed = Status.fromJSON("active");        // Status.Active
+//&nbsp;Use&nbsp;the&nbsp;namespace&nbsp;functions
+console.log(Status.toString(Status.Active));&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;"Status.Active"
+console.log(Status.equals(Status.Active,&nbsp;Status.Active));&nbsp;//&nbsp;true
+const&nbsp;json&nbsp;=&nbsp;Status.toJSON(Status.Pending);&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;"pending"
+const&nbsp;parsed&nbsp;=&nbsp;Status.fromJSON("active");&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;Status.Active
 ``` ## Type Alias Support
  All built-in macros work with type aliases. For object type aliases, field-aware methods are generated in a namespace:
  ```
-/** @derive(Debug, Clone, PartialEq, Serialize, Deserialize) */
-type Point = &#123;
-  x: number;
-  y: number;
+/**&nbsp;@derive(Debug,&nbsp;Clone,&nbsp;PartialEq,&nbsp;Serialize,&nbsp;Deserialize)&nbsp;*/
+type&nbsp;Point&nbsp;=&nbsp;&#123;
+&nbsp;&nbsp;x:&nbsp;number;
+&nbsp;&nbsp;y:&nbsp;number;
 &#125;;
 
-// Generated namespace:
-// namespace Point &#123;
-//   export function toString(value: Point): string &#123; ... &#125;
-//   export function clone(value: Point): Point &#123; ... &#125;
-//   export function equals(a: Point, b: Point): boolean &#123; ... &#125;
-//   export function hashCode(value: Point): number &#123; ... &#125;
-//   export function toJSON(value: Point): Record&#x3C;string, unknown> &#123; ... &#125;
-//   export function fromJSON(data: unknown): Point &#123; ... &#125;
-// &#125;
+//&nbsp;Generated&nbsp;namespace:
+//&nbsp;namespace&nbsp;Point&nbsp;&#123;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;toString(value:&nbsp;Point):&nbsp;string&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;clone(value:&nbsp;Point):&nbsp;Point&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;equals(a:&nbsp;Point,&nbsp;b:&nbsp;Point):&nbsp;boolean&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;hashCode(value:&nbsp;Point):&nbsp;number&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;toJSON(value:&nbsp;Point):&nbsp;Record&#x3C;string,&nbsp;unknown>&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&nbsp;&nbsp;export&nbsp;function&nbsp;fromJSON(data:&nbsp;unknown):&nbsp;Point&nbsp;&#123;&nbsp;...&nbsp;&#125;
+//&nbsp;&#125;
 
-const point: Point = &#123; x: 10, y: 20 &#125;;
-console.log(Point.toString(point));     // "Point &#123; x: 10, y: 20 &#125;"
-const copy = Point.clone(point);        // &#123; x: 10, y: 20 &#125;
-console.log(Point.equals(point, copy)); // true
+const&nbsp;point:&nbsp;Point&nbsp;=&nbsp;&#123;&nbsp;x:&nbsp;10,&nbsp;y:&nbsp;20&nbsp;&#125;;
+console.log(Point.toString(point));&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;"Point&nbsp;&#123;&nbsp;x:&nbsp;10,&nbsp;y:&nbsp;20&nbsp;&#125;"
+const&nbsp;copy&nbsp;=&nbsp;Point.clone(point);&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;&#123;&nbsp;x:&nbsp;10,&nbsp;y:&nbsp;20&nbsp;&#125;
+console.log(Point.equals(point,&nbsp;copy));&nbsp;//&nbsp;true
 ``` Union type aliases also work, using JSON-based implementations:
  ```
-/** @derive(Debug, PartialEq) */
-type ApiStatus = "loading" | "success" | "error";
+/**&nbsp;@derive(Debug,&nbsp;PartialEq)&nbsp;*/
+type&nbsp;ApiStatus&nbsp;=&nbsp;"loading"&nbsp;|&nbsp;"success"&nbsp;|&nbsp;"error";
 
-const status: ApiStatus = "success";
-console.log(ApiStatus.toString(status)); // "ApiStatus(\\"success\\")"
-console.log(ApiStatus.equals("success", "success")); // true
+const&nbsp;status:&nbsp;ApiStatus&nbsp;=&nbsp;"success";
+console.log(ApiStatus.toString(status));&nbsp;//&nbsp;"ApiStatus(\\"success\\")"
+console.log(ApiStatus.equals("success",&nbsp;"success"));&nbsp;//&nbsp;true
 ``` ## Combining Macros
  All macros can be used together. They don't conflict and each generates independent methods:
  ```
-const user = new User("Alice", 30);
+const&nbsp;user&nbsp;=&nbsp;new&nbsp;User("Alice",&nbsp;30);
 
-// Debug
+//&nbsp;Debug
 console.log(user.toString());
-// "User &#123; name: Alice, age: 30 &#125;"
+//&nbsp;"User&nbsp;&#123;&nbsp;name:&nbsp;Alice,&nbsp;age:&nbsp;30&nbsp;&#125;"
 
-// Clone
-const copy = user.clone();
-console.log(copy.name); // "Alice"
+//&nbsp;Clone
+const&nbsp;copy&nbsp;=&nbsp;user.clone();
+console.log(copy.name);&nbsp;//&nbsp;"Alice"
 
-// Eq
-console.log(user.equals(copy)); // true
+//&nbsp;Eq
+console.log(user.equals(copy));&nbsp;//&nbsp;true
 ``` ## Detailed Documentation
  Each macro has its own options and behaviors:
  - [**Debug**](../docs/builtin-macros/debug) - Customizable field renaming and skipping

package/docs/builtin-macros/partial-ord.md

@@ -70,32 +70,30 @@ class Temperature {
 ```
 
 ```typescript after
-import { Option } from 'macroforge/utils';
-
 class Temperature {
     value: number | null;
     unit: string;
 
-    static compareTo(a: Temperature, b: Temperature): Option<number> {
+    static compareTo(a: Temperature, b: Temperature): number | null {
         return temperaturePartialCompare(a, b);
     }
 }
 
-export function temperaturePartialCompare(a: Temperature, b: Temperature): Option<number> {
-    if (a === b) return Option.some(0);
+export function temperaturePartialCompare(a: Temperature, b: Temperature): number | null {
+    if (a === b) return 0;
     const cmp0 = (() => {
         if (typeof (a.value as any)?.compareTo === 'function') {
             const optResult = (a.value as any).compareTo(b.value);
-            return Option.isNone(optResult) ? null : optResult.value;
+            return optResult === null ? null : optResult;
         }
         return a.value === b.value ? 0 : null;
     })();
-    if (cmp0 === null) return Option.none();
-    if (cmp0 !== 0) return Option.some(cmp0);
+    if (cmp0 === null) return null;
+    if (cmp0 !== 0) return cmp0;
     const cmp1 = a.unit.localeCompare(b.unit);
-    if (cmp1 === null) return Option.none();
-    if (cmp1 !== 0) return Option.some(cmp1);
-    return Option.some(0);
+    if (cmp1 === null) return null;
+    if (cmp1 !== 0) return cmp1;
+    return 0;
 }
 ```
 
@@ -106,26 +104,26 @@ class Temperature {
     value: number | null;
     unit: string;
 
-    static compareTo(a: Temperature, b: Temperature): Option<number> {
+    static compareTo(a: Temperature, b: Temperature): number | null {
         return temperaturePartialCompare(a, b);
     }
 }
 
-export function temperaturePartialCompare(a: Temperature, b: Temperature): Option<number> {
-    if (a === b) return Option.some(0);
+export function temperaturePartialCompare(a: Temperature, b: Temperature): number | null {
+    if (a === b) return 0;
     const cmp0 = (() => {
         if (typeof (a.value as any)?.compareTo === 'function') {
             const optResult = (a.value as any).compareTo(b.value);
-            return Option.isNone(optResult) ? null : optResult.value;
+            return optResult === null ? null : optResult;
         }
         return a.value === b.value ? 0 : null;
     })();
-    if (cmp0 === null) return Option.none();
-    if (cmp0 !== 0) return Option.some(cmp0);
+    if (cmp0 === null) return null;
+    if (cmp0 !== 0) return cmp0;
     const cmp1 = a.unit.localeCompare(b.unit);
-    if (cmp1 === null) return Option.none();
-    if (cmp1 !== 0) return Option.some(cmp1);
-    return Option.some(0);
+    if (cmp1 === null) return null;
+    if (cmp1 !== 0) return cmp1;
+    return 0;
 }
 ```
 

package/docs/concepts/architecture.md

@@ -13,37 +13,37 @@
  - Parsing utilities for macro input
  - Derive input structures (class fields, decorators, etc.)
  ### macroforge_ts_quote
- Template-based code generation similar to Rust's `quote!`:
- - `ts_template!` - Generate TypeScript code from templates
- - `body!` - Generate class body members
- - Control flow: `{#for}`, `{#if}`, `{$let}`
+ Template-based code generation similar to Rust's <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">quote!</code>:
+ - <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">ts_template!</code> - Generate TypeScript code from templates
+ - <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">body!</code> - Generate class body members
+ - Control flow: <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">{<span style="--shiki-dark:#9ECBFF;--shiki-light:#032F62">"{#for}"<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">}</code>, <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">{<span style="--shiki-dark:#9ECBFF;--shiki-light:#032F62">"{#if}"<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">}</code>, <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">{<span style="--shiki-dark:#9ECBFF;--shiki-light:#032F62">"{$let}"<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">}</code>
  ### macroforge_ts_macros
  The procedural macro attribute for defining derive macros:
- - `#[ts_macro_derive(Name)]` attribute
+ - <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">#[<span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">ts_macro_derive<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">(Name)]</code> attribute
  - Automatic registration with the macro system
  - Error handling and span tracking
  ### NAPI-RS Bindings
  Bridges Rust and Node.js:
- - Exposes `expandSync`, `transformSync`, etc.
- - Provides the `NativePlugin` class for caching
+ - Exposes <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">expandSync</code>, <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">transformSync</code>, etc.
+ - Provides the <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">NativePlugin</code> class for caching
  - Handles data marshaling between Rust and JavaScript
  ## Data Flow
  <div class="w-full max-w-md border border-border rounded-lg bg-card p-4 text-center shadow-sm"><div class="font-semibold text-foreground">1. Source Code TypeScript with @derive  <div class="font-semibold text-foreground">2. NAPI-RS receives JavaScript string  <div class="font-semibold text-foreground">3. SWC Parser parses to AST  <div class="font-semibold text-foreground">4. Macro Expander finds @derive decorators  <div class="font-semibold text-foreground">5. For Each Macro extract data, run macro, generate AST nodes  <div class="font-semibold text-foreground">6. Merge generated nodes into AST  <div class="font-semibold text-foreground">7. SWC Codegen generates source code  <div class="font-semibold text-foreground">8. Return to JavaScript with source mapping  ## Performance Characteristics
  - **Thread-safe**: Each expansion runs in an isolated thread with a 32MB stack
- - **Caching**: `NativePlugin` caches results by file version
+ - **Caching**: <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">NativePlugin</code> caches results by file version
  - **Binary search**: Position mapping uses O(log n) lookups
  - **Zero-copy**: SWC's arena allocator minimizes allocations
  ## Re-exported Crates
- For custom macro development, `macroforge_ts` re-exports everything you need:
+ For custom macro development, <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">macroforge_ts</code> re-exports everything you need:
  ```
-// Convenient re-exports for macro development
-use macroforge_ts::macros::&#123;ts_macro_derive, body, ts_template, above, below, signature&#125;;
-use macroforge_ts::ts_syn::&#123;Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input&#125;;
+//&nbsp;Convenient&nbsp;re-exports&nbsp;for&nbsp;macro&nbsp;development
+use&nbsp;macroforge_ts::macros::&#123;ts_macro_derive,&nbsp;body,&nbsp;ts_template,&nbsp;above,&nbsp;below,&nbsp;signature&#125;;
+use&nbsp;macroforge_ts::ts_syn::&#123;Data,&nbsp;DeriveInput,&nbsp;MacroforgeError,&nbsp;TsStream,&nbsp;parse_ts_macro_input&#125;;
 
-// Also available: raw crate access and SWC modules
-use macroforge_ts::swc_core;
-use macroforge_ts::swc_common;
-use macroforge_ts::swc_ecma_ast;
+//&nbsp;Also&nbsp;available:&nbsp;raw&nbsp;crate&nbsp;access&nbsp;and&nbsp;SWC&nbsp;modules
+use&nbsp;macroforge_ts::swc_core;
+use&nbsp;macroforge_ts::swc_common;
+use&nbsp;macroforge_ts::swc_ecma_ast;
 ``` ## Next Steps
  - [Write custom macros](../../docs/custom-macros)
  - [Explore the API reference](../../docs/api)

package/docs/concepts/derive-system.md

@@ -1,125 +1,146 @@
 # 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`.*
+ *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 `@derive` decorator triggers macro expansion on a class or interface:
+ 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:**
 ```
 /** @derive(Debug) */
-class MyClass {
-  value: string;
-}
+class MyClass &#123;
+    value: string;
+&#125;
 ```  Syntax rules:
- - Must be inside a JSDoc comment (`/** */`)
+ - 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: `@derive(A, B, C)`
- - Multiple `@derive` statements can be stacked
+ - 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:**
 ```
 /** @derive(Debug, Clone) */
-class User {
-  name: string;
-  email: string;
-}
+class User &#123;
+    name: string;
+    email: string;
+&#125;
 ```  ### The import macro Statement
- To use macros from external packages, you must declare them with `import macro`:
+ 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>:
  ```
-/** import macro &#123; MacroName &#125; from "package-name"; */
+/**&nbsp;import&nbsp;macro&nbsp;&#123;&nbsp;MacroName&nbsp;&#125;&nbsp;from&nbsp;"package-name";&nbsp;*/
 ``` Syntax rules:
- - Must be inside a JSDoc comment (`/** */`)
+ - 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: `import macro { A, B } from "pkg";`
+ - 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
  ```
-/** import macro &#123; JSON, Validate &#125; from "@my/macros"; */
-/** import macro &#123; Builder &#125; from "@other/macros"; */
+/**&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;*/
 
-/** @derive(JSON, Validate, Builder) */
-class User &#123;
-  name: string;
-  email: string;
+/**&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:
- ****Before:**
+ **<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:**
 ```
 /** @derive(Debug, Serialize) */
-class User {
-    /** @debug({ rename: "userId" }) */
-    /** @serde({ rename: "user_id" }) */
+class User &#123;
+    /** @debug(&#123; rename: "userId" &#125;) */
+    /** @serde(&#123; rename: "user_id" &#125;) */
     id: number;
 
     name: string;
 
-    /** @debug({ skip: true }) */
-    /** @serde({ skip: true }) */
+    /** @debug(&#123; skip: true &#125;) */
+    /** @serde(&#123; skip: true &#125;) */
     password: string;
 
-    /** @serde({ flatten: true }) */
-    metadata: Record<string, unknown>;
-}
-```  
+    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:**
 ```
-import { SerializeContext } from "macroforge/serde";
+import &#123; SerializeContext &#125; from 'macroforge/serde';
 
-class User {
-  
-  
-  id: number;
+class User &#123;
+    id: number;
 
-  name: string;
+    name: string;
 
-  
-  
-  password: string;
+    password: string;
 
-  
-  metadata: Record<string, unknown>;
+    metadata: Record&#x3C;string, unknown>;
 
-  static toString(value: User): string {
-    return userToString(value);
-}
-/** Serializes a value to a JSON string.
+    static toString(value: User): string &#123;
+        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 {
-    return userSerialize(value);
-}
-/** @internal Serializes with an existing context for nested/cyclic object graphs.
+    static serialize(value: User): string &#123;
+        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<string, unknown> {
-    return userSerializeWithContext(value, ctx);
-}
-}
+    static serializeWithContext(value: User, ctx: SerializeContext): Record&#x3C;string, unknown> &#123;
+        return userSerializeWithContext(value, ctx);
+    &#125;
+&#125;
 
-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 &#123;
+    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;
 
 /** 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 &#123;
+    const ctx = SerializeContext.create();
+    return JSON.stringify(userSerializeWithContext(value, ctx));
+&#125; /** @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;}
+@param ctx - The serialization context */
+export function userSerializeWithContext(
+    value: User,
+    ctx: SerializeContext
+): Record&#x3C;string, unknown> &#123;
+    const existingId = ctx.getId(value);
+    if (existingId !== undefined) &#123;
+        return &#123; __ref: existingId &#125;;
+    &#125;
+    const __id = ctx.register(value);
+    const result: Record&#x3C;string, unknown> = &#123; __type: 'User', __id &#125;;
+    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: `@attr({ key: value })`
- - Boolean options: `@attr({ skip: true })`
- - String options: `@attr({ rename: "newName" })`
+ - 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` |
+| 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
+ 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
@@ -130,7 +151,7 @@ export function userToString(value: User): string {const parts: string[]= []; pa
  - **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.
+ 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 |