@macroforge/mcp-server 0.1.34 → 0.1.36

package/docs/builtin-macros/hash.md

@@ -1,279 +1,81 @@
 # Hash
-  *The `Hash` macro generates a `hashCode()` method for computing numeric hash codes. This is analogous to Rust's `Hash` trait and Java's `hashCode()` method, enabling objects to be used as keys in hash-based collections.*
- ## Basic Usage
- **Before:**
-```
-/** @derive(Hash) */
-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 `Hash` macro generates a `hashCode()` method for computing numeric hash codes.
+This is analogous to Rust's `Hash` trait and Java's `hashCode()` method, enabling
+objects to be used as keys in hash-based collections.
 
-    constructor(x: number, y: number) {
-        this.x = x;
-        this.y = y;
-    }
+## Generated Output
 
-    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;
-    }
-}
-``` ```
-const p1 = new Point(10, 20);
-const p2 = new Point(10, 20);
-const p3 = new Point(5, 5);
+| Type | Generated Code | Description |
+|------|----------------|-------------|
+| Class | `hashCode(): number` | Instance method computing hash from all fields |
+| Enum | `hashCodeEnumName(value: EnumName): number` | Standalone function hashing by enum value |
+| Interface | `hashCodeInterfaceName(value: InterfaceName): number` | Standalone function computing hash |
+| Type Alias | `hashCodeTypeName(value: TypeName): number` | Standalone function computing hash |
 
-console.log(p1.hashCode()); // Same hash
-console.log(p2.hashCode()); // Same hash (equal values = equal hash)
-console.log(p3.hashCode()); // Different 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:
- **Before:**
-```
-/** @derive(Hash) */
-class User {
-    id: number;
-    name: string;
+## Configuration
 
-    /** @hash(skip) */
-    lastLogin: Date;
+The `functionNamingStyle` option in `macroforge.json` controls naming:
+- `"suffix"` (default): Suffixes with type name (e.g., `hashCodeMyType`)
+- `"prefix"`: Prefixes with type name (e.g., `myTypeHashCode`)
+- `"generic"`: Uses TypeScript generics (e.g., `hashCode<T extends MyType>`)
+- `"namespace"`: Legacy namespace wrapping
 
-    constructor(id: number, name: string, lastLogin: Date) {
-        this.id = id;
-        this.name = name;
-        this.lastLogin = lastLogin;
-    }
-}
-```  
-**After:**
+## Hash Algorithm
+
+Uses the standard polynomial rolling hash algorithm:
+
+```text
+hash = 17  // Initial seed
+for each field:
+    hash = (hash * 31 + fieldHash) | 0  // Bitwise OR keeps it 32-bit integer
 ```
-class User {
-    id: number;
-    name: string;
 
-    lastLogin: Date;
+This algorithm is consistent with Java's `Objects.hash()` implementation.
 
-    constructor(id: number, name: string, lastLogin: Date) {
-        this.id = id;
-        this.name = name;
-        this.lastLogin = lastLogin;
-    }
+## Type-Specific Hashing
 
-    hashCode(): number {
-        let hash = 17;
-        hash =
-            (hash * 31 +
-                (Number.isInteger(this.id)
-                    ? this.id | 0
-                    : this.id
-                          .toString()
-                          .split('')
-                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
-            0;
-        hash =
-            (hash * 31 +
-                (this.name ?? '').split('').reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0)) |
-            0;
-        return hash;
-    }
-}
-``` ```
-const user1 = new User(1, "Alice", new Date("2024-01-01"));
-const user2 = new User(1, "Alice", new Date("2024-12-01"));
+| Type | Hash Strategy |
+|------|---------------|
+| `number` | Integer: direct value; Float: string hash of decimal |
+| `bigint` | String hash of decimal representation |
+| `string` | Character-by-character polynomial hash |
+| `boolean` | 1231 for true, 1237 for false (Java convention) |
+| `Date` | `getTime()` timestamp |
+| Arrays | Element-by-element hash combination |
+| `Map` | Entry-by-entry key+value hash |
+| `Set` | Element-by-element hash |
+| Objects | Calls `hashCode()` if available, else JSON string hash |
 
-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:
- **Source:**
-```
-/** @derive(Hash, PartialEq) */
-class Product {
-  sku: string;
-  name: string;
+## Field-Level Options
 
-  constructor(sku: string, name: string) {
-    this.sku = sku;
-    this.name = name;
-  }
-}
-```  ```
-const p1 = new Product("ABC123", "Widget");
-const p2 = new Product("ABC123", "Widget");
+The `@hash` decorator supports:
 
-// 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:
- **Before:**
-```
-/** @derive(Hash) */
-interface Point {
-    x: number;
-    y: number;
-}
-```  
-**After:**
-```
-interface Point {
-    x: number;
-    y: number;
-}
+- `skip` - Exclude the field from hash calculation
 
-export namespace Point {
-    export function hashCode(self: Point): number {
-        let hash = 17;
-        hash =
-            (hash * 31 +
-                (Number.isInteger(self.x)
-                    ? self.x | 0
-                    : self.x
-                          .toString()
-                          .split('')
-                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
-            0;
-        hash =
-            (hash * 31 +
-                (Number.isInteger(self.y)
-                    ? self.y | 0
-                    : self.y
-                          .toString()
-                          .split('')
-                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 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:
- **Before:**
-```
-/** @derive(Hash) */
-enum Status {
-    Active = 'active',
-    Inactive = 'inactive',
-    Pending = 'pending'
-}
-```  
-**After:**
-```
-enum Status {
-    Active = 'active',
-    Inactive = 'inactive',
-    Pending = 'pending'
-}
+## Example
 
-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 as number;
-    }
-}
-``` ```
-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:
- **Before:**
-```
-/** @derive(Hash) */
-type Coordinates = {
-    lat: number;
-    lng: number;
-};
-```  
-**After:**
-```
-type Coordinates = {
-    lat: number;
-    lng: number;
-};
+```typescript
+@derive(Hash, PartialEq)
+class User {
+    id: number;
+    name: string;
 
-export namespace Coordinates {
-    export function hashCode(value: Coordinates): number {
-        let hash = 17;
-        hash =
-            (hash * 31 +
-                (Number.isInteger(value.lat)
-                    ? value.lat | 0
-                    : value.lat
-                          .toString()
-                          .split('')
-                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
-            0;
-        hash =
-            (hash * 31 +
-                (Number.isInteger(value.lng)
-                    ? value.lng | 0
-                    : value.lng
-                          .toString()
-                          .split('')
-                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
-            0;
-        return hash;
-    }
+    @hash(skip)  // Cached value shouldn't affect hash
+    cachedScore: number;
 }
-``` ```
-const loc: Coordinates = { lat: 40.7128, lng: -74.0060 };
-console.log(Coordinates.hashCode(loc));
-``` For union types, it uses JSON stringification as a fallback:
- **Source:**
+
+// Generated:
+// hashCode(): number {
+//     let hash = 17;
+//     hash = (hash * 31 + (Number.isInteger(this.id) ? this.id | 0 : ...)) | 0;
+//     hash = (hash * 31 + (this.name ?? '').split('').reduce(...)) | 0;
+//     return hash;
+// }
 ```
-/** @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
-```
+
+## Hash Contract
+
+Objects that are equal (`PartialEq`) should produce the same hash code.
+When using `@hash(skip)`, ensure the same fields are skipped in both
+`Hash` and `PartialEq` to maintain this contract.

package/docs/builtin-macros/ord.md

@@ -1,272 +1,91 @@
 # Ord
-  *The `Ord` macro generates a `compareTo()` method for **total ordering** comparison. This is analogous to Rust's `Ord` trait, enabling objects to be sorted and compared with a guaranteed ordering relationship.*
- ## Basic Usage
- **Before:**
-```
-/** @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;
-    }
-}
-```  
-**After:**
-```
-class Version {
-    major: number;
-    minor: number;
-    patch: number;
+The `Ord` macro generates a `compareTo()` method for **total ordering** comparison.
+This is analogous to Rust's `Ord` trait, enabling objects to be sorted and
+compared with a guaranteed ordering relationship.
 
-    constructor(major: number, minor: number, patch: number) {
-        this.major = major;
-        this.minor = minor;
-        this.patch = patch;
-    }
+## Generated Output
 
-    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;
-    }
-}
-``` ```
-const v1 = new Version(1, 0, 0);
-const v2 = new Version(1, 2, 0);
-const v3 = new Version(1, 2, 0);
+| Type | Generated Code | Description |
+|------|----------------|-------------|
+| Class | `compareTo(other): number` | Instance method returning -1, 0, or 1 |
+| Enum | `compareEnumName(a: EnumName, b: EnumName): number` | Standalone function comparing enum values |
+| Interface | `compareInterfaceName(a: InterfaceName, b: InterfaceName): number` | Standalone function comparing fields |
+| Type Alias | `compareTypeName(a: TypeName, b: TypeName): number` | Standalone function with type-appropriate comparison |
 
-console.log(v1.compareTo(v2)); // -1 (v1 < v2)
-console.log(v2.compareTo(v1)); // 1  (v2 > v1)
-console.log(v2.compareTo(v3)); // 0  (v2 == v3)
-``` ## 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:
- **Before:**
-```
-/** @derive(Ord) */
-class Task {
-    priority: number;
-    name: string;
+## Configuration
 
-    /** @ord(skip) */
-    createdAt: Date;
+The `functionNamingStyle` option in `macroforge.json` controls naming:
+- `"suffix"` (default): Suffixes with type name (e.g., `compareMyType`)
+- `"prefix"`: Prefixes with type name (e.g., `myTypeCompare`)
+- `"generic"`: Uses TypeScript generics (e.g., `compare<T extends MyType>`)
+- `"namespace"`: Legacy namespace wrapping
 
-    constructor(priority: number, name: string, createdAt: Date) {
-        this.priority = priority;
-        this.name = name;
-        this.createdAt = createdAt;
-    }
-}
-```  
-**After:**
-```
-class Task {
-    priority: number;
-    name: string;
+## Return Values
 
-    createdAt: Date;
+Unlike `PartialOrd`, `Ord` provides **total ordering** - every pair of values
+can be compared:
 
-    constructor(priority: number, name: string, createdAt: Date) {
-        this.priority = priority;
-        this.name = name;
-        this.createdAt = createdAt;
-    }
+- **-1**: `this` is less than `other`
+- **0**: `this` is equal to `other`
+- **1**: `this` is greater than `other`
 
-    compareTo(other: Task): number {
-        if (this === other) return 0;
-        const typedOther = other;
-        const cmp0 =
-            this.priority < typedOther.priority ? -1 : this.priority > typedOther.priority ? 1 : 0;
-        if (cmp0 !== 0) return cmp0;
-        const cmp1 = ((cmp) => (cmp < 0 ? -1 : cmp > 0 ? 1 : 0))(
-            this.name.localeCompare(typedOther.name)
-        );
-        if (cmp1 !== 0) return cmp1;
-        return 0;
-    }
-}
-``` ```
-const t1 = new Task(1, "Bug fix", new Date("2024-01-01"));
-const t2 = new Task(1, "Bug fix", new Date("2024-12-01"));
+The method **never returns null** - all values must be comparable.
 
-console.log(t1.compareTo(t2)); // 0 (createdAt is skipped)
-``` ## Sorting Arrays
- The generated `compareTo()` method works directly with `Array.sort()`:
- **Source:**
-```
-/** @derive(Ord) */
-class Score {
-  points: number;
-  name: string;
+## Comparison Strategy
 
-  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
-];
+Fields are compared **lexicographically** in declaration order:
 
-// Sort ascending
-scores.sort((a, b) => a.compareTo(b));
-// Result: [Bob(50), Alice(50), Alice(100), Charlie(150)]
+1. Compare first field
+2. If not equal, return that result
+3. Otherwise, compare next field
+4. Continue until a difference is found or all fields are equal
 
-// 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:
- **Before:**
-```
-/** @derive(Ord) */
-interface Point {
-    x: number;
-    y: number;
-}
-```  
-**After:**
-```
-interface Point {
-    x: number;
-    y: number;
-}
+## Type-Specific Comparisons
 
-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 }
-];
+| Type | Comparison Method |
+|------|-------------------|
+| `number`/`bigint` | Direct `<` and `>` comparison |
+| `string` | `localeCompare()` (clamped to -1, 0, 1) |
+| `boolean` | false &lt; true |
+| Arrays | Lexicographic element-by-element |
+| `Date` | `getTime()` timestamp comparison |
+| Objects | Calls `compareTo()` if available, else 0 |
 
-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:
- **Before:**
-```
-/** @derive(Ord) */
-enum Priority {
-    Low = 0,
-    Medium = 1,
-    High = 2,
-    Critical = 3
-}
-```  
-**After:**
-```
-enum Priority {
-    Low = 0,
-    Medium = 1,
-    High = 2,
-    Critical = 3
-}
+## Field-Level Options
 
-export namespace Priority {
-    export function compareTo(a: Priority, b: Priority): number {
-        if (typeof a === 'number' && typeof b === 'number') {
-            return a < b ? -1 : a > b ? 1 : 0;
-        }
-        if (typeof a === 'string' && typeof b === 'string') {
-            const cmp = a.localeCompare(b);
-            return cmp < 0 ? -1 : cmp > 0 ? 1 : 0;
-        }
-        return 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:
- **Before:**
-```
-/** @derive(Ord) */
-type Coordinate = {
-    x: number;
-    y: number;
-};
-```  
-**After:**
-```
-type Coordinate = {
-    x: number;
-    y: number;
-};
+The `@ord` decorator supports:
 
-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 };
+- `skip` - Exclude the field from ordering comparison
 
-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).
- **Source:**
-```
-// Ord: Total ordering - never returns null
-/** @derive(Ord) */
+## Example
+
+```typescript
+@derive(Ord)
 class Version {
-  major: number;
-  minor: number;
-  constructor(major: number, minor: number) {
-    this.major = major;
-    this.minor = minor;
-  }
+    major: number;
+    minor: number;
+    patch: number;
 }
-```  ```
-const v1 = new Version(1, 0);
-const v2 = new Version(2, 0);
-console.log(v1.compareTo(v2)); // Always -1, 0, or 1
-```
+
+// Generated:
+// 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 : ...;
+//     if (cmp1 !== 0) return cmp1;
+//     const cmp2 = this.patch < typedOther.patch ? -1 : ...;
+//     if (cmp2 !== 0) return cmp2;
+//     return 0;
+// }
+
+// Usage:
+versions.sort((a, b) => a.compareTo(b));
+```
+
+## Ord vs PartialOrd
+
+- Use **Ord** when all values are comparable (total ordering)
+- Use **PartialOrd** when some values may be incomparable (returns `Option<number>`)