@macroforge/mcp-server 0.1.17 → 0.1.21

package/docs/builtin-macros/hash.md

@@ -4,18 +4,9 @@
 
 ## Basic Usage
 
-```typescript
-/** @derive(Hash) */
-class Point {
-  x: number;
-  y: number;
-
-  constructor(x: number, y: number) {
-    this.x = x;
-    this.y = y;
-  }
-}
+<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
 
+```typescript
 const p1 = new Point(10, 20);
 const p2 = new Point(10, 20);
 const p3 = new Point(5, 5);
@@ -25,19 +16,6 @@ console.log(p2.hashCode()); // Same hash (equal values = equal hash)
 console.log(p3.hashCode()); // Different hash
 ```
 
-## Generated Code
-
-The Hash macro generates a method that combines field hashes using the FNV-1a style algorithm:
-
-```typescript
-hashCode(): number {
-    let hash = 17;
-    hash = (hash * 31 + (Number.isInteger(this.x) ? this.x | 0 : this.x.toString().split('').reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) | 0;
-    hash = (hash * 31 + (Number.isInteger(this.y) ? this.y | 0 : this.y.toString().split('').reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) | 0;
-    return hash;
-}
-```
-
 ## Hash Algorithm
 
 The generated hash function uses the following algorithm for different types:
@@ -68,22 +46,9 @@ The generated hash function uses the following algorithm for different types:
 
 Use `@hash(skip)` to exclude a field from hash computation:
 
-```typescript
-/** @derive(Hash) */
-class User {
-  id: number;
-  name: string;
-
-  /** @hash(skip) */
-  lastLogin: Date;  // Not included in hash
-
-  constructor(id: number, name: string, lastLogin: Date) {
-    this.id = id;
-    this.name = name;
-    this.lastLogin = lastLogin;
-  }
-}
+<MacroExample before={data.examples.skip.before} after={data.examples.skip.after} />
 
+```typescript
 const user1 = new User(1, "Alice", new Date("2024-01-01"));
 const user2 = new User(1, "Alice", new Date("2024-12-01"));
 
@@ -94,8 +59,7 @@ console.log(user1.hashCode() === user2.hashCode()); // true (lastLogin is skippe
 
 Hash is often used together with PartialEq. Objects that are equal should have the same hash code:
 
-```typescript
-/** @derive(Hash, PartialEq) */
+<InteractiveMacro code={`/** @derive(Hash, PartialEq) */
 class Product {
   sku: string;
   name: string;
@@ -104,8 +68,9 @@ class Product {
     this.sku = sku;
     this.name = name;
   }
-}
+}`} />
 
+```typescript
 const p1 = new Product("ABC123", "Widget");
 const p2 = new Product("ABC123", "Widget");
 
@@ -118,23 +83,9 @@ console.log(p1.hashCode() === p2.hashCode());     // true
 
 Hash also works with interfaces. For interfaces, a namespace is generated with a `hashCode` function:
 
-```typescript
-/** @derive(Hash) */
-interface Point {
-  x: number;
-  y: number;
-}
-
-// Generated:
-// export namespace Point {
-//   export function hashCode(self: Point): number {
-//     let hash = 17;
-//     hash = (hash * 31 + (self.x | 0)) | 0;
-//     hash = (hash * 31 + (self.y | 0)) | 0;
-//     return hash;
-//   }
-// }
+<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
 
+```typescript
 const p: Point = { x: 10, y: 20 };
 console.log(Point.hashCode(p)); // numeric hash value
 ```
@@ -143,28 +94,9 @@ console.log(Point.hashCode(p)); // numeric hash value
 
 Hash works with enums. For string enums, it hashes the string value; for numeric enums, it uses the numeric value directly:
 
-```typescript
-/** @derive(Hash) */
-enum Status {
-  Active = "active",
-  Inactive = "inactive",
-  Pending = "pending",
-}
-
-// Generated:
-// export namespace Status {
-//   export function hashCode(value: Status): number {
-//     if (typeof value === "string") {
-//       let hash = 0;
-//       for (let i = 0; i < value.length; i++) {
-//         hash = (hash * 31 + value.charCodeAt(i)) | 0;
-//       }
-//       return hash;
-//     }
-//     return value | 0;
-//   }
-// }
+<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
 
+```typescript
 console.log(Status.hashCode(Status.Active));   // consistent hash
 console.log(Status.hashCode(Status.Inactive)); // different hash
 ```
@@ -173,33 +105,19 @@ console.log(Status.hashCode(Status.Inactive)); // different hash
 
 Hash works with type aliases. For object types, it hashes each field:
 
-```typescript
-/** @derive(Hash) */
-type Coordinates = {
-  lat: number;
-  lng: number;
-};
-
-// Generated:
-// export namespace Coordinates {
-//   export function hashCode(value: Coordinates): number {
-//     let hash = 17;
-//     hash = (hash * 31 + (value.lat | 0)) | 0;
-//     hash = (hash * 31 + (value.lng | 0)) | 0;
-//     return hash;
-//   }
-// }
+<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
 
+```typescript
 const loc: Coordinates = { lat: 40.7128, lng: -74.0060 };
 console.log(Coordinates.hashCode(loc));
 ```
 
 For union types, it uses JSON stringification as a fallback:
 
-```typescript
-/** @derive(Hash) */
-type Result = "success" | "error" | "pending";
+<InteractiveMacro code={`/** @derive(Hash) */
+type Result = "success" | "error" | "pending";`} />
 
+```typescript
 console.log(Result.hashCode("success")); // hash of "success" string
 console.log(Result.hashCode("error"));   // hash of "error" string
 ```

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

@@ -1,27 +1,43 @@
 # Built-in Macros
 
-*Macroforge comes with five built-in derive macros that cover the most common code generation needs. All macros work with classes, interfaces, enums, and type aliases.*
+*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
 
-| `Debug` 
+| [`Debug`]({base}/docs/builtin-macros/debug) 
 | `toString(): string` 
 | Human-readable string representation 
 
-| `Clone` 
+| [`Clone`]({base}/docs/builtin-macros/clone) 
 | `clone(): T` 
-| Creates a copy of the object 
+| Creates a deep copy of the object 
 
-| `PartialEq` 
+| [`Default`]({base}/docs/builtin-macros/default) 
+| `static default(): T` 
+| Creates an instance with default values 
+
+| [`Hash`]({base}/docs/builtin-macros/hash) 
+| `hashCode(): number` 
+| Generates a hash code for the object 
+
+| [`PartialEq`]({base}/docs/builtin-macros/partial-eq) 
 | `equals(other: T): boolean` 
 | Value equality comparison 
 
-| `Serialize` 
+| [`Ord`]({base}/docs/builtin-macros/ord) 
+| `compare(other: T): number` 
+| Total ordering comparison (-1, 0, 1) 
+
+| [`PartialOrd`]({base}/docs/builtin-macros/partial-ord) 
+| `partialCompare(other: T): number | null` 
+| Partial ordering comparison 
+
+| [`Serialize`]({base}/docs/builtin-macros/serialize) 
 | `toJSON(): Record<string, unknown>` 
 | JSON serialization with type handling 
 
-| `Deserialize` 
-| `fromJSON(data: unknown): T` 
+| [`Deserialize`]({base}/docs/builtin-macros/deserialize) 
+| `static fromJSON(data: unknown): T` 
 | JSON deserialization with validation
 
 ## Using Built-in Macros
@@ -160,10 +176,18 @@ Each macro has its own options and behaviors:
 
 - [**Debug**]({base}/docs/builtin-macros/debug) - Customizable field renaming and skipping
 
-- [**Clone**]({base}/docs/builtin-macros/clone) - Shallow copying for all field types
+- [**Clone**]({base}/docs/builtin-macros/clone) - Deep copying for all field types
+
+- [**Default**]({base}/docs/builtin-macros/default) - Default value generation with field attributes
+
+- [**Hash**]({base}/docs/builtin-macros/hash) - Hash code generation for use in maps and sets
 
 - [**PartialEq**]({base}/docs/builtin-macros/partial-eq) - Value-based equality comparison
 
+- [**Ord**]({base}/docs/builtin-macros/ord) - Total ordering for sorting
+
+- [**PartialOrd**]({base}/docs/builtin-macros/partial-ord) - Partial ordering comparison
+
 - [**Serialize**]({base}/docs/builtin-macros/serialize) - JSON serialization with serde-style options
 
 - [**Deserialize**]({base}/docs/builtin-macros/deserialize) - JSON deserialization with validation

package/docs/builtin-macros/ord.md

@@ -4,20 +4,9 @@
 
 ## Basic Usage
 
-```typescript
-/** @derive(Ord) */
-class Version {
-  major: number;
-  minor: number;
-  patch: number;
-
-  constructor(major: number, minor: number, patch: number) {
-    this.major = major;
-    this.minor = minor;
-    this.patch = patch;
-  }
-}
+<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
 
+```typescript
 const v1 = new Version(1, 0, 0);
 const v2 = new Version(1, 2, 0);
 const v3 = new Version(1, 2, 0);
@@ -27,24 +16,6 @@ console.log(v2.compareTo(v1)); // 1  (v2 > v1)
 console.log(v2.compareTo(v3)); // 0  (v2 == v3)
 ```
 
-## Generated Code
-
-The Ord macro generates a compareTo method using lexicographic field comparison:
-
-```typescript
-compareTo(other: Version): number {
-    if (this === other) return 0;
-    const typedOther = other;
-    const cmp0 = (this.major < typedOther.major ? -1 : this.major > typedOther.major ? 1 : 0);
-    if (cmp0 !== 0) return cmp0;
-    const cmp1 = (this.minor < typedOther.minor ? -1 : this.minor > typedOther.minor ? 1 : 0);
-    if (cmp1 !== 0) return cmp1;
-    const cmp2 = (this.patch < typedOther.patch ? -1 : this.patch > typedOther.patch ? 1 : 0);
-    if (cmp2 !== 0) return cmp2;
-    return 0;
-}
-```
-
 ## Comparison Logic
 
 The Ord macro compares fields in declaration order (lexicographic ordering). For each type:
@@ -83,22 +54,9 @@ Unlike `PartialOrd`, the `Ord` macro never returns `null` - it provides total or
 
 Use `@ord(skip)` to exclude a field from ordering comparison:
 
-```typescript
-/** @derive(Ord) */
-class Task {
-  priority: number;
-  name: string;
-
-  /** @ord(skip) */
-  createdAt: Date;  // Not used for ordering
-
-  constructor(priority: number, name: string, createdAt: Date) {
-    this.priority = priority;
-    this.name = name;
-    this.createdAt = createdAt;
-  }
-}
+<MacroExample before={data.examples.skip.before} after={data.examples.skip.after} />
 
+```typescript
 const t1 = new Task(1, "Bug fix", new Date("2024-01-01"));
 const t2 = new Task(1, "Bug fix", new Date("2024-12-01"));
 
@@ -109,8 +67,7 @@ console.log(t1.compareTo(t2)); // 0 (createdAt is skipped)
 
 The generated `compareTo()` method works directly with `Array.sort()`:
 
-```typescript
-/** @derive(Ord) */
+<InteractiveMacro code={`/** @derive(Ord) */
 class Score {
   points: number;
   name: string;
@@ -119,8 +76,9 @@ class Score {
     this.points = points;
     this.name = name;
   }
-}
+}`} />
 
+```typescript
 const scores = [
   new Score(100, "Alice"),
   new Score(50, "Bob"),
@@ -141,25 +99,9 @@ scores.sort((a, b) => b.compareTo(a));
 
 Ord works with interfaces. For interfaces, a namespace is generated with a `compareTo` function:
 
-```typescript
-/** @derive(Ord) */
-interface Point {
-  x: number;
-  y: number;
-}
-
-// Generated:
-// export namespace Point {
-//   export function compareTo(self: Point, other: Point): number {
-//     if (self === other) return 0;
-//     const cmp0 = (self.x < other.x ? -1 : self.x > other.x ? 1 : 0);
-//     if (cmp0 !== 0) return cmp0;
-//     const cmp1 = (self.y < other.y ? -1 : self.y > other.y ? 1 : 0);
-//     if (cmp1 !== 0) return cmp1;
-//     return 0;
-//   }
-// }
+<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
 
+```typescript
 const points: Point[] = [
   { x: 5, y: 10 },
   { x: 1, y: 20 },
@@ -174,22 +116,9 @@ points.sort((a, b) => Point.compareTo(a, b));
 
 Ord works with enums. For numeric enums, it compares the numeric values; for string enums, it uses string comparison:
 
-```typescript
-/** @derive(Ord) */
-enum Priority {
-  Low = 0,
-  Medium = 1,
-  High = 2,
-  Critical = 3
-}
-
-// Generated:
-// export namespace Priority {
-//   export function compareTo(a: Priority, b: Priority): number {
-//     return a < b ? -1 : a > b ? 1 : 0;
-//   }
-// }
+<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
 
+```typescript
 console.log(Priority.compareTo(Priority.Low, Priority.High));      // -1
 console.log(Priority.compareTo(Priority.Critical, Priority.Low));  // 1
 console.log(Priority.compareTo(Priority.Medium, Priority.Medium)); // 0
@@ -199,25 +128,9 @@ console.log(Priority.compareTo(Priority.Medium, Priority.Medium)); // 0
 
 Ord works with type aliases. For object types, it uses lexicographic field comparison:
 
-```typescript
-/** @derive(Ord) */
-type Coordinate = {
-  x: number;
-  y: number;
-};
-
-// Generated:
-// export namespace Coordinate {
-//   export function compareTo(a: Coordinate, b: Coordinate): number {
-//     if (a === b) return 0;
-//     const cmp0 = (a.x < b.x ? -1 : a.x > b.x ? 1 : 0);
-//     if (cmp0 !== 0) return cmp0;
-//     const cmp1 = (a.y < b.y ? -1 : a.y > b.y ? 1 : 0);
-//     if (cmp1 !== 0) return cmp1;
-//     return 0;
-//   }
-// }
+<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
 
+```typescript
 const c1: Coordinate = { x: 10, y: 20 };
 const c2: Coordinate = { x: 10, y: 30 };
 
@@ -228,8 +141,7 @@ console.log(Coordinate.compareTo(c1, c2)); // -1 (c1 < c2)
 
 Use `Ord` when all values of a type are comparable. Use `PartialOrd` when some values might be incomparable (e.g., different types at runtime).
 
-```typescript
-// Ord: Total ordering - never returns null
+<InteractiveMacro code={`// Ord: Total ordering - never returns null
 /** @derive(Ord) */
 class Version {
   major: number;
@@ -238,21 +150,10 @@ class Version {
     this.major = major;
     this.minor = minor;
   }
-}
+}`} />
 
+```typescript
 const v1 = new Version(1, 0);
 const v2 = new Version(2, 0);
 console.log(v1.compareTo(v2)); // Always -1, 0, or 1
-
-// PartialOrd: Partial ordering - can return null
-/** @derive(PartialOrd) */
-class Value {
-  data: number;
-  constructor(data: number) {
-    this.data = data;
-  }
-}
-
-const val = new Value(10);
-console.log(val.compareTo("not a Value")); // null (incomparable)
 ```