@macroforge/mcp-server 0.1.40 → 0.1.49

package/docs/custom-macros/ts-quote/comments-and.md

@@ -1,45 +1,79 @@
-## Comments: `&#123;> "..." <&#125;` and `&#123;>> "..." <<&#125;`
+## Comments: `{> "..." <}` and `{>> "..." <<}`
 
 Since Rust's tokenizer strips whitespace before macros see them, use string literals to preserve exact spacing in comments:
 
 ### Block Comments
 
-Use `&#123;> "comment" <&#125;` for block comments:
+Use `{> "comment" <}` for block comments:
 
-```rust
-let code = ts_template! {
-    {> "This is a block comment" <}
-    const x = 42;
+Rust
+
+```
+let code = ts_template! {
+    {> "This is a block comment" <}
+    const x = 42;
 };
 ```
 
 **Generates:**
 
-```typescript
-/* This is a block comment */
-const x = 42;
+TypeScript
+
+```
+/* This is a block comment */
+const x = 42;
 ```
 
 ### Doc Comments (JSDoc)
 
-Use `&#123;>> "doc" <<&#125;` for JSDoc comments:
+Use `{>> "doc" <<}` for JSDoc comments:
+
+Rust
 
-```rust
-let code = ts_template! {
-    {>> "@param {string} name - The user's name" <<}
-    {>> "@returns {string} A greeting message" <<}
-    function greet(name: string): string {
-        return "Hello, " + name;
-    }
+```
+let code = ts_template! {
+    {>> "@param {string} name - The user's name" <<}
+    {>> "@returns {string} A greeting message" <<}
+    function greet(name: string): string {
+        return "Hello, " + name;
+    }
 };
 ```
 
 **Generates:**
 
-```typescript
-/** @param {string} name - The user's name */
-/** @returns {string} A greeting message */
-function greet(name: string): string {
-    return "Hello, " + name;
+TypeScript
+
+```
+/** @param {string} name - The user's name */
+/** @returns {string} A greeting message */
+function greet(name: string): string {
+    return "Hello, " + name;
 }
+```
+
+### Comments with Interpolation
+
+Use `format!()` or similar to build dynamic comment strings:
+
+Rust
+
+```
+let param_name = "userId";
+let param_type = "number";
+let comment = format!("@param {{{}}} {} - The user ID", param_type, param_name);
+
+let code = ts_template! {
+    {>> @{comment} <<}
+    function getUser(userId: number) {}
+};
+```
+
+**Generates:**
+
+TypeScript
+
+```
+/** @param {number} userId - The user ID */
+function getUser(userId: number) {}
 ```

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

@@ -4,82 +4,85 @@ Here's a comparison showing how `ts_template!` simplifies code generation:
 
 ### Before (Manual AST Building)
 
-```rust
-pub fn derive_json_macro(input: TsStream) -> MacroResult {
-    let input = parse_ts_macro_input!(input as DeriveInput);
-
-    match &input.data {
-        Data::Class(class) => {
-            let class_name = input.name();
-
-            let mut body_stmts = vec![ts_quote!( const result = {}; as Stmt )];
-
-            for field_name in class.field_names() {
-                body_stmts.push(ts_quote!(
-                    result.$(ident!("{}", field_name)) = this.$(ident!("{}", field_name));
-                    as Stmt
-                ));
-            }
-
-            body_stmts.push(ts_quote!( return result; as Stmt ));
-
-            let runtime_code = fn_assign!(
-                member_expr!(Expr::Ident(ident!(class_name)), "prototype"),
-                "toJSON",
-                body_stmts
-            );
-
-            // ...
-        }
-    }
-}
+Rust
+
 ```
+pub fn derive_json_macro(input: TsStream) -> MacroResult {
+    let input = parse_ts_macro_input!(input as DeriveInput);
+
+    match &input.data {
+        Data::Class(class) => {
+            let class_name = input.name();
+
+            let mut body_stmts = vec![ts_quote!( const result = {}; as Stmt )];
+
+            for field_name in class.field_names() {
+                body_stmts.push(ts_quote!(
+                    result.$(ident!("{}", field_name)) = this.$(ident!("{}", field_name));
+                    as Stmt
+                ));
+            }
 
-### After (With ts_template!)
-
-```rust
-pub fn derive_json_macro(input: TsStream) -> MacroResult {
-    let input = parse_ts_macro_input!(input as DeriveInput);
-
-    match &input.data {
-        Data::Class(class) => {
-            let class_name = input.name();
-            let fields = class.field_names();
-
-            let runtime_code = ts_template! {
-                @{class_name}.prototype.toJSON = function() {
-                    const result = {};
-                    {#for field in fields}
-                        result.@{field} = this.@{field};
-                    {/for}
-                    return result;
-                };
-            };
-
-            // ...
-        }
-    }
+            body_stmts.push(ts_quote!( return result; as Stmt ));
+
+            let runtime_code = fn_assign!(
+                member_expr!(Expr::Ident(ident!(class_name)), "prototype"),
+                "toJSON",
+                body_stmts
+            );
+
+            // ...
+        }
+    }
 }
 ```
 
-## How It Works
+### After (With ts\_template!)
 
-1. **Compile-Time:** The template is parsed during macro expansion
+Rust
 
-    2. **String Building:** Generates Rust code that builds a TypeScript string at runtime
+```
+pub fn derive_json_macro(input: TsStream) -> MacroResult {
+    let input = parse_ts_macro_input!(input as DeriveInput);
+
+    match &input.data {
+        Data::Class(class) => {
+            let class_name = input.name();
+            let fields = class.field_names();
+
+            let runtime_code = ts_template! {
+                @{class_name}.prototype.toJSON = function() {
+                    const result = {};
+                    {#for field in fields}
+                        result.@{field} = this.@{field};
+                    {/for}
+                    return result;
+                };
+            };
+
+            // ...
+        }
+    }
+}
+```
 
-    3. **SWC Parsing:** The generated string is parsed with SWC to produce a typed AST
+## How It Works
 
-    4. **Result:** Returns `Stmt` that can be used in `MacroResult` patches
+1.  **Compile-Time:** The template is parsed during macro expansion
+2.  **String Building:** Generates Rust code that builds a TypeScript string at runtime
+3.  **SWC Parsing:** The generated string is parsed with SWC to produce a typed AST
+4.  **Result:** Returns `Stmt` that can be used in `MacroResult` patches
 
 ## Return Type
 
-`ts_template!` returns a `Result<Stmt, TsSynError>` by default. The macro automatically unwraps and provides helpful error messages showing the generated TypeScript code if parsing fails:
+`ts_template!` returns a `Result<Stmt, TsSynError>` by default. The macro automatically unwraps and provides helpful error messages showing the generated TypeScript code if parsing fails:
+
+Text
 
-```text
-Failed to parse generated TypeScript:
-User.prototype.toJSON = function( {
-    return {};
+```
+Failed to parse generated TypeScript:
+User.prototype.toJSON = function( {
+    return {};
 }
 ```
 
@@ -87,49 +90,37 @@ This shows you exactly what was generated, making debugging easy!
 
 ## Nesting and Regular TypeScript
 
-You can mix template syntax with regular TypeScript. Braces <code >&#123;&#125;</code > are recognized as either:
+You can mix template syntax with regular TypeScript. Braces `{}` are recognized as either:
 
-- **Template tags** if they start with `#`, `$`, `:`, or `/`
+*   **Template tags** if they start with `#`, `$`, `:`, or `/`
+*   **Regular TypeScript blocks** otherwise
 
-    - **Regular TypeScript blocks** otherwise
+Rust
 
-```rust
-ts_template! {
-    const config = {
-        {#if use_strict}
-            strict: true,
-        {:else}
-            strict: false,
-        {/if}
-        timeout: 5000
-    };
+```
+ts_template! {
+    const config = {
+        {#if use_strict}
+            strict: true,
+        {:else}
+            strict: false,
+        {/if}
+        timeout: 5000
+    };
 }
 ```
 
 ## Comparison with Alternatives
 
-| `ts_quote!` 
-            | Compile-time validation, type-safe 
-            | Can't handle Vec<Stmt>, verbose 
-        
-
-        
-            | `parse_ts_str()` 
-            | Maximum flexibility 
-            | Runtime parsing, less readable 
-        
-
-        
-            | `ts_template!` 
-            | Readable, handles loops/conditions 
-            | Small runtime parsing overhead
+| Approach         | Pros                               | Cons                             |
+| ---------------- | ---------------------------------- | -------------------------------- |
+| `ts_quote!`      | Compile-time validation, type-safe | Can't handle Vec\<Stmt>, verbose |
+| `parse_ts_str()` | Maximum flexibility                | Runtime parsing, less readable   |
+| `ts_template!`   | Readable, handles loops/conditions | Small runtime parsing overhead   |
 
 ## Best Practices
 
-1. Use `ts_template!` for complex code generation with loops/conditions
-
-    2. Use `ts_quote!` for simple, static statements
-
-    3. Keep templates readable - extract complex logic into variables
-
-    4. Don't nest templates too deeply - split into helper functions
+1.  Use `ts_template!` for complex code generation with loops/conditions
+2.  Use `ts_quote!` for simple, static statements
+3.  Keep templates readable - extract complex logic into variables
+4.  Don't nest templates too deeply - split into helper functions

package/docs/custom-macros/ts-quote/conditionals-ifif.md

@@ -1,46 +1,52 @@
-## Conditionals: `{#if}...{/if}`
+## Conditionals: `{#if}...{/if}`
 
 Basic conditional:
 
-```rust
-let needs_validation = true;
+Rust
 
-let code = ts_template! {
-    function save() {
-        {#if needs_validation}
-            if (!this.isValid()) return false;
-        {/if}
-        return this.doSave();
-    }
+```
+let needs_validation = true;
+
+let code = ts_template! {
+    function save() {
+        {#if needs_validation}
+            if (!this.isValid()) return false;
+        {/if}
+        return this.doSave();
+    }
 };
 ```
 
 ### If-Else
 
-```rust
-let has_default = true;
+Rust
 
-let code = ts_template! {
-    {#if has_default}
-        return defaultValue;
-    {:else}
-        throw new Error("No default");
-    {/if}
+```
+let has_default = true;
+
+let code = ts_template! {
+    {#if has_default}
+        return defaultValue;
+    {:else}
+        throw new Error("No default");
+    {/if}
 };
 ```
 
 ### If-Else-If Chains
 
-```rust
-let level = 2;
-
-let code = ts_template! {
-    {#if level == 1}
-        console.log("Level 1");
-    {:else if level == 2}
-        console.log("Level 2");
-    {:else}
-        console.log("Other level");
-    {/if}
+Rust
+
+```
+let level = 2;
+
+let code = ts_template! {
+    {#if level == 1}
+        console.log("Level 1");
+    {:else if level == 2}
+        console.log("Level 2");
+    {:else}
+        console.log("Other level");
+    {/if}
 };
 ```

package/docs/custom-macros/ts-quote/identifier-concatenation-content.md

@@ -1,42 +1,50 @@
-## Identifier Concatenation: `{| content |}`
+## Identifier Concatenation: `{| content |}`
 
-When you need to build identifiers dynamically (like `getUser`, `setName`), use the ident block syntax. Everything inside `{| |}` is concatenated without spaces:
+When you need to build identifiers dynamically (like `getUser`, `setName`), use the ident block syntax. Everything inside `{| |}` is concatenated without spaces:
 
-```rust
-let field_name = "User";
+Rust
 
-let code = ts_template! {
-    function {|get@{field_name}|}() {
-        return this.@{field_name.to_lowercase()};
-    }
+```
+let field_name = "User";
+
+let code = ts_template! {
+    function {|get@{field_name}|}() {
+        return this.@{field_name.to_lowercase()};
+    }
 };
 ```
 
 **Generates:**
 
-```typescript
-function getUser() {
-  return this.user;
+TypeScript
+
+```
+function getUser() {
+  return this.user;
 }
 ```
 
-Without ident blocks, `@{}` always adds a space after for readability. Use `{| |}` when you explicitly want concatenation:
+Without ident blocks, `@{}` always adds a space after for readability. Use `{| |}` when you explicitly want concatenation:
 
-```rust
-let name = "Status";
+Rust
 
-// With space (default behavior)
-ts_template! { namespace @{name} }  // → "namespace Status"
+```
+let name = "Status";
+
+// With space (default behavior)
+ts_template! { namespace @{name} }  // → "namespace Status"
 
-// Without space (ident block)
-ts_template! { {|namespace@{name}|} }  // → "namespaceStatus"
+// Without space (ident block)
+ts_template! { {|namespace@{name}|} }  // → "namespaceStatus"
 ```
 
 Multiple interpolations can be combined:
 
-```rust
-let entity = "user";
-let action = "create";
+Rust
+
+```
+let entity = "user";
+let action = "create";
 
-ts_template! { {|@{entity}_@{action}|} }  // → "user_create"
+ts_template! { {|@{entity}_@{action}|} }  // → "user_create"
 ```

package/docs/custom-macros/ts-quote/iteration-for.md

@@ -1,60 +1,68 @@
-## Iteration: `{#for}`
-
-```rust
-let fields = vec!["name", "email", "age"];
-
-let code = ts_template! {
-    function toJSON() {
-        const result = {};
-        {#for field in fields}
-            result.@{field} = this.@{field};
-        {/for}
-        return result;
-    }
+## Iteration: `{#for}`
+
+Rust
+
+```
+let fields = vec!["name", "email", "age"];
+
+let code = ts_template! {
+    function toJSON() {
+        const result = {};
+        {#for field in fields}
+            result.@{field} = this.@{field};
+        {/for}
+        return result;
+    }
 };
 ```
 
 **Generates:**
 
-```typescript
-function toJSON() {
-  const result = {};
-  result.name = this.name;
-  result.email = this.email;
-  result.age = this.age;
-  return result;
+TypeScript
+
+```
+function toJSON() {
+  const result = {};
+  result.name = this.name;
+  result.email = this.email;
+  result.age = this.age;
+  return result;
 }
 ```
 
 ### Tuple Destructuring in Loops
 
-```rust
-let items = vec![("user", "User"), ("post", "Post")];
+Rust
+
+```
+let items = vec![("user", "User"), ("post", "Post")];
 
-let code = ts_template! {
-    {#for (key, class_name) in items}
-        const @{key} = new @{class_name}();
-    {/for}
+let code = ts_template! {
+    {#for (key, class_name) in items}
+        const @{key} = new @{class_name}();
+    {/for}
 };
 ```
 
 ### Nested Iterations
 
-```rust
-let classes = vec![
-    ("User", vec!["name", "email"]),
-    ("Post", vec!["title", "content"]),
+Rust
+
+```
+let classes = vec![
+    ("User", vec!["name", "email"]),
+    ("Post", vec!["title", "content"]),
 ];
 
-ts_template! {
-    {#for (class_name, fields) in classes}
-        @{class_name}.prototype.toJSON = function() {
-            return {
-                {#for field in fields}
-                    @{field}: this.@{field},
-                {/for}
-            };
-        };
-    {/for}
+ts_template! {
+    {#for (class_name, fields) in classes}
+        @{class_name}.prototype.toJSON = function() {
+            return {
+                {#for field in fields}
+                    @{field}: this.@{field},
+                {/for}
+            };
+        };
+    {/for}
 }
 ```

package/docs/custom-macros/ts-quote/local-constants-let.md

@@ -1,34 +1,36 @@
-## Local Constants: `{$let}`
+## Local Constants: `{$let}`
 
 Define local variables within the template scope:
 
-```rust
-let items = vec![("user", "User"), ("post", "Post")];
+Rust
 
-let code = ts_template! {
-    {#for (key, class_name) in items}
-        {$let upper = class_name.to_uppercase()}
-        console.log("Processing @{upper}");
-        const @{key} = new @{class_name}();
-    {/for}
+```
+let items = vec![("user", "User"), ("post", "Post")];
+
+let code = ts_template! {
+    {#for (key, class_name) in items}
+        {$let upper = class_name.to_uppercase()}
+        console.log("Processing @{upper}");
+        const @{key} = new @{class_name}();
+    {/for}
 };
 ```
 
 This is useful for computing derived values inside loops without cluttering the Rust code.
 
-<h2 id="mutable-variables">
-    Mutable Variables: `&#123;$let mut&#125;`
-</h2>
+## Mutable Variables: `{$let mut}`
 
-When you need to modify a variable within the template (e.g., in a <code >while</code > loop), use `&#123;$let mut&#125;`:
+When you need to modify a variable within the template (e.g., in a `while` loop), use `{$let mut}`:
 
-```rust
-let code = ts_template! {
-    {$let mut count = 0}
-    {#for item in items}
-        console.log("Item @{count}: @{item}");
-        {$do count += 1}
-    {/for}
-    console.log("Total: @{count}");
+Rust
+
+```
+let code = ts_template! {
+    {$let mut count = 0}
+    {#for item in items}
+        console.log("Item @{count}: @{item}");
+        {$do count += 1}
+    {/for}
+    console.log("Total: @{count}");
 };
 ```