@macroforge/mcp-server 0.1.39 → 0.1.42

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

@@ -3,31 +3,32 @@
  ## 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
+ 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
- **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) */
-class User {
+class User &#123;
     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 {
+class User &#123;
     name: string;
 
-    static toString(value: User): string {
+    static toString(value: User): string &#123;
         return userToString(value);
-    }
-}
+    &#125;
+&#125;
 
-export function userToString(value: User): string {
+export function userToString(value: User): string &#123;
     const parts: string[] = [];
     parts.push('name: ' + value.name);
-    return 'User { ' + parts.join(', ') + ' }';
-}
+    return 'User &#123; ' + parts.join(', ') + ' &#125;';
+&#125;
 ``` ## Zero Runtime Overhead
  Because code generation happens at compile time, there's no:
  - Runtime reflection or metadata

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

@@ -3,57 +3,57 @@
  ## 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
+ 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 macroforge_ts::macros::&#123;ts_macro_derive, body&#125;;
-use macroforge_ts::ts_syn::&#123;Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input&#125;;
+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;;
 
 #[ts_macro_derive(
-    JSON,
-    description = "Generates toJSON() returning a plain object"
+&nbsp;&nbsp;&nbsp;&nbsp;JSON,
+&nbsp;&nbsp;&nbsp;&nbsp;description&nbsp;=&nbsp;"Generates&nbsp;toJSON()&nbsp;returning&nbsp;a&nbsp;plain&nbsp;object"
 )]
-pub fn derive_json(mut input: TsStream) -> Result&#x3C;TsStream, MacroforgeError> &#123;
-    let input = parse_ts_macro_input!(input as DeriveInput);
+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);
 
-    match &#x26;input.data &#123;
-        Data::Class(class) => &#123;
-            Ok(body! &#123;
-                toJSON(): Record&#x3C;string, unknown> &#123;
-                    return &#123;
-                        &#123;#for field in class.field_names()&#125;
-                            @&#123;field&#125;: this.@&#123;field&#125;,
-                        &#123;/for&#125;
-                    &#125;;
-                &#125;
-            &#125;)
-        &#125;
-        _ => Err(MacroforgeError::new(
-            input.decorator_span(),
-            "@derive(JSON) only works on classes",
-        )),
-    &#125;
+&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:
  ```
-/** import macro &#123; JSON &#125; from "@my/macros"; */
+/**&nbsp;import&nbsp;macro&nbsp;&#123;&nbsp;JSON&nbsp;&#125;&nbsp;from&nbsp;"@my/macros";&nbsp;*/
 
-/** @derive(JSON) */
-class User &#123;
-  name: string;
-  age: number;
+/**&nbsp;@derive(JSON)&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;
 
-const user = new User("Alice", 30);
-console.log(user.toJSON()); // &#123; name: "Alice", age: 30 &#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)

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

@@ -3,109 +3,109 @@
  ## Prerequisites
  - Rust toolchain (1.88 or later)
  - Node.js 24 or later
- - NAPI-RS CLI: `cargo install macroforge_ts`
+ - NAPI-RS CLI: <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">cargo<span style="--shiki-dark:#9ECBFF;--shiki-light:#032F62"> install<span style="--shiki-dark:#9ECBFF;--shiki-light:#032F62"> macroforge_ts</code>
  ## Create the Project
  ```
-# Create a new directory
-mkdir my-macros
-cd my-macros
+#&nbsp;Create&nbsp;a&nbsp;new&nbsp;directory
+mkdir&nbsp;my-macros
+cd&nbsp;my-macros
 
-# Initialize with NAPI-RS
-napi new --platform --name my-macros
+#&nbsp;Initialize&nbsp;with&nbsp;NAPI-RS
+napi&nbsp;new&nbsp;--platform&nbsp;--name&nbsp;my-macros
 ``` ## Configure Cargo.toml
- Update your `Cargo.toml` with the required dependencies:
+ Update your <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#FDAEB7;--shiki-dark-font-style:italic;--shiki-light:#B31D28;--shiki-light-font-style:italic">Cargo.toml</code> with the required dependencies:
  ```
 [package]
-name = "my-macros"
-version = "0.1.0"
-edition = "2024"
+name&nbsp;=&nbsp;"my-macros"
+version&nbsp;=&nbsp;"0.1.0"
+edition&nbsp;=&nbsp;"2024"
 
 [lib]
-crate-type = ["cdylib"]
+crate-type&nbsp;=&nbsp;["cdylib"]
 
 [dependencies]
-macroforge_ts = "0.1"
-napi = &#123; version = "3", features = ["napi8", "compat-mode"] &#125;
-napi-derive = "3"
+macroforge_ts&nbsp;=&nbsp;"0.1"
+napi&nbsp;=&nbsp;&#123;&nbsp;version&nbsp;=&nbsp;"3",&nbsp;features&nbsp;=&nbsp;["napi8",&nbsp;"compat-mode"]&nbsp;&#125;
+napi-derive&nbsp;=&nbsp;"3"
 
 [build-dependencies]
-napi-build = "2"
+napi-build&nbsp;=&nbsp;"2"
 
 [profile.release]
-lto = true
-strip = true
+lto&nbsp;=&nbsp;true
+strip&nbsp;=&nbsp;true
 ``` ## Create build.rs
  ```
-fn main() &#123;
-    napi_build::setup();
+fn&nbsp;main()&nbsp;&#123;
+&nbsp;&nbsp;&nbsp;&nbsp;napi_build::setup();
 &#125;
 ``` ## Create src/lib.rs
  ```
-use macroforge_ts::macros::&#123;ts_macro_derive, body&#125;;
-use macroforge_ts::ts_syn::&#123;
-    Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input,
+use&nbsp;macroforge_ts::macros::&#123;ts_macro_derive,&nbsp;body&#125;;
+use&nbsp;macroforge_ts::ts_syn::&#123;
+&nbsp;&nbsp;&nbsp;&nbsp;Data,&nbsp;DeriveInput,&nbsp;MacroforgeError,&nbsp;TsStream,&nbsp;parse_ts_macro_input,
 &#125;;
 
 #[ts_macro_derive(
-    JSON,
-    description = "Generates toJSON() returning a plain object"
+&nbsp;&nbsp;&nbsp;&nbsp;JSON,
+&nbsp;&nbsp;&nbsp;&nbsp;description&nbsp;=&nbsp;"Generates&nbsp;toJSON()&nbsp;returning&nbsp;a&nbsp;plain&nbsp;object"
 )]
-pub fn derive_json(mut input: TsStream) -> Result&#x3C;TsStream, MacroforgeError> &#123;
-    let input = parse_ts_macro_input!(input as DeriveInput);
+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);
 
-    match &#x26;input.data &#123;
-        Data::Class(class) => &#123;
-            Ok(body! &#123;
-                toJSON(): Record&#x3C;string, unknown> &#123;
-                    return &#123;
-                        &#123;#for field in class.field_names()&#125;
-                            @&#123;field&#125;: this.@&#123;field&#125;,
-                        &#123;/for&#125;
-                    &#125;;
-                &#125;
-            &#125;)
-        &#125;
-        _ => Err(MacroforgeError::new(
-            input.decorator_span(),
-            "@derive(JSON) only works on classes",
-        )),
-    &#125;
+&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;
 ``` ## Create package.json
  ```
 &#123;
-  "name": "@my-org/macros",
-  "version": "0.1.0",
-  "main": "index.js",
-  "types": "index.d.ts",
-  "napi": &#123;
-    "name": "my-macros",
-    "triples": &#123;
-      "defaults": true
-    &#125;
-  &#125;,
-  "files": [
-    "index.js",
-    "index.d.ts",
-    "*.node"
-  ],
-  "scripts": &#123;
-    "build": "napi build --release",
-    "prepublishOnly": "napi build --release"
-  &#125;,
-  "devDependencies": &#123;
-    "@napi-rs/cli": "^3.0.0-alpha.0"
-  &#125;
+&nbsp;&nbsp;"name":&nbsp;"@my-org/macros",
+&nbsp;&nbsp;"version":&nbsp;"0.1.0",
+&nbsp;&nbsp;"main":&nbsp;"index.js",
+&nbsp;&nbsp;"types":&nbsp;"index.d.ts",
+&nbsp;&nbsp;"napi":&nbsp;&#123;
+&nbsp;&nbsp;&nbsp;&nbsp;"name":&nbsp;"my-macros",
+&nbsp;&nbsp;&nbsp;&nbsp;"triples":&nbsp;&#123;
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"defaults":&nbsp;true
+&nbsp;&nbsp;&nbsp;&nbsp;&#125;
+&nbsp;&nbsp;&#125;,
+&nbsp;&nbsp;"files":&nbsp;[
+&nbsp;&nbsp;&nbsp;&nbsp;"index.js",
+&nbsp;&nbsp;&nbsp;&nbsp;"index.d.ts",
+&nbsp;&nbsp;&nbsp;&nbsp;"*.node"
+&nbsp;&nbsp;],
+&nbsp;&nbsp;"scripts":&nbsp;&#123;
+&nbsp;&nbsp;&nbsp;&nbsp;"build":&nbsp;"napi&nbsp;build&nbsp;--release",
+&nbsp;&nbsp;&nbsp;&nbsp;"prepublishOnly":&nbsp;"napi&nbsp;build&nbsp;--release"
+&nbsp;&nbsp;&#125;,
+&nbsp;&nbsp;"devDependencies":&nbsp;&#123;
+&nbsp;&nbsp;&nbsp;&nbsp;"@napi-rs/cli":&nbsp;"^3.0.0-alpha.0"
+&nbsp;&nbsp;&#125;
 &#125;
 ``` ## Build the Package
  ```
-# Build the native addon
-npm run build
+#&nbsp;Build&nbsp;the&nbsp;native&nbsp;addon
+npm&nbsp;run&nbsp;build
 
-# This creates:
-# - index.js (JavaScript bindings)
-# - index.d.ts (TypeScript types)
-# - *.node (native binary)
+#&nbsp;This&nbsp;creates:
+#&nbsp;-&nbsp;index.js&nbsp;(JavaScript&nbsp;bindings)
+#&nbsp;-&nbsp;index.d.ts&nbsp;(TypeScript&nbsp;types)
+#&nbsp;-&nbsp;*.node&nbsp;(native&nbsp;binary)
 ```  **Tip For cross-platform builds, use GitHub Actions with the NAPI-RS CI template. ## Next Steps
  - [Learn the #[ts_macro_derive] attribute](../../docs/custom-macros/ts-macro-derive)
  - [Master the template syntax](../../docs/custom-macros/ts-quote)