@macroforge/mcp-server 0.1.40 → 0.1.49

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

@@ -70,65 +70,33 @@ class Temperature {
 ```
 
 ```typescript after
-import { Option } from 'macroforge/utils';
-
-class Temperature {
-    value: number | null;
-    unit: string;
-
-    static compareTo(a: Temperature, b: Temperature): Option<number> {
-        return temperaturePartialCompare(a, b);
-    }
-}
-
-export function temperaturePartialCompare(a: Temperature, b: Temperature): Option<number> {
-    if (a === b) return Option.some(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 a.value === b.value ? 0 : null;
-    })();
-    if (cmp0 === null) return Option.none();
-    if (cmp0 !== 0) return Option.some(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);
-}
-```
-
-Generated output:
-
-```typescript
 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;
 }
 ```
 
-## Required Import
+## Return Type
 
-The generated code automatically adds an import for `Option` from `macroforge/utils`.
+The generated functions return `number | null` where `null` indicates incomparable values.

package/docs/builtin-macros/serialize.md

@@ -94,7 +94,7 @@ class User {
 @param value - The value to serialize
 @param ctx - The serialization context  */
 
-    static serializeWithContext(value: User, ctx: SerializeContext): Record<string, unknown> {
+    static serializeWithContext(value: User, ctx: @{SERIALIZE_CONTEXT}): Record<string, unknown> {
         return userSerializeWithContext(value, ctx);
     }
 }
@@ -104,67 +104,7 @@ class User {
 @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.
-@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['id'] = value.id;
-    result['userName'] = value.name;
-    {
-        const __flattened = userMetadataSerializeWithContext(value.metadata, ctx);
-        const { __type: _, __id: __, ...rest } = __flattened as any;
-        Object.assign(result, rest);
-    }
-    return result;
-}
-```
-
-Generated output:
-
-```typescript
-import { SerializeContext } from 'macroforge/serde';
-
-class User {
-    id: number;
-
-    name: string;
-
-    password: string;
-
-    metadata: UserMetadata;
-    /** 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.
-@param value - The value to serialize
-@param ctx - The serialization context  */
-
-    static serializeWithContext(value: User, ctx: SerializeContext): Record<string, unknown> {
-        return userSerializeWithContext(value, ctx);
-    }
-}
-
-/** 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();
+    const ctx = @{SERIALIZE_CONTEXT}.create();
     return JSON.stringify(userSerializeWithContext(value, ctx));
 } /** @internal Serializes with an existing context for nested/cyclic object graphs.
 @param value - The value to serialize

package/docs/concepts/architecture.md

@@ -1,49 +1,126 @@
 # Architecture
- *Macroforge is built as a native Node.js module using Rust and NAPI-RS. It leverages SWC for fast TypeScript parsing and code generation.*
- ## Overview
- <div class="border border-border bg-card p-4 text-center rounded-t-lg  "><div class="font-semibold text-foreground">Node.js / Vite <div class="font-semibold text-foreground">NAPI-RS Bindings <div class="font-semibold text-foreground">Macro Crates <div class="px-3 py-1.5 bg-muted rounded text-sm text-muted-foreground font-mono">macroforge_ts_synmacroforge_ts_quotemacroforge_ts_macros<div class="font-semibold text-foreground">SWC Core <div class="px-3 py-1.5 bg-muted rounded text-sm text-muted-foreground font-mono">TypeScript parsing & codegen ## Core Components
- ### SWC Core
- The foundation layer provides:
- - Fast TypeScript/JavaScript parsing
- - AST representation
- - Code generation (AST → source code)
- ### macroforge_ts_syn
- A Rust crate that provides:
- - TypeScript-specific AST types
- - 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}`
- ### macroforge_ts_macros
- The procedural macro attribute for defining derive macros:
- - `#[ts_macro_derive(Name)]` 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
- - 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
- - **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:
- ```
-// 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;;
-
-// Also available: raw crate access and SWC modules
-use macroforge_ts::swc_core;
-use macroforge_ts::swc_common;
-use macroforge_ts::swc_ecma_ast;
-``` ## Next Steps
- - [Write custom macros](../../docs/custom-macros)
- - [Explore the API reference](../../docs/api)
+
+Macroforge is built as a native Node.js module using Rust and NAPI-RS. It leverages SWC for fast TypeScript parsing and code generation.
+
+## Overview
+
+Node.js / Vite
+
+NAPI-RS Bindings
+
+Macro Crates
+
+macroforge\_ts\_syn
+
+macroforge\_ts\_quote
+
+macroforge\_ts\_macros
+
+SWC Core
+
+TypeScript parsing & codegen
+
+## Core Components
+
+### SWC Core
+
+The foundation layer provides:
+
+*   Fast TypeScript/JavaScript parsing
+*   AST representation
+*   Code generation (AST → source code)
+
+### macroforge\_ts\_syn
+
+A Rust crate that provides:
+
+*   TypeScript-specific AST types
+*   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}"}`
+
+### macroforge\_ts\_macros
+
+The procedural macro attribute for defining derive macros:
+
+*   `#[ts_macro_derive(Name)]` 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
+*   Handles data marshaling between Rust and JavaScript
+
+## Data Flow
+
+1\. Source Code
+
+TypeScript with @derive
+
+2\. NAPI-RS
+
+receives JavaScript string
+
+3\. SWC Parser
+
+parses to AST
+
+4\. Macro Expander
+
+finds @derive decorators
+
+5\. For Each Macro
+
+extract data, run macro, generate AST nodes
+
+6\. Merge
+
+generated nodes into AST
+
+7\. SWC Codegen
+
+generates source code
+
+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
+*   **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:
+
+Rust
+
+```
+// Convenient re-exports for macro development
+use macroforge_ts::macros::{ts_macro_derive, body, ts_template, above, below, signature};
+use macroforge_ts::ts_syn::{Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input};
+
+// Also available: raw crate access and SWC modules
+use macroforge_ts::swc_core;
+use macroforge_ts::swc_common;
+use macroforge_ts::swc_ecma_ast;
+```
+
+## Next Steps
+
+*   [Write custom macros](../../docs/custom-macros)
+*   [Explore the API reference](../../docs/api)

package/docs/concepts/derive-system/built-in-vs-custom-macros.md

@@ -0,0 +1,13 @@
+## 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/derive-system/overview.md

@@ -0,0 +1,200 @@
+# 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
+
+TypeScript
+
+```
+/** @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
+
+Source
+
+TypeScript
+
+```
+/** @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
+
+```
+/** 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 {
+    /** @debug({ rename: "userId" }) */
+    /** @serde({ rename: "user_id" }) */
+    id: number;
+
+    name: string;
+
+    /** @debug({ skip: true }) */
+    /** @serde({ skip: true }) */
+    password: string;
+
+    metadata: Record<string, unknown>;
+}
+```
+
+After (Generated)
+
+```
+import { SerializeContext as __mf_SerializeContext } from 'macroforge/serde';
+
+class User {
+    id: number;
+
+    name: string;
+
+    password: string;
+
+    metadata: Record<string, unknown>;
+
+    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.
+@param value - The value to serialize
+@param ctx - The serialization context  */
+
+    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(', ') + ' }';
+}
+
+/** 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 = __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: __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