@macroforge/mcp-server 0.1.37 → 0.1.39

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

@@ -0,0 +1,526 @@
+## Example
+
+```typescript before
+/** @derive(PartialEq, Hash) */
+class User {
+    id: number;
+    name: string;
+
+    @partialEq(skip) // Don't compare cached values
+    /** @hash({ skip: true }) */
+    cachedScore: number;
+}
+```
+
+```typescript after
+class User {
+    id: number;
+    name: string;
+
+    // Don't compare cached values
+    /** @hash({ skip: true }) */
+    cachedScore: number;
+
+    equals(other: unknown): boolean {
+        if (this === other) return true;
+        if (!(other instanceof User)) return false;
+        const typedOther = other as User;
+        return this.id === typedOther.id && this.name === typedOther.name;
+    }
+
+    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;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(this.cachedScore)
+                    ? this.cachedScore | 0
+                    : this.cachedScore
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        return hash;
+    }
+}
+```
+
+Generated output:
+
+```typescript before
+class User {
+    id: number;
+    name: string;
+
+    // Don't compare cached values
+    /** @hash({ skip: true }) */
+    cachedScore: number;
+
+    equals(other: unknown): boolean {
+        if (this === other) return true;
+        if (!(other instanceof User)) return false;
+        const typedOther = other as User;
+        return this.id === typedOther.id && this.name === typedOther.name;
+    }
+
+    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;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(this.cachedScore)
+                    ? this.cachedScore | 0
+                    : this.cachedScore
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        return hash;
+    }
+}
+```
+
+```typescript after
+class User {
+    id: number;
+    name: string;
+
+    // Don't compare cached values
+    /** @hash({ skip: true }) */
+    cachedScore: number;
+
+    equals(other: unknown): boolean {
+        if (this === other) return true;
+        if (!(other instanceof User)) return false;
+        const typedOther = other as User;
+        return this.id === typedOther.id && this.name === typedOther.name;
+    }
+
+    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;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(this.cachedScore)
+                    ? this.cachedScore | 0
+                    : this.cachedScore
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        return hash;
+    }
+}
+```
+
+Generated output:
+
+```typescript before
+class User {
+    id: number;
+    name: string;
+
+    // Don't compare cached values
+    /** @hash({ skip: true }) */
+    cachedScore: number;
+
+    equals(other: unknown): boolean {
+        if (this === other) return true;
+        if (!(other instanceof User)) return false;
+        const typedOther = other as User;
+        return this.id === typedOther.id && this.name === typedOther.name;
+    }
+
+    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;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(this.cachedScore)
+                    ? this.cachedScore | 0
+                    : this.cachedScore
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        return hash;
+    }
+}
+```
+
+```typescript after
+class User {
+    id: number;
+    name: string;
+
+    // Don't compare cached values
+    /** @hash({ skip: true }) */
+    cachedScore: number;
+
+    equals(other: unknown): boolean {
+        if (this === other) return true;
+        if (!(other instanceof User)) return false;
+        const typedOther = other as User;
+        return this.id === typedOther.id && this.name === typedOther.name;
+    }
+
+    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;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(this.cachedScore)
+                    ? this.cachedScore | 0
+                    : this.cachedScore
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        return hash;
+    }
+}
+```
+
+Generated output:
+
+```typescript before
+class User {
+    id: number;
+    name: string;
+
+    // Don't compare cached values
+    /** @hash({ skip: true }) */
+    cachedScore: number;
+
+    equals(other: unknown): boolean {
+        if (this === other) return true;
+        if (!(other instanceof User)) return false;
+        const typedOther = other as User;
+        return this.id === typedOther.id && this.name === typedOther.name;
+    }
+
+    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;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(this.cachedScore)
+                    ? this.cachedScore | 0
+                    : this.cachedScore
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        return hash;
+    }
+}
+```
+
+```typescript after
+class User {
+    id: number;
+    name: string;
+
+    // Don't compare cached values
+    /** @hash({ skip: true }) */
+    cachedScore: number;
+
+    equals(other: unknown): boolean {
+        if (this === other) return true;
+        if (!(other instanceof User)) return false;
+        const typedOther = other as User;
+        return this.id === typedOther.id && this.name === typedOther.name;
+    }
+
+    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;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(this.cachedScore)
+                    ? this.cachedScore | 0
+                    : this.cachedScore
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        return hash;
+    }
+}
+```
+
+Generated output:
+
+```typescript before
+class User {
+    id: number;
+    name: string;
+
+    // Don't compare cached values
+    /** @hash({ skip: true }) */
+    cachedScore: number;
+
+    equals(other: unknown): boolean {
+        if (this === other) return true;
+        if (!(other instanceof User)) return false;
+        const typedOther = other as User;
+        return this.id === typedOther.id && this.name === typedOther.name;
+    }
+
+    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;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(this.cachedScore)
+                    ? this.cachedScore | 0
+                    : this.cachedScore
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        return hash;
+    }
+}
+```
+
+```typescript after
+class User {
+    id: number;
+    name: string;
+
+    // Don't compare cached values
+    /** @hash({ skip: true }) */
+    cachedScore: number;
+
+    equals(other: unknown): boolean {
+        if (this === other) return true;
+        if (!(other instanceof User)) return false;
+        const typedOther = other as User;
+        return this.id === typedOther.id && this.name === typedOther.name;
+    }
+
+    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;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(this.cachedScore)
+                    ? this.cachedScore | 0
+                    : this.cachedScore
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        return hash;
+    }
+}
+```
+
+Generated output:
+
+```typescript before
+class User {
+    id: number;
+    name: string;
+
+    // Don't compare cached values
+    /** @hash({ skip: true }) */
+    cachedScore: number;
+
+    equals(other: unknown): boolean {
+        if (this === other) return true;
+        if (!(other instanceof User)) return false;
+        const typedOther = other as User;
+        return this.id === typedOther.id && this.name === typedOther.name;
+    }
+
+    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;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(this.cachedScore)
+                    ? this.cachedScore | 0
+                    : this.cachedScore
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        return hash;
+    }
+}
+```
+
+```typescript after
+class User {
+    id: number;
+    name: string;
+
+    // Don't compare cached values
+    /** @hash({ skip: true }) */
+    cachedScore: number;
+
+    equals(other: unknown): boolean {
+        if (this === other) return true;
+        if (!(other instanceof User)) return false;
+        const typedOther = other as User;
+        return this.id === typedOther.id && this.name === typedOther.name;
+    }
+
+    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;
+        hash =
+            (hash * 31 +
+                (Number.isInteger(this.cachedScore)
+                    ? this.cachedScore | 0
+                    : this.cachedScore
+                          .toString()
+                          .split('')
+                          .reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0))) |
+            0;
+        return hash;
+    }
+}
+```
+
+## Equality Contract
+
+When implementing `PartialEq`, consider also implementing `Hash`:
+
+- **Reflexivity**: `a.equals(a)` is always true
+- **Symmetry**: `a.equals(b)` implies `b.equals(a)`
+- **Hash consistency**: Equal objects must have equal hash codes

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

@@ -0,0 +1,39 @@
+# PartialEq
+
+The `PartialEq` macro generates an `equals()` method for field-by-field
+structural equality comparison. This is analogous to Rust's `PartialEq` trait,
+enabling value-based equality semantics instead of reference equality.
+
+## Generated Output
+
+| Type | Generated Code | Description |
+|------|----------------|-------------|
+| Class | `equals(other: unknown): boolean` | Instance method with instanceof check |
+| Enum | `equalsEnumName(a: EnumName, b: EnumName): boolean` | Standalone function using strict equality |
+| Interface | `equalsInterfaceName(a: InterfaceName, b: InterfaceName): boolean` | Standalone function comparing fields |
+| Type Alias | `equalsTypeName(a: TypeName, b: TypeName): boolean` | Standalone function with type-appropriate comparison |
+
+## Comparison Strategy
+
+The generated equality check:
+
+1. **Identity check**: `this === other` returns true immediately
+2. **Type check**: For classes, uses `instanceof`; returns false if wrong type
+3. **Field comparison**: Compares each non-skipped field
+
+## Type-Specific Comparisons
+
+| Type | Comparison Method |
+|------|-------------------|
+| Primitives | Strict equality (`===`) |
+| Arrays | Length + element-by-element (recursive) |
+| `Date` | `getTime()` comparison |
+| `Map` | Size + entry-by-entry comparison |
+| `Set` | Size + membership check |
+| Objects | Calls `equals()` if available, else `===` |
+
+## Field-Level Options
+
+The `@partialEq` decorator supports:
+
+- `skip` - Exclude the field from equality comparison