@macroforge/mcp-server 0.1.25 → 0.1.26

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

@@ -0,0 +1,50 @@
+## Attribute Options
+
+### Name (Required)
+
+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(...)
+```
+
+### Description
+
+Provides documentation for the macro:
+
+```rust
+#[ts_macro_derive(
+    JSON,
+    description = "Generates toJSON() returning a plain object"
+)]
+pub fn derive_json(...)
+```
+
+### Attributes
+
+Declare which field-level decorators your macro accepts:
+
+```rust
+#[ts_macro_derive(
+    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>
+```
+
+| `input: TsStream` 
+| Token stream containing the class/interface AST 
+
+| `Result<TsStream, MacroforgeError>` 
+| Returns generated code or an error with source location

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

@@ -0,0 +1,51 @@
+## 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,
+};
+
+// 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)
+)]
+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)

package/docs/custom-macros/ts-macro-derive/deriveinput-structure.md

@@ -0,0 +1,61 @@
+## DeriveInput Structure
+
+```rust
+struct DeriveInput {
+    pub ident: Ident,           // The type name
+    pub span: SpanIR,           // Span of the type definition
+    pub attrs: Vec<Attribute>,  // Decorators (excluding @derive)
+    pub data: Data,             // The parsed type data
+    pub context: MacroContextIR, // Macro context with spans
+
+    // Helper methods
+    fn name(&self) -> &str;              // Get the type name
+    fn decorator_span(&self) -> SpanIR;  // Span of @derive decorator
+    fn as_class(&self) -> Option<&DataClass>;
+    fn as_interface(&self) -> Option<&DataInterface>;
+    fn as_enum(&self) -> Option<&DataEnum>;
+}
+
+enum Data {
+    Class(DataClass),
+    Interface(DataInterface),
+    Enum(DataEnum),
+    TypeAlias(DataTypeAlias),
+}
+
+impl DataClass {
+    fn fields(&self) -> &[FieldIR];
+    fn methods(&self) -> &[MethodSigIR];
+    fn field_names(&self) -> impl Iterator<Item = &str>;
+    fn field(&self, name: &str) -> Option<&FieldIR>;
+    fn body_span(&self) -> SpanIR;      // For inserting code into class body
+    fn type_params(&self) -> &[String]; // Generic type parameters
+    fn heritage(&self) -> &[String];    // extends/implements clauses
+    fn is_abstract(&self) -> bool;
+}
+
+impl DataInterface {
+    fn fields(&self) -> &[InterfaceFieldIR];
+    fn methods(&self) -> &[InterfaceMethodIR];
+    fn field_names(&self) -> impl Iterator<Item = &str>;
+    fn field(&self, name: &str) -> Option<&InterfaceFieldIR>;
+    fn body_span(&self) -> SpanIR;
+    fn type_params(&self) -> &[String];
+    fn heritage(&self) -> &[String];    // extends clauses
+}
+
+impl DataEnum {
+    fn variants(&self) -> &[EnumVariantIR];
+    fn variant_names(&self) -> impl Iterator<Item = &str>;
+    fn variant(&self, name: &str) -> Option<&EnumVariantIR>;
+}
+
+impl DataTypeAlias {
+    fn body(&self) -> &TypeBody;
+    fn type_params(&self) -> &[String];
+    fn is_union(&self) -> bool;
+    fn is_object(&self) -> bool;
+    fn as_union(&self) -> Option<&[TypeMember]>;
+    fn as_object(&self) -> Option<&[InterfaceFieldIR]>;
+}
+```

package/docs/custom-macros/ts-macro-derive/overview.md

@@ -0,0 +1,15 @@
+# ts_macro_derive
+
+*The `#[ts_macro_derive]` attribute is a Rust procedural macro that registers your function as a Macroforge derive macro.*
+
+## Basic Syntax
+
+```rust
+use macroforge_ts::macros::ts_macro_derive;
+use macroforge_ts::ts_syn::{TsStream, MacroforgeError};
+
+#[ts_macro_derive(MacroName)]
+pub fn my_macro(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
+    // Macro implementation
+}
+```

package/docs/custom-macros/ts-macro-derive/parsing-input.md

@@ -0,0 +1,27 @@
+## Parsing Input
+
+Use `parse_ts_macro_input!` to convert the token stream:
+
+```rust
+use macroforge_ts::ts_syn::{Data, DeriveInput, parse_ts_macro_input};
+
+#[ts_macro_derive(MyMacro)]
+pub fn my_macro(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
+    let input = parse_ts_macro_input!(input as DeriveInput);
+
+    // Access class data
+    match &input.data {
+        Data::Class(class) => {
+            let class_name = input.name();
+            let fields = class.fields();
+            // ...
+        }
+        Data::Interface(interface) => {
+            // Handle interfaces
+        }
+        Data::Enum(_) => {
+            // Handle enums (if supported)
+        }
+    }
+}
+```

package/docs/custom-macros/ts-macro-derive/returning-errors.md

@@ -0,0 +1,21 @@
+## Returning Errors
+
+Use `MacroforgeError` to report errors with source locations:
+
+```rust
+#[ts_macro_derive(ClassOnly)]
+pub fn class_only(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
+    let input = parse_ts_macro_input!(input as DeriveInput);
+
+    match &input.data {
+        Data::Class(_) => {
+            // Generate code...
+            Ok(body! { /* ... */ })
+        }
+        _ => Err(MacroforgeError::new(
+            input.decorator_span(),
+            "@derive(ClassOnly) can only be used on classes",
+        )),
+    }
+}
+```

package/docs/custom-macros/ts-quote/backtick-template-literals.md

@@ -0,0 +1,29 @@
+## Backtick Template Literals: `"'^...^'"`
+
+For JavaScript template literals (backtick strings), use the `'^...^'` syntax. This outputs actual backticks and passes through `${"${}"}` for JS interpolation:
+
+```rust
+let tag_name = "div";
+
+let code = ts_template! {
+    const html = "'^<@{tag_name}>\${content}</@{tag_name}>^'";
+};
+```
+
+**Generates:**
+
+<CodeBlock code={'const html = `${content}`;'} lang="typescript" />
+
+You can mix Rust `@&#123;&#125;` interpolation (evaluated at macro expansion time) with JS `${"${}"}` interpolation (evaluated at runtime):
+
+```rust
+let class_name = "User";
+
+let code = ts_template! {
+    "'^Hello \${this.name}, you are a @{class_name}^'"
+};
+```
+
+**Generates:**
+
+<CodeBlock code={'`Hello ${this.name}, you are a User`'} lang="typescript" />

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

@@ -0,0 +1,66 @@
+## Comments: `&#123;> ... <&#125;` and `&#123;>> ... <<&#125;`
+
+Since Rust's tokenizer strips comments before macros see them, you can't write JSDoc comments directly. Instead, use the comment syntax to output JavaScript comments:
+
+### Block Comments
+
+Use `&#123;> comment <&#125;` for block comments:
+
+```rust
+let code = ts_template! {
+    {> This is a block comment <}
+    const x = 42;
+};
+```
+
+**Generates:**
+
+```typescript
+/* This is a block comment */
+const x = 42;
+```
+
+### Doc Comments (JSDoc)
+
+Use `&#123;>> doc <<&#125;` for JSDoc comments:
+
+```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;
+    }
+};
+```
+
+**Generates:**
+
+```typescript
+/** @param {string} name - The user's name */
+/** @returns {string} A greeting message */
+function greet(name: string): string {
+    return "Hello, " + name;
+}
+```
+
+### Comments with Interpolation
+
+Comments support `@&#123;expr&#125;` interpolation for dynamic content:
+
+```rust
+let param_name = "userId";
+let param_type = "number";
+
+let code = ts_template! {
+    {>> @param {@{param_type}} @{param_name} - The user ID <<}
+    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

@@ -0,0 +1,131 @@
+## Complete Example: JSON Derive Macro
+
+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
+            );
+
+            // ...
+        }
+    }
+}
+```
+
+### 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;
+                };
+            };
+
+            // ...
+        }
+    }
+}
+```
+
+## How It Works
+
+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:
+
+```text
+Failed to parse generated TypeScript:
+User.prototype.toJSON = function( {
+    return {};
+}
+```
+
+This shows you exactly what was generated, making debugging easy!
+
+## Nesting and Regular TypeScript
+
+You can mix template syntax with regular TypeScript. Braces `&#123;&#125;` are recognized as either:
+
+- **Template tags** if they start with `#`, `$`, `:`, or `/`
+
+- **Regular TypeScript blocks** otherwise
+
+```rust
+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
+
+## 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

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

@@ -0,0 +1,46 @@
+## Conditionals: `{#if}...{/if}`
+
+Basic conditional:
+
+```rust
+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;
+
+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}
+};
+```

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

@@ -0,0 +1,42 @@
+## Identifier Concatenation: `{| content |}`
+
+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";
+
+let code = ts_template! {
+    function {|get@{field_name}|}() {
+        return this.@{field_name.to_lowercase()};
+    }
+};
+```
+
+**Generates:**
+
+```typescript
+function getUser() {
+  return this.user;
+}
+```
+
+Without ident blocks, `@{}` always adds a space after for readability. Use `{| |}` when you explicitly want concatenation:
+
+```rust
+let name = "Status";
+
+// With space (default behavior)
+ts_template! { namespace @{name} }  // → "namespace Status"
+
+// Without space (ident block)
+ts_template! { {|namespace@{name}|} }  // → "namespaceStatus"
+```
+
+Multiple interpolations can be combined:
+
+```rust
+let entity = "user";
+let action = "create";
+
+ts_template! { {|@{entity}_@{action}|} }  // → "user_create"
+```

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

@@ -0,0 +1,60 @@
+## 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;
+}
+```
+
+### Tuple Destructuring in Loops
+
+```rust
+let items = vec![("user", "User"), ("post", "Post")];
+
+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"]),
+];
+
+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/match-expressions-match.md

@@ -0,0 +1,58 @@
+## Match Expressions: `{#match}`
+
+Use `match` for exhaustive pattern matching:
+
+```rust
+enum Visibility { Public, Private, Protected }
+let visibility = Visibility::Public;
+
+let code = ts_template! {
+    {#match visibility}
+        {:case Visibility::Public}
+            public
+        {:case Visibility::Private}
+            private
+        {:case Visibility::Protected}
+            protected
+    {/match}
+    field: string;
+};
+```
+
+**Generates:**
+
+```typescript
+public field: string;
+```
+
+### Match with Value Extraction
+
+```rust
+let result: Result<i32, &str> = Ok(42);
+
+let code = ts_template! {
+    const value = {#match result}
+        {:case Ok(val)}
+            @{val}
+        {:case Err(msg)}
+            throw new Error("@{msg}")
+    {/match};
+};
+```
+
+### Match with Wildcard
+
+```rust
+let count = 5;
+
+let code = ts_template! {
+    {#match count}
+        {:case 0}
+            console.log("none");
+        {:case 1}
+            console.log("one");
+        {:case _}
+            console.log("many");
+    {/match}
+};
+```

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

@@ -0,0 +1,13 @@
+# Template Syntax
+
+*The `macroforge_ts_quote` crate provides template-based code generation for TypeScript. The `ts_template!` macro uses Rust-inspired syntax for control flow and interpolation, making it easy to generate complex TypeScript code.*
+
+## Available Macros
+
+| `ts_template!` 
+| Any TypeScript code 
+| General code generation 
+
+| `body!` 
+| Class body members 
+| Methods and properties