@macroforge/mcp-server 0.1.42 → 0.1.49

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

@@ -1,112 +1,151 @@
 # Rust Setup
- *Create a new Rust crate that will contain your custom macros. This crate compiles to a native Node.js addon.*
- ## Prerequisites
- - Rust toolchain (1.88 or later)
- - Node.js 24 or later
- - 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
- ```
-#&nbsp;Create&nbsp;a&nbsp;new&nbsp;directory
-mkdir&nbsp;my-macros
-cd&nbsp;my-macros
-
-#&nbsp;Initialize&nbsp;with&nbsp;NAPI-RS
-napi&nbsp;new&nbsp;--platform&nbsp;--name&nbsp;my-macros
-``` ## Configure Cargo.toml
- 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:
- ```
+
+Create a new Rust crate that will contain your custom macros. This crate compiles to a native Node.js addon.
+
+## Prerequisites
+
+*   Rust toolchain (1.88 or later)
+*   Node.js 24 or later
+*   NAPI-RS CLI: `cargo install macroforge_ts`
+
+## Create the Project
+
+Bash
+
+```
+# Create a new directory
+mkdir my-macros
+cd my-macros
+
+# Initialize with NAPI-RS
+napi new --platform --name my-macros
+```
+
+## Configure Cargo.toml
+
+Update your `Cargo.toml` with the required dependencies:
+
+Cargo.toml 
+
+```
 [package]
-name&nbsp;=&nbsp;"my-macros"
-version&nbsp;=&nbsp;"0.1.0"
-edition&nbsp;=&nbsp;"2024"
+name = "my-macros"
+version = "0.1.0"
+edition = "2024"
 
 [lib]
-crate-type&nbsp;=&nbsp;["cdylib"]
+crate-type = ["cdylib"]
 
 [dependencies]
-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"
+macroforge_ts = "0.1"
+napi = { version = "3", features = ["napi8", "compat-mode"] }
+napi-derive = "3"
 
 [build-dependencies]
-napi-build&nbsp;=&nbsp;"2"
+napi-build = "2"
 
 [profile.release]
-lto&nbsp;=&nbsp;true
-strip&nbsp;=&nbsp;true
-``` ## Create build.rs
- ```
-fn&nbsp;main()&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;napi_build::setup();
-&#125;
-``` ## Create src/lib.rs
- ```
-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;;
+lto = true
+strip = true
+```
+
+## Create build.rs
+
+build.rs 
+
+```
+fn main() {
+    napi_build::setup();
+}
+```
+
+## Create src/lib.rs
+
+src/lib.rs 
+
+```
+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;
-``` ## Create package.json
- ```
-&#123;
-&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
- ```
-#&nbsp;Build&nbsp;the&nbsp;native&nbsp;addon
-npm&nbsp;run&nbsp;build
-
-#&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)
-**
+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",
+        )),
+    }
+}
+```
+
+## Create package.json
+
+package.json 
+
+```
+{
+  "name": "@my-org/macros",
+  "version": "0.1.0",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "napi": {
+    "name": "my-macros",
+    "triples": {
+      "defaults": true
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "*.node"
+  ],
+  "scripts": {
+    "build": "napi build --release",
+    "prepublishOnly": "napi build --release"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.0.0-alpha.0"
+  }
+}
+```
+
+## Build the Package
+
+Bash
+
+```
+# Build the native addon
+npm run build
+
+# This creates:
+# - index.js (JavaScript bindings)
+# - index.d.ts (TypeScript types)
+# - *.node (native 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)

package/docs/custom-macros/ts-macro-derive/accessing-field-data.md

@@ -2,52 +2,61 @@
 
 ### Class Fields (FieldIR)
 
-```rust
-struct FieldIR {
-    pub name: String,               // Field name
-    pub span: SpanIR,               // Field span
-    pub ts_type: String,            // TypeScript type annotation
-    pub optional: bool,             // Whether field has ?
-    pub readonly: bool,             // Whether field is readonly
-    pub visibility: Visibility,     // Public, Protected, Private
-    pub decorators: Vec<DecoratorIR>, // Field decorators
+Rust
+
+```
+struct FieldIR {
+    pub name: String,               // Field name
+    pub span: SpanIR,               // Field span
+    pub ts_type: String,            // TypeScript type annotation
+    pub optional: bool,             // Whether field has ?
+    pub readonly: bool,             // Whether field is readonly
+    pub visibility: Visibility,     // Public, Protected, Private
+    pub decorators: Vec<DecoratorIR>, // Field decorators
 }
 ```
 
 ### Interface Fields (InterfaceFieldIR)
 
-```rust
-struct InterfaceFieldIR {
-    pub name: String,
-    pub span: SpanIR,
-    pub ts_type: String,
-    pub optional: bool,
-    pub readonly: bool,
-    pub decorators: Vec<DecoratorIR>,
-    // Note: No visibility field (interfaces are always public)
+Rust
+
+```
+struct InterfaceFieldIR {
+    pub name: String,
+    pub span: SpanIR,
+    pub ts_type: String,
+    pub optional: bool,
+    pub readonly: bool,
+    pub decorators: Vec<DecoratorIR>,
+    // Note: No visibility field (interfaces are always public)
 }
 ```
 
 ### Enum Variants (EnumVariantIR)
 
-```rust
-struct EnumVariantIR {
-    pub name: String,
-    pub span: SpanIR,
-    pub value: EnumValue,  // Auto, String(String), or Number(f64)
-    pub decorators: Vec<DecoratorIR>,
+Rust
+
+```
+struct EnumVariantIR {
+    pub name: String,
+    pub span: SpanIR,
+    pub value: EnumValue,  // Auto, String(String), or Number(f64)
+    pub decorators: Vec<DecoratorIR>,
 }
 ```
 
 ### Decorator Structure
 
-```rust
-struct DecoratorIR {
-    pub name: String,      // e.g., "serde"
-    pub args_src: String,  // Raw args text, e.g., "skip, rename: 'id'"
-    pub span: SpanIR,
+Rust
+
+```
+struct DecoratorIR {
+    pub name: String,      // e.g., "serde"
+    pub args_src: String,  // Raw args text, e.g., "skip, rename: 'id'"
+    pub span: SpanIR,
 }
 ```
 
->
-> To check for decorators, iterate through `field.decorators` and check `decorator.name`. For parsing options, you can write helper functions like the built-in macros do.
+Note
+
+To check for decorators, iterate through `field.decorators` and check `decorator.name`. For parsing options, you can write helper functions like the built-in macros do.

package/docs/custom-macros/ts-macro-derive/adding-imports.md

@@ -2,20 +2,23 @@
 
 If your macro generates code that requires imports, use the `add_import` method on `TsStream`:
 
-```rust
-// Add an import to be inserted at the top of the file
-let mut output = body! {
-    validate(): ValidationResult {
-        return validateFields(this);
-    }
+Rust
+
+```
+// Add an import to be inserted at the top of the file
+let mut output = body! {
+    validate(): ValidationResult {
+        return validateFields(this);
+    }
 };
 
-// This will add: import { validateFields, ValidationResult } from "my-validation-lib";
-output.add_import("validateFields", "my-validation-lib");
-output.add_import("ValidationResult", "my-validation-lib");
+// This will add: import { validateFields, ValidationResult } from "my-validation-lib";
+output.add_import("validateFields", "my-validation-lib");
+output.add_import("ValidationResult", "my-validation-lib");
 
 Ok(output)
 ```
 
->
-> Imports are automatically deduplicated. If the same import already exists in the file, it won't be added again.
+Note
+
+Imports are automatically deduplicated. If the same import already exists in the file, it won't be added again.

package/docs/custom-macros/ts-macro-derive/attribute-options.md

@@ -4,47 +4,42 @@
 
 The first argument is the macro name that users will reference in `@derive()`:
 
-```rust
-#[ts_macro_derive(JSON)]  // Users write: @derive(JSON)
-pub fn derive_json(...)
+Rust
+
+```
+#[ts_macro_derive(JSON)]  // Users write: @derive(JSON)
+pub fn derive_json(...)
 ```
 
 ### Description
 
 Provides documentation for the macro:
 
-```rust
+Rust
+
+```
 #[ts_macro_derive(
-    JSON,
-    description = "Generates toJSON() returning a plain object"
+    JSON,
+    description = "Generates toJSON() returning a plain object"
 )]
-pub fn derive_json(...)
+pub fn derive_json(...)
 ```
 
 ### Attributes
 
 Declare which field-level decorators your macro accepts:
 
-```rust
+Rust
+
+```
 #[ts_macro_derive(
-    Debug,
-    description = "Generates toString()",
-    attributes(debug)  // Allows @debug({ ... }) on fields
+    Debug,
+    description = "Generates toString()",
+    attributes(debug)  // Allows @debug({ ... }) on fields
 )]
-pub fn derive_debug(...)
-```
-
->
-> Declared attributes become available as `@attributeName({ options })` decorators in TypeScript.
-
-## Function Signature
-
-```rust
-pub fn my_macro(mut input: TsStream) -> Result<TsStream, MacroforgeError>
+pub fn derive_debug(...)
 ```
 
-| `input: TsStream` 
-| Token stream containing the class/interface AST 
+Note
 
-| `Result<TsStream, MacroforgeError>` 
-| Returns generated code or an error with source location
+Declared attributes become available as `@attributeName({ options })` decorators in TypeScript.

package/docs/custom-macros/ts-macro-derive/complete-example.md

@@ -1,51 +1,53 @@
 ## Complete Example
 
-```rust
-use macroforge_ts::macros::{ts_macro_derive, body};
-use macroforge_ts::ts_syn::{
-    Data, DeriveInput, FieldIR, MacroforgeError, TsStream, parse_ts_macro_input,
+Rust
+
+```
+use macroforge_ts::macros::{ts_macro_derive, body};
+use macroforge_ts::ts_syn::{
+    Data, DeriveInput, FieldIR, MacroforgeError, TsStream, parse_ts_macro_input,
 };
 
-// Helper function to check if a field has a decorator
-fn has_decorator(field: &FieldIR, name: &str) -> bool {
-    field.decorators.iter().any(|d| d.name.eq_ignore_ascii_case(name))
+// Helper function to check if a field has a decorator
+fn has_decorator(field: &FieldIR, name: &str) -> bool {
+    field.decorators.iter().any(|d| d.name.eq_ignore_ascii_case(name))
 }
 
 #[ts_macro_derive(
-    Validate,
-    description = "Generates a validate() method",
-    attributes(validate)
+    Validate,
+    description = "Generates a validate() method",
+    attributes(validate)
 )]
-pub fn derive_validate(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
-    let input = parse_ts_macro_input!(input as DeriveInput);
-
-    match &input.data {
-        Data::Class(class) => {
-            let validations: Vec<_> = class.fields()
-                .iter()
-                .filter(|f| has_decorator(f, "validate"))
-                .collect();
-
-            Ok(body! {
-                validate(): string[] {
-                    const errors: string[] = [];
-                    {#for field in validations}
-                        if (!this.@{field.name}) {
-                            errors.push("@{field.name} is required");
-                        }
-                    {/for}
-                    return errors;
-                }
-            })
-        }
-        _ => Err(MacroforgeError::new(
-            input.decorator_span(),
-            "@derive(Validate) only works on classes",
-        )),
-    }
+pub fn derive_validate(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
+    let input = parse_ts_macro_input!(input as DeriveInput);
+
+    match &input.data {
+        Data::Class(class) => {
+            let validations: Vec<_> = class.fields()
+                .iter()
+                .filter(|f| has_decorator(f, "validate"))
+                .collect();
+
+            Ok(body! {
+                validate(): string[] {
+                    const errors: string[] = [];
+                    {#for field in validations}
+                        if (!this.@{field.name}) {
+                            errors.push("@{field.name} is required");
+                        }
+                    {/for}
+                    return errors;
+                }
+            })
+        }
+        _ => Err(MacroforgeError::new(
+            input.decorator_span(),
+            "@derive(Validate) only works on classes",
+        )),
+    }
 }
 ```
 
 ## Next Steps
 
-- [Learn the template syntax]({base}/docs/custom-macros/ts-quote)
+*   [Learn the template syntax](../../docs/custom-macros/ts-quote)