@macroforge/mcp-server 0.1.40 → 0.1.49

package/docs/builtin-macros/hash.md

@@ -99,48 +99,6 @@ export function userEquals(a: User, b: User): boolean {
 }
 ```
 
-Generated output:
-
-```typescript
-class User {
-    id: number;
-    name: string;
-
-    cachedScore: number;
-
-    static hashCode(value: User): number {
-        return userHashCode(value);
-    }
-
-    static equals(a: User, b: User): boolean {
-        return userEquals(a, b);
-    }
-}
-
-export function userHashCode(value: User): number {
-    let hash = 17;
-    hash =
-        (hash * 31 +
-            (Number.isInteger(value.id)
-                ? value.id | 0
-                : value.id
-                      .toString()
-                      .split('')
-                      .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
-        0;
-    hash =
-        (hash * 31 +
-            (value.name ?? '').split('').reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0)) |
-        0;
-    return hash;
-}
-
-export function userEquals(a: User, b: User): boolean {
-    if (a === b) return true;
-    return a.id === b.id && a.name === b.name && a.cachedScore === b.cachedScore;
-}
-```
-
 ## Hash Contract
 
 Objects that are equal (`PartialEq`) should produce the same hash code.

package/docs/builtin-macros/macros-overview/detailed-documentation.md

@@ -0,0 +1,13 @@
+## Detailed Documentation
+
+Each macro has its own options and behaviors:
+
+*   [**Debug**](../docs/builtin-macros/debug) - Customizable field renaming and skipping
+*   [**Clone**](../docs/builtin-macros/clone) - Deep copying for all field types
+*   [**Default**](../docs/builtin-macros/default) - Default value generation with field attributes
+*   [**Hash**](../docs/builtin-macros/hash) - Hash code generation for use in maps and sets
+*   [**PartialEq**](../docs/builtin-macros/partial-eq) - Value-based equality comparison
+*   [**Ord**](../docs/builtin-macros/ord) - Total ordering for sorting
+*   [**PartialOrd**](../docs/builtin-macros/partial-ord) - Partial ordering comparison
+*   [**Serialize**](../docs/builtin-macros/serialize) - JSON serialization with serde-style options
+*   [**Deserialize**](../docs/builtin-macros/deserialize) - JSON deserialization with validation

package/docs/builtin-macros/macros-overview/enum-support.md

@@ -0,0 +1,30 @@
+## Enum Support
+
+All built-in macros work with enums. For enums, methods are generated as functions in a namespace with the same name:
+
+TypeScript
+
+```
+/** @derive(Debug, Clone, PartialEq, Serialize, Deserialize) */
+enum Status {
+  Active = "active",
+  Inactive = "inactive",
+  Pending = "pending",
+}
+
+// Generated namespace:
+// namespace Status {
+//   export function toString(value: Status): string { ... }
+//   export function clone(value: Status): Status { ... }
+//   export function equals(a: Status, b: Status): boolean { ... }
+//   export function hashCode(value: Status): number { ... }
+//   export function toJSON(value: Status): string | number { ... }
+//   export function fromJSON(data: unknown): Status { ... }
+// }
+
+// Use the namespace functions
+console.log(Status.toString(Status.Active));     // "Status.Active"
+console.log(Status.equals(Status.Active, Status.Active)); // true
+const json = Status.toJSON(Status.Pending);      // "pending"
+const parsed = Status.fromJSON("active");        // Status.Active
+```

package/docs/builtin-macros/macros-overview/interface-support.md

@@ -0,0 +1,28 @@
+## Interface Support
+
+All built-in macros work with interfaces. For interfaces, methods are generated as functions in a namespace with the same name, using `self` as the first parameter:
+
+TypeScript
+
+```
+/** @derive(Debug, Clone, PartialEq) */
+interface Point {
+  x: number;
+  y: number;
+}
+
+// Generated namespace:
+// namespace Point {
+//   export function toString(self: Point): string { ... }
+//   export function clone(self: Point): Point { ... }
+//   export function equals(self: Point, other: Point): boolean { ... }
+//   export function hashCode(self: Point): number { ... }
+// }
+
+const point: Point = { x: 10, y: 20 };
+
+// Use the namespace functions
+console.log(Point.toString(point));     // "Point { x: 10, y: 20 }"
+const copy = Point.clone(point);        // { x: 10, y: 20 }
+console.log(Point.equals(point, copy)); // true
+```

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

@@ -0,0 +1,36 @@
+# Built-in Macros
+
+Macroforge comes with built-in derive macros that cover the most common code generation needs. All macros work with classes, interfaces, enums, and type aliases.
+
+## Overview
+
+| Macro                                               | Generates                                 | Description                             |
+| --------------------------------------------------- | ----------------------------------------- | --------------------------------------- |
+| [`Debug`](../docs/builtin-macros/debug)             | `toString(): string`                      | Human-readable string representation    |
+| [`Clone`](../docs/builtin-macros/clone)             | `clone(): T`                              | Creates a deep copy of the object       |
+| [`Default`](../docs/builtin-macros/default)         | `static default(): T`                     | Creates an instance with default values |
+| [`Hash`](../docs/builtin-macros/hash)               | `hashCode(): number`                      | Generates a hash code for the object    |
+| [`PartialEq`](../docs/builtin-macros/partial-eq)    | `equals(other: T): boolean`               | Value equality comparison               |
+| [`Ord`](../docs/builtin-macros/ord)                 | `compare(other: T): number`               | Total ordering comparison (-1, 0, 1)    |
+| [`PartialOrd`](../docs/builtin-macros/partial-ord)  | `partialCompare(other: T): number | null` | Partial ordering comparison             |
+| [`Serialize`](../docs/builtin-macros/serialize)     | `toJSON(): Record<string, unknown>`       | JSON serialization with type handling   |
+| [`Deserialize`](../docs/builtin-macros/deserialize) | `static fromJSON(data: unknown): T`       | JSON deserialization with validation    |
+
+## Using Built-in Macros
+
+Built-in macros don't require imports. Just use them with `@derive`:
+
+TypeScript
+
+```
+/** @derive(Debug, Clone, PartialEq) */
+class User {
+  name: string;
+  age: number;
+
+  constructor(name: string, age: number) {
+    this.name = name;
+    this.age = age;
+  }
+}
+```

package/docs/builtin-macros/macros-overview/type-alias-support.md

@@ -0,0 +1,62 @@
+## Type Alias Support
+
+All built-in macros work with type aliases. For object type aliases, field-aware methods are generated in a namespace:
+
+TypeScript
+
+```
+/** @derive(Debug, Clone, PartialEq, Serialize, Deserialize) */
+type Point = {
+  x: number;
+  y: number;
+};
+
+// Generated namespace:
+// namespace Point {
+//   export function toString(value: Point): string { ... }
+//   export function clone(value: Point): Point { ... }
+//   export function equals(a: Point, b: Point): boolean { ... }
+//   export function hashCode(value: Point): number { ... }
+//   export function toJSON(value: Point): Record<string, unknown> { ... }
+//   export function fromJSON(data: unknown): Point { ... }
+// }
+
+const point: Point = { x: 10, y: 20 };
+console.log(Point.toString(point));     // "Point { x: 10, y: 20 }"
+const copy = Point.clone(point);        // { x: 10, y: 20 }
+console.log(Point.equals(point, copy)); // true
+```
+
+Union type aliases also work, using JSON-based implementations:
+
+TypeScript
+
+```
+/** @derive(Debug, PartialEq) */
+type ApiStatus = "loading" | "success" | "error";
+
+const status: ApiStatus = "success";
+console.log(ApiStatus.toString(status)); // "ApiStatus(\\"success\\")"
+console.log(ApiStatus.equals("success", "success")); // true
+```
+
+## Combining Macros
+
+All macros can be used together. They don't conflict and each generates independent methods:
+
+TypeScript
+
+```
+const user = new User("Alice", 30);
+
+// Debug
+console.log(user.toString());
+// "User { name: Alice, age: 30 }"
+
+// Clone
+const copy = user.clone();
+console.log(copy.name); // "Alice"
+
+// Eq
+console.log(user.equals(copy)); // true
+```

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

@@ -1,132 +1,173 @@
 # Built-in Macros
- *Macroforge comes with built-in derive macros that cover the most common code generation needs. All macros work with classes, interfaces, enums, and type aliases.*
- ## Overview
- | Macro | Generates | Description |
-| --- | --- | --- |
-| [`Debug`](../docs/builtin-macros/debug) | `toString(): string` | Human-readable string representation |
-| [`Clone`](../docs/builtin-macros/clone) | `clone(): T` | Creates a deep copy of the object |
-| [`Default`](../docs/builtin-macros/default) | `static default(): T` | Creates an instance with default values |
-| [`Hash`](../docs/builtin-macros/hash) | `hashCode(): number` | Generates a hash code for the object |
-| [`PartialEq`](../docs/builtin-macros/partial-eq) | `equals(other: T): boolean` | Value equality comparison |
-| [`Ord`](../docs/builtin-macros/ord) | `compare(other: T): number` | Total ordering comparison (-1, 0, 1) |
-| [`PartialOrd`](../docs/builtin-macros/partial-ord) | `partialCompare(other: T): number | null` | Partial ordering comparison |
-| [`Serialize`](../docs/builtin-macros/serialize) | `toJSON(): Record<string, unknown>` | JSON serialization with type handling |
-| [`Deserialize`](../docs/builtin-macros/deserialize) | `static fromJSON(data: unknown): T` | JSON deserialization with validation |
- ## Using Built-in Macros
- Built-in macros don't require imports. Just use them with `@derive`:
- ```
-/** @derive(Debug, Clone, PartialEq) */
-class User &#123;
-  name: string;
-  age: number;
-
-  constructor(name: string, age: number) &#123;
-    this.name = name;
-    this.age = age;
-  &#125;
-&#125;
-``` ## Interface Support
- All built-in macros work with interfaces. For interfaces, methods are generated as functions in a namespace with the same name, using `self` as the first parameter:
- ```
-/** @derive(Debug, Clone, PartialEq) */
-interface Point &#123;
-  x: number;
-  y: number;
-&#125;
-
-// Generated namespace:
-// namespace Point &#123;
-//   export function toString(self: Point): string &#123; ... &#125;
-//   export function clone(self: Point): Point &#123; ... &#125;
-//   export function equals(self: Point, other: Point): boolean &#123; ... &#125;
-//   export function hashCode(self: Point): number &#123; ... &#125;
-// &#125;
-
-const point: Point = &#123; x: 10, y: 20 &#125;;
-
-// Use the namespace functions
-console.log(Point.toString(point));     // "Point &#123; x: 10, y: 20 &#125;"
-const copy = Point.clone(point);        // &#123; x: 10, y: 20 &#125;
-console.log(Point.equals(point, copy)); // true
-``` ## Enum Support
- All built-in macros work with enums. For enums, methods are generated as functions in a namespace with the same name:
- ```
-/** @derive(Debug, Clone, PartialEq, Serialize, Deserialize) */
-enum Status &#123;
-  Active = "active",
-  Inactive = "inactive",
-  Pending = "pending",
-&#125;
-
-// Generated namespace:
-// namespace Status &#123;
-//   export function toString(value: Status): string &#123; ... &#125;
-//   export function clone(value: Status): Status &#123; ... &#125;
-//   export function equals(a: Status, b: Status): boolean &#123; ... &#125;
-//   export function hashCode(value: Status): number &#123; ... &#125;
-//   export function toJSON(value: Status): string | number &#123; ... &#125;
-//   export function fromJSON(data: unknown): Status &#123; ... &#125;
-// &#125;
-
-// Use the namespace functions
-console.log(Status.toString(Status.Active));     // "Status.Active"
-console.log(Status.equals(Status.Active, Status.Active)); // true
-const json = Status.toJSON(Status.Pending);      // "pending"
-const parsed = Status.fromJSON("active");        // Status.Active
-``` ## Type Alias Support
- All built-in macros work with type aliases. For object type aliases, field-aware methods are generated in a namespace:
- ```
-/** @derive(Debug, Clone, PartialEq, Serialize, Deserialize) */
-type Point = &#123;
-  x: number;
-  y: number;
-&#125;;
-
-// Generated namespace:
-// namespace Point &#123;
-//   export function toString(value: Point): string &#123; ... &#125;
-//   export function clone(value: Point): Point &#123; ... &#125;
-//   export function equals(a: Point, b: Point): boolean &#123; ... &#125;
-//   export function hashCode(value: Point): number &#123; ... &#125;
-//   export function toJSON(value: Point): Record&#x3C;string, unknown> &#123; ... &#125;
-//   export function fromJSON(data: unknown): Point &#123; ... &#125;
-// &#125;
-
-const point: Point = &#123; x: 10, y: 20 &#125;;
-console.log(Point.toString(point));     // "Point &#123; x: 10, y: 20 &#125;"
-const copy = Point.clone(point);        // &#123; x: 10, y: 20 &#125;
-console.log(Point.equals(point, copy)); // true
-``` Union type aliases also work, using JSON-based implementations:
- ```
-/** @derive(Debug, PartialEq) */
-type ApiStatus = "loading" | "success" | "error";
-
-const status: ApiStatus = "success";
-console.log(ApiStatus.toString(status)); // "ApiStatus(\\"success\\")"
-console.log(ApiStatus.equals("success", "success")); // true
-``` ## Combining Macros
- All macros can be used together. They don't conflict and each generates independent methods:
- ```
-const user = new User("Alice", 30);
-
-// Debug
+
+Macroforge comes with built-in derive macros that cover the most common code generation needs. All macros work with classes, interfaces, enums, and type aliases.
+
+## Overview
+
+| Macro                                               | Generates                                 | Description                             |
+| --------------------------------------------------- | ----------------------------------------- | --------------------------------------- |
+| [`Debug`](../docs/builtin-macros/debug)             | `toString(): string`                      | Human-readable string representation    |
+| [`Clone`](../docs/builtin-macros/clone)             | `clone(): T`                              | Creates a deep copy of the object       |
+| [`Default`](../docs/builtin-macros/default)         | `static default(): T`                     | Creates an instance with default values |
+| [`Hash`](../docs/builtin-macros/hash)               | `hashCode(): number`                      | Generates a hash code for the object    |
+| [`PartialEq`](../docs/builtin-macros/partial-eq)    | `equals(other: T): boolean`               | Value equality comparison               |
+| [`Ord`](../docs/builtin-macros/ord)                 | `compare(other: T): number`               | Total ordering comparison (-1, 0, 1)    |
+| [`PartialOrd`](../docs/builtin-macros/partial-ord)  | `partialCompare(other: T): number &#124; null` | Partial ordering comparison             |
+| [`Serialize`](../docs/builtin-macros/serialize)     | `toJSON(): Record<string, unknown>`       | JSON serialization with type handling   |
+| [`Deserialize`](../docs/builtin-macros/deserialize) | `static fromJSON(data: unknown): T`       | JSON deserialization with validation    |
+
+## Using Built-in Macros
+
+Built-in macros don't require imports. Just use them with `@derive`:
+
+TypeScript
+
+```
+/** @derive(Debug, Clone, PartialEq) */
+class User {
+  name: string;
+  age: number;
+
+  constructor(name: string, age: number) {
+    this.name = name;
+    this.age = age;
+  }
+}
+```
+
+## Interface Support
+
+All built-in macros work with interfaces. For interfaces, methods are generated as functions in a namespace with the same name, using `self` as the first parameter:
+
+TypeScript
+
+```
+/** @derive(Debug, Clone, PartialEq) */
+interface Point {
+  x: number;
+  y: number;
+}
+
+// Generated namespace:
+// namespace Point {
+//   export function toString(self: Point): string { ... }
+//   export function clone(self: Point): Point { ... }
+//   export function equals(self: Point, other: Point): boolean { ... }
+//   export function hashCode(self: Point): number { ... }
+// }
+
+const point: Point = { x: 10, y: 20 };
+
+// Use the namespace functions
+console.log(Point.toString(point));     // "Point { x: 10, y: 20 }"
+const copy = Point.clone(point);        // { x: 10, y: 20 }
+console.log(Point.equals(point, copy)); // true
+```
+
+## Enum Support
+
+All built-in macros work with enums. For enums, methods are generated as functions in a namespace with the same name:
+
+TypeScript
+
+```
+/** @derive(Debug, Clone, PartialEq, Serialize, Deserialize) */
+enum Status {
+  Active = "active",
+  Inactive = "inactive",
+  Pending = "pending",
+}
+
+// Generated namespace:
+// namespace Status {
+//   export function toString(value: Status): string { ... }
+//   export function clone(value: Status): Status { ... }
+//   export function equals(a: Status, b: Status): boolean { ... }
+//   export function hashCode(value: Status): number { ... }
+//   export function toJSON(value: Status): string | number { ... }
+//   export function fromJSON(data: unknown): Status { ... }
+// }
+
+// Use the namespace functions
+console.log(Status.toString(Status.Active));     // "Status.Active"
+console.log(Status.equals(Status.Active, Status.Active)); // true
+const json = Status.toJSON(Status.Pending);      // "pending"
+const parsed = Status.fromJSON("active");        // Status.Active
+```
+
+## Type Alias Support
+
+All built-in macros work with type aliases. For object type aliases, field-aware methods are generated in a namespace:
+
+TypeScript
+
+```
+/** @derive(Debug, Clone, PartialEq, Serialize, Deserialize) */
+type Point = {
+  x: number;
+  y: number;
+};
+
+// Generated namespace:
+// namespace Point {
+//   export function toString(value: Point): string { ... }
+//   export function clone(value: Point): Point { ... }
+//   export function equals(a: Point, b: Point): boolean { ... }
+//   export function hashCode(value: Point): number { ... }
+//   export function toJSON(value: Point): Record<string, unknown> { ... }
+//   export function fromJSON(data: unknown): Point { ... }
+// }
+
+const point: Point = { x: 10, y: 20 };
+console.log(Point.toString(point));     // "Point { x: 10, y: 20 }"
+const copy = Point.clone(point);        // { x: 10, y: 20 }
+console.log(Point.equals(point, copy)); // true
+```
+
+Union type aliases also work, using JSON-based implementations:
+
+TypeScript
+
+```
+/** @derive(Debug, PartialEq) */
+type ApiStatus = "loading" | "success" | "error";
+
+const status: ApiStatus = "success";
+console.log(ApiStatus.toString(status)); // "ApiStatus(\\"success\\")"
+console.log(ApiStatus.equals("success", "success")); // true
+```
+
+## Combining Macros
+
+All macros can be used together. They don't conflict and each generates independent methods:
+
+TypeScript
+
+```
+const user = new User("Alice", 30);
+
+// Debug
 console.log(user.toString());
-// "User &#123; name: Alice, age: 30 &#125;"
-
-// Clone
-const copy = user.clone();
-console.log(copy.name); // "Alice"
-
-// Eq
-console.log(user.equals(copy)); // true
-``` ## Detailed Documentation
- Each macro has its own options and behaviors:
- - [**Debug**](../docs/builtin-macros/debug) - Customizable field renaming and skipping
- - [**Clone**](../docs/builtin-macros/clone) - Deep copying for all field types
- - [**Default**](../docs/builtin-macros/default) - Default value generation with field attributes
- - [**Hash**](../docs/builtin-macros/hash) - Hash code generation for use in maps and sets
- - [**PartialEq**](../docs/builtin-macros/partial-eq) - Value-based equality comparison
- - [**Ord**](../docs/builtin-macros/ord) - Total ordering for sorting
- - [**PartialOrd**](../docs/builtin-macros/partial-ord) - Partial ordering comparison
- - [**Serialize**](../docs/builtin-macros/serialize) - JSON serialization with serde-style options
- - [**Deserialize**](../docs/builtin-macros/deserialize) - JSON deserialization with validation
+// "User { name: Alice, age: 30 }"
+
+// Clone
+const copy = user.clone();
+console.log(copy.name); // "Alice"
+
+// Eq
+console.log(user.equals(copy)); // true
+```
+
+## Detailed Documentation
+
+Each macro has its own options and behaviors:
+
+*   [**Debug**](../docs/builtin-macros/debug) - Customizable field renaming and skipping
+*   [**Clone**](../docs/builtin-macros/clone) - Deep copying for all field types
+*   [**Default**](../docs/builtin-macros/default) - Default value generation with field attributes
+*   [**Hash**](../docs/builtin-macros/hash) - Hash code generation for use in maps and sets
+*   [**PartialEq**](../docs/builtin-macros/partial-eq) - Value-based equality comparison
+*   [**Ord**](../docs/builtin-macros/ord) - Total ordering for sorting
+*   [**PartialOrd**](../docs/builtin-macros/partial-ord) - Partial ordering comparison
+*   [**Serialize**](../docs/builtin-macros/serialize) - JSON serialization with serde-style options
+*   [**Deserialize**](../docs/builtin-macros/deserialize) - JSON deserialization with validation

package/docs/builtin-macros/ord.md

@@ -85,31 +85,6 @@ export function versionCompare(a: Version, b: Version): number {
 }
 ```
 
-Generated output:
-
-```typescript
-class Version {
-    major: number;
-    minor: number;
-    patch: number;
-
-    static compareTo(a: Version, b: Version): number {
-        return versionCompare(a, b);
-    }
-}
-
-export function versionCompare(a: Version, b: Version): number {
-    if (a === b) return 0;
-    const cmp0 = a.major < b.major ? -1 : a.major > b.major ? 1 : 0;
-    if (cmp0 !== 0) return cmp0;
-    const cmp1 = a.minor < b.minor ? -1 : a.minor > b.minor ? 1 : 0;
-    if (cmp1 !== 0) return cmp1;
-    const cmp2 = a.patch < b.patch ? -1 : a.patch > b.patch ? 1 : 0;
-    if (cmp2 !== 0) return cmp2;
-    return 0;
-}
-```
-
 ## Ord vs PartialOrd
 
 - Use **Ord** when all values are comparable (total ordering)

package/docs/builtin-macros/partial-eq.md

@@ -90,48 +90,6 @@ export function userHashCode(value: User): number {
 }
 ```
 
-Generated output:
-
-```typescript
-class User {
-    id: number;
-    name: string;
-
-    cachedScore: number;
-
-    static equals(a: User, b: User): boolean {
-        return userEquals(a, b);
-    }
-
-    static hashCode(value: User): number {
-        return userHashCode(value);
-    }
-}
-
-export function userEquals(a: User, b: User): boolean {
-    if (a === b) return true;
-    return a.id === b.id && a.name === b.name;
-}
-
-export function userHashCode(value: User): number {
-    let hash = 17;
-    hash =
-        (hash * 31 +
-            (Number.isInteger(value.id)
-                ? value.id | 0
-                : value.id
-                      .toString()
-                      .split('')
-                      .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
-        0;
-    hash =
-        (hash * 31 +
-            (value.name ?? '').split('').reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0)) |
-        0;
-    return hash;
-}
-```
-
 ## Equality Contract
 
 When implementing `PartialEq`, consider also implementing `Hash`:
@@ -192,45 +150,3 @@ export function userHashCode(value: User): number {
     return hash;
 }
 ```
-
-Generated output:
-
-```typescript
-class User {
-    id: number;
-    name: string;
-
-    cachedScore: number;
-
-    static equals(a: User, b: User): boolean {
-        return userEquals(a, b);
-    }
-
-    static hashCode(value: User): number {
-        return userHashCode(value);
-    }
-}
-
-export function userEquals(a: User, b: User): boolean {
-    if (a === b) return true;
-    return a.id === b.id && a.name === b.name;
-}
-
-export function userHashCode(value: User): number {
-    let hash = 17;
-    hash =
-        (hash * 31 +
-            (Number.isInteger(value.id)
-                ? value.id | 0
-                : value.id
-                      .toString()
-                      .split('')
-                      .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
-        0;
-    hash =
-        (hash * 31 +
-            (value.name ?? '').split('').reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0)) |
-        0;
-    return hash;
-}
-```