@macroforge/mcp-server 0.1.34 → 0.1.36

package/docs/builtin-macros/clone.md

@@ -1,203 +1,62 @@
 # Clone
-  *The `Clone` macro generates a `clone()` method for deep copying objects. This is analogous to Rust's `Clone` trait, providing a way to create independent copies of values.*
- ## Basic Usage
- **Before:**
-```
-/** @derive(Clone) */
-class Point {
-    x: number;
-    y: number;
 
-    constructor(x: number, y: number) {
-        this.x = x;
-        this.y = y;
-    }
-}
-```  
-**After:**
-```
-class Point {
-    x: number;
-    y: number;
+The `Clone` macro generates a `clone()` method for deep copying objects.
+This is analogous to Rust's `Clone` trait, providing a way to create
+independent copies of values.
 
-    constructor(x: number, y: number) {
-        this.x = x;
-        this.y = y;
-    }
+## Generated Output
 
-    clone(): Point {
-        const cloned = Object.create(Object.getPrototypeOf(this));
-        cloned.x = this.x;
-        cloned.y = this.y;
-        return cloned;
-    }
-}
-``` ```
-const original = new Point(10, 20);
-const copy = original.clone();
+| Type | Generated Code | Description |
+|------|----------------|-------------|
+| Class | `clone(): ClassName` | Instance method creating a new instance with copied fields |
+| Enum | `cloneEnumName(value: EnumName): EnumName` | Standalone function (enums are primitives, returns value as-is) |
+| Interface | `cloneInterfaceName(value: InterfaceName): InterfaceName` | Standalone function creating a new object literal |
+| Type Alias | `cloneTypeName(value: TypeName): TypeName` | Standalone function with spread copy for objects |
 
-console.log(copy.x, copy.y); // 10, 20
-console.log(original === copy); // false (different instances)
-``` ## How It Works
- The Clone macro:
- 1. Creates a new instance of the class
- 2. Passes all field values to the constructor
- 3. Returns the new instance
- This creates a **shallow clone** - primitive values are copied, but object references remain the same.
- ## With Nested Objects
- **Before:**
-```
-/** @derive(Clone) */
-class User {
-    name: string;
-    address: { city: string; zip: string };
+## Configuration
 
-    constructor(name: string, address: { city: string; zip: string }) {
-        this.name = name;
-        this.address = address;
-    }
-}
-```  
-**After:**
-```
-class User {
-    name: string;
-    address: { city: string; zip: string };
+The `functionNamingStyle` option in `macroforge.json` controls naming:
+- `"suffix"` (default): Suffixes with type name (e.g., `cloneMyType`)
+- `"prefix"`: Prefixes with type name (e.g., `myTypeClone`)
+- `"generic"`: Uses TypeScript generics (e.g., `clone<T extends MyType>`)
+- `"namespace"`: Legacy namespace wrapping
 
-    constructor(name: string, address: { city: string; zip: string }) {
-        this.name = name;
-        this.address = address;
-    }
+## Cloning Strategy
 
-    clone(): User {
-        const cloned = Object.create(Object.getPrototypeOf(this));
-        cloned.name = this.name;
-        cloned.address = this.address;
-        return cloned;
-    }
-}
-``` ```
-const original = new User("Alice", { city: "NYC", zip: "10001" });
-const copy = original.clone();
+The generated clone performs a **shallow copy** of all fields:
 
-// The address object is the same reference
-console.log(original.address === copy.address); // true
+- **Primitives** (`string`, `number`, `boolean`): Copied by value
+- **Objects**: Reference is copied (not deep cloned)
+- **Arrays**: Reference is copied (not deep cloned)
 
-// Modifying the copy's address affects the original
-copy.address.city = "LA";
-console.log(original.address.city); // "LA"
-``` For deep cloning of nested objects, you would need to implement custom clone methods or use a deep clone utility.
- ## Combining with PartialEq
- Clone works well with PartialEq for creating independent copies that compare as equal:
- **Source:**
-```
-/** @derive(Clone, PartialEq) */
-class Point {
-  x: number;
-  y: number;
+For deep cloning of nested objects, those objects should also derive `Clone`
+and the caller should clone them explicitly.
 
-  constructor(x: number, y: number) {
-    this.x = x;
-    this.y = y;
-  }
-}
-```  ```
-const original = new Point(10, 20);
-const copy = original.clone();
+## Example
 
-console.log(original === copy);       // false (different instances)
-console.log(original.equals(copy));   // true (same values)
-``` ## Interface Support
- Clone also works with interfaces. For interfaces, a namespace is generated with a `clone` function:
- **Before:**
-```
-/** @derive(Clone) */
-interface Point {
-    x: number;
-    y: number;
-}
-```  
-**After:**
-```
-interface Point {
+```typescript
+@derive(Clone)
+class Point {
     x: number;
     y: number;
 }
 
-export namespace Point {
-    export function clone(self: Point): Point {
-        return { x: self.x, y: self.y };
-    }
-}
-``` ```
-const original: Point = { x: 10, y: 20 };
-const copy = Point.clone(original);
+// Generated:
+// clone(): Point {
+//     const cloned = Object.create(Object.getPrototypeOf(this));
+//     cloned.x = this.x;
+//     cloned.y = this.y;
+//     return cloned;
+// }
 
-console.log(copy.x, copy.y);        // 10, 20
-console.log(original === copy);     // false (different objects)
-``` ## Enum Support
- Clone also works with enums. For enums, the clone function simply returns the value as-is, since enum values are primitives and don't need cloning:
- **Before:**
+const p1 = new Point();
+const p2 = p1.clone(); // Creates a new Point with same values
 ```
-/** @derive(Clone) */
-enum Status {
-    Active = 'active',
-    Inactive = 'inactive'
-}
-```  
-**After:**
-```
-enum Status {
-    Active = 'active',
-    Inactive = 'inactive'
-}
 
-export namespace Status {
-    export function clone(value: Status): Status {
-        return value;
-    }
-}
-``` ```
-const original = Status.Active;
-const copy = Status.clone(original);
+## Implementation Notes
 
-console.log(copy);               // "active"
-console.log(original === copy);  // true (same primitive value)
-``` ## Type Alias Support
- Clone works with type aliases. For object types, a shallow copy is created using spread:
- **Before:**
-```
-/** @derive(Clone) */
-type Point = {
-    x: number;
-    y: number;
-};
-```  
-**After:**
-```
-type Point = {
-    x: number;
-    y: number;
-};
-
-export namespace Point {
-    export function clone(value: Point): Point {
-        return { x: value.x, y: value.y };
-    }
-}
-``` ```
-const original: Point = { x: 10, y: 20 };
-const copy = Point.clone(original);
-
-console.log(copy.x, copy.y);     // 10, 20
-console.log(original === copy);  // false (different objects)
-``` For union types, the value is returned as-is (unions of primitives don't need cloning):
- **Source:**
-```
-/** @derive(Clone) */
-type ApiStatus = "loading" | "success" | "error";
-```  ```
-const status: ApiStatus = "success";
-const copy = ApiStatus.clone(status);
-console.log(copy); // "success"
-```
+- **Classes**: Uses `Object.create(Object.getPrototypeOf(this))` to preserve
+  the prototype chain, ensuring `instanceof` checks work correctly
+- **Enums**: Simply returns the value (enums are primitives in TypeScript)
+- **Interfaces/Type Aliases**: Creates new object literals with spread operator
+  for union/tuple types, or field-by-field copy for object types

package/docs/builtin-macros/debug.md

@@ -1,258 +1,52 @@
 # Debug
-  *The `Debug` macro generates a human-readable `toString()` method for TypeScript classes, interfaces, enums, and type aliases.*
- ## Basic Usage
- **Before:**
-```
-/** @derive(Debug) */
-class User {
-    name: string;
-    age: number;
-
-    constructor(name: string, age: number) {
-        this.name = name;
-        this.age = age;
-    }
-}
-```  
-**After:**
-```
-class User {
-    name: string;
-    age: number;
 
-    constructor(name: string, age: number) {
-        this.name = name;
-        this.age = age;
-    }
+The `Debug` macro generates a human-readable `toString()` method for
+TypeScript classes, interfaces, enums, and type aliases.
 
-    toString(): string {
-        const parts: string[] = [];
-        parts.push('name: ' + this.name);
-        parts.push('age: ' + this.age);
-        return 'User { ' + parts.join(', ') + ' }';
-    }
-}
-``` ```
-const user = new User("Alice", 30);
-console.log(user.toString());
-// Output: User { name: Alice, age: 30 }
-``` ## Field Options
- Use the `@debug` field decorator to customize behavior:
- ### Renaming Fields
- **Before:**
-```
-/** @derive(Debug) */
-class User {
-    /** @debug({ rename: "userId" }) */
-    id: number;
+## Generated Output
 
-    name: string;
+**Classes**: Generates an instance method returning a string
+like `"ClassName { field1: value1, field2: value2 }"`.
 
-    constructor(id: number, name: string) {
-        this.id = id;
-        this.name = name;
-    }
-}
-```  
-**After:**
-```
-class User {
-    id: number;
+**Enums**: Generates a standalone function `toStringEnumName(value)` that performs
+reverse lookup on numeric enums.
 
-    name: string;
+**Interfaces**: Generates a standalone function `toStringInterfaceName(value)`.
 
-    constructor(id: number, name: string) {
-        this.id = id;
-        this.name = name;
-    }
-
-    toString(): string {
-        const parts: string[] = [];
-        parts.push('userId: ' + this.id);
-        parts.push('name: ' + this.name);
-        return 'User { ' + parts.join(', ') + ' }';
-    }
-}
-``` ```
-const user = new User(42, "Alice");
-console.log(user.toString());
-// Output: User { userId: 42, name: Alice }
-``` ### Skipping Fields
- Use `skip: true` to exclude sensitive fields from the output:
- **Before:**
-```
-/** @derive(Debug) */
-class User {
-    name: string;
-    email: string;
-
-    /** @debug({ skip: true }) */
-    password: string;
-
-    /** @debug({ skip: true }) */
-    authToken: string;
-
-    constructor(name: string, email: string, password: string, authToken: string) {
-        this.name = name;
-        this.email = email;
-        this.password = password;
-        this.authToken = authToken;
-    }
-}
-```  
-**After:**
-```
-class User {
-    name: string;
-    email: string;
+**Type Aliases**: Generates a standalone function using JSON.stringify for
+complex types, or field enumeration for object types.
 
-    password: string;
+## Configuration
 
-    authToken: string;
+The `functionNamingStyle` option in `macroforge.json` controls naming:
+- `"suffix"` (default): Suffixes with type name (e.g., `toStringMyType`)
+- `"prefix"`: Prefixes with type name (e.g., `myTypeToString`)
+- `"generic"`: Uses TypeScript generics (e.g., `toString<T extends MyType>`)
+- `"namespace"`: Legacy namespace wrapping
 
-    constructor(name: string, email: string, password: string, authToken: string) {
-        this.name = name;
-        this.email = email;
-        this.password = password;
-        this.authToken = authToken;
-    }
+## Field-Level Options
 
-    toString(): string {
-        const parts: string[] = [];
-        parts.push('name: ' + this.name);
-        parts.push('email: ' + this.email);
-        return 'User { ' + parts.join(', ') + ' }';
-    }
-}
-``` ```
-const user = new User("Alice", "alice@example.com", "secret", "tok_xxx");
-console.log(user.toString());
-// Output: User { name: Alice, email: alice@example.com }
-// Note: password and authToken are not included
-```  **Security Always skip sensitive fields like passwords, tokens, and API keys to prevent accidental logging. ## Combining Options
- ****Source:**
-```
-/** @derive(Debug) */
-class ApiResponse {
-  /** @debug({ rename: "statusCode" }) */
-  status: number;
+The `@debug` decorator supports:
 
-  data: unknown;
+- `skip` - Exclude the field from debug output
+- `rename = "label"` - Use a custom label instead of the field name
 
-  /** @debug({ skip: true }) */
-  internalMetadata: Record<string, unknown>;
-}
-```  ## All Options
- | Option | Type | Description |
-| --- | --- | --- |
-| `rename` | `string` | Display a different name in the output |
-| `skip` | `boolean` | Exclude this field from the output |
- ## Interface Support
- Debug also works with interfaces. For interfaces, a namespace is generated with a `toString` function:
- **Before:**
-```
-/** @derive(Debug) */
-interface Status {
-    active: boolean;
-    message: string;
-}
-```  
-**After:**
-```
-interface Status {
-    active: boolean;
-    message: string;
-}
+## Example
 
-export namespace Status {
-    export function toString(self: Status): string {
-        const parts: string[] = [];
-        parts.push('active: ' + self.active);
-        parts.push('message: ' + self.message);
-        return 'Status { ' + parts.join(', ') + ' }';
-    }
-}
-``` ```
-const status: Status = { active: true, message: "OK" };
-console.log(Status.toString(status));
-// Output: Status { active: true, message: OK }
-``` ## Enum Support
- Debug also works with enums. For enums, a namespace is generated with a `toString` function that displays the enum name and variant:
- **Before:**
-```
-/** @derive(Debug) */
-enum Priority {
-    Low = 1,
-    Medium = 2,
-    High = 3
-}
-```  
-**After:**
-```
-enum Priority {
-    Low = 1,
-    Medium = 2,
-    High = 3
-}
+```typescript
+@derive(Debug)
+class User {
+    @debug(rename = "id")
+    userId: number;
 
-export namespace Priority {
-    export function toString(value: Priority): string {
-        const key = Priority[value as unknown as keyof typeof Priority];
-        if (key !== undefined) {
-            return 'Priority.' + key;
-        }
-        return 'Priority(' + String(value) + ')';
-    }
-}
-``` ```
-console.log(Priority.toString(Priority.High));
-// Output: Priority.High
+    @debug(skip)
+    password: string;
 
-console.log(Priority.toString(Priority.Low));
-// Output: Priority.Low
-``` Works with both numeric and string enums:
- **Source:**
-```
-/** @derive(Debug) */
-enum Status {
-  Active = "active",
-  Inactive = "inactive",
+    email: string;
 }
-```  ## Type Alias Support
- Debug works with type aliases. For object types, fields are displayed similar to interfaces:
- **Before:**
-```
-/** @derive(Debug) */
-type Point = {
-    x: number;
-    y: number;
-};
-```  
-**After:**
-```
-type Point = {
-    x: number;
-    y: number;
-};
 
-export namespace Point {
-    export function toString(value: Point): string {
-        const parts: string[] = [];
-        parts.push('x: ' + value.x);
-        parts.push('y: ' + value.y);
-        return 'Point { ' + parts.join(', ') + ' }';
-    }
-}
-``` ```
-const point: Point = { x: 10, y: 20 };
-console.log(Point.toString(point));
-// Output: Point { x: 10, y: 20 }
-``` For union types, the value is displayed using JSON.stringify:
- **Source:**
+// Generated:
+// toString(): string {
+//     return "User { id: " + this.userId + ", email: " + this.email + " }";
+// }
 ```
-/** @derive(Debug) */
-type ApiStatus = "loading" | "success" | "error";
-```  ```
-console.log(ApiStatus.toString("success"));
-// Output: ApiStatus("success")
-```