@macroforge/mcp-server 0.1.17

package/docs/builtin-macros/hash.md

@@ -0,0 +1,205 @@
+# Hash
+
+*The `Hash` macro generates a `hashCode()` method that computes a numeric hash value based on field values.*
+
+## Basic Usage
+
+```typescript
+/** @derive(Hash) */
+class Point {
+  x: number;
+  y: number;
+
+  constructor(x: number, y: number) {
+    this.x = x;
+    this.y = y;
+  }
+}
+
+const p1 = new Point(10, 20);
+const p2 = new Point(10, 20);
+const p3 = new Point(5, 5);
+
+console.log(p1.hashCode()); // Same hash
+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:
+
+- `number` → Integers use bitwise OR (`| 0`), floats are stringified and hashed
+
+- `string` → Character-by-character hash: `(h * 31 + charCode) | 0`
+
+- `boolean` → `1231` for true, `1237` for false (Java convention)
+
+- `bigint` → Converted to string and hashed character-by-character
+
+- `Date` → Uses `getTime() | 0` for timestamp hash
+
+- `Array` → Combines element hashes with `h * 31 + elementHash`
+
+- `Map/Set` → Combines all entry hashes
+
+- `Object` → Calls `hashCode()` if available, otherwise JSON stringifies and hashes
+
+- `null` → Returns 0
+
+- `undefined` → Returns 1
+
+## Field Options
+
+### @hash(skip)
+
+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;
+  }
+}
+
+const user1 = new User(1, "Alice", new Date("2024-01-01"));
+const user2 = new User(1, "Alice", new Date("2024-12-01"));
+
+console.log(user1.hashCode() === user2.hashCode()); // true (lastLogin is skipped)
+```
+
+## Use with PartialEq
+
+Hash is often used together with PartialEq. Objects that are equal should have the same hash code:
+
+```typescript
+/** @derive(Hash, PartialEq) */
+class Product {
+  sku: string;
+  name: string;
+
+  constructor(sku: string, name: string) {
+    this.sku = sku;
+    this.name = name;
+  }
+}
+
+const p1 = new Product("ABC123", "Widget");
+const p2 = new Product("ABC123", "Widget");
+
+// Equal objects have equal hash codes
+console.log(p1.equals(p2));                       // true
+console.log(p1.hashCode() === p2.hashCode());     // true
+```
+
+## Interface Support
+
+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;
+//   }
+// }
+
+const p: Point = { x: 10, y: 20 };
+console.log(Point.hashCode(p)); // numeric hash value
+```
+
+## Enum Support
+
+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;
+//   }
+// }
+
+console.log(Status.hashCode(Status.Active));   // consistent hash
+console.log(Status.hashCode(Status.Inactive)); // different hash
+```
+
+## Type Alias Support
+
+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;
+//   }
+// }
+
+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";
+
+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

@@ -0,0 +1,169 @@
+# 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.*
+
+## Overview
+
+| `Debug` 
+| `toString(): string` 
+| Human-readable string representation 
+
+| `Clone` 
+| `clone(): T` 
+| Creates a copy of the object 
+
+| `PartialEq` 
+| `equals(other: T): boolean` 
+| Value equality comparison 
+
+| `Serialize` 
+| `toJSON(): Record<string, unknown>` 
+| JSON serialization with type handling 
+
+| `Deserialize` 
+| `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 { 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**]({base}/docs/builtin-macros/debug) - Customizable field renaming and skipping
+
+- [**Clone**]({base}/docs/builtin-macros/clone) - Shallow copying for all field types
+
+- [**PartialEq**]({base}/docs/builtin-macros/partial-eq) - Value-based equality 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

@@ -0,0 +1,258 @@
+# Ord
+
+*The `Ord` macro generates a `compareTo()` method that implements total ordering, always returning `-1`, `0`, or `1`.*
+
+## 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;
+  }
+}
+
+const v1 = new Version(1, 0, 0);
+const v2 = new Version(1, 2, 0);
+const v3 = new Version(1, 2, 0);
+
+console.log(v1.compareTo(v2)); // -1 (v1 < v2)
+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:
+
+- `number` / `bigint` → Direct numeric comparison
+
+- `string` → Uses `localeCompare()` clamped to -1/0/1
+
+- `boolean` → `false < true`
+
+- `Date` → Compares timestamps via `getTime()`
+
+- `Array` → Lexicographic: compares element-by-element, then length
+
+- `Map/Set` → Size and content comparison
+
+- `Object` → Calls `compareTo()` if available, otherwise 0
+
+- `null/undefined` → Treated as equal (returns 0)
+
+## Return Values
+
+The `compareTo()` method always returns:
+
+- `-1` → `this` is less than `other`
+
+- `0` → `this` equals `other`
+
+- `1` → `this` is greater than `other`
+
+Unlike `PartialOrd`, the `Ord` macro never returns `null` - it provides total ordering.
+
+## Field Options
+
+### @ord(skip)
+
+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;
+  }
+}
+
+const t1 = new Task(1, "Bug fix", new Date("2024-01-01"));
+const t2 = new Task(1, "Bug fix", new Date("2024-12-01"));
+
+console.log(t1.compareTo(t2)); // 0 (createdAt is skipped)
+```
+
+## Sorting Arrays
+
+The generated `compareTo()` method works directly with `Array.sort()`:
+
+```typescript
+/** @derive(Ord) */
+class Score {
+  points: number;
+  name: string;
+
+  constructor(points: number, name: string) {
+    this.points = points;
+    this.name = name;
+  }
+}
+
+const scores = [
+  new Score(100, "Alice"),
+  new Score(50, "Bob"),
+  new Score(150, "Charlie"),
+  new Score(50, "Alice")  // Same points, different name
+];
+
+// Sort ascending
+scores.sort((a, b) => a.compareTo(b));
+// Result: [Bob(50), Alice(50), Alice(100), Charlie(150)]
+
+// Sort descending
+scores.sort((a, b) => b.compareTo(a));
+// Result: [Charlie(150), Alice(100), Alice(50), Bob(50)]
+```
+
+## Interface Support
+
+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;
+//   }
+// }
+
+const points: Point[] = [
+  { x: 5, y: 10 },
+  { x: 1, y: 20 },
+  { x: 5, y: 5 }
+];
+
+points.sort((a, b) => Point.compareTo(a, b));
+// Result: [{ x: 1, y: 20 }, { x: 5, y: 5 }, { x: 5, y: 10 }]
+```
+
+## Enum Support
+
+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;
+//   }
+// }
+
+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
+```
+
+## Type Alias Support
+
+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;
+//   }
+// }
+
+const c1: Coordinate = { x: 10, y: 20 };
+const c2: Coordinate = { x: 10, y: 30 };
+
+console.log(Coordinate.compareTo(c1, c2)); // -1 (c1 < c2)
+```
+
+## Ord vs PartialOrd
+
+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
+/** @derive(Ord) */
+class Version {
+  major: number;
+  minor: number;
+  constructor(major: number, minor: number) {
+    this.major = major;
+    this.minor = minor;
+  }
+}
+
+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)
+```