@macroforge/mcp-server 0.1.37 → 0.1.39

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

@@ -8,26 +8,17 @@ enabling value-based equality semantics instead of reference equality.
 
 | 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 |
-
-## Configuration
-
-The `functionNamingStyle` option in `macroforge.json` controls naming:
-- `"prefix"` (default): Prefixes with type name (e.g., `myTypeEquals`)
-- `"suffix"`: Suffixes with type name (e.g., `equalsMyType`)
-- `"generic"`: Uses TypeScript generics (e.g., `equals<T extends MyType>`)
-- `"namespace"`: Legacy namespace wrapping
+| Class | `classNameEquals(a, b)` + `static equals(a, b)` | Standalone function + static wrapper method |
+| Enum | `enumNameEquals(a: EnumName, b: EnumName): boolean` | Standalone function using strict equality |
+| Interface | `interfaceNameEquals(a: InterfaceName, b: InterfaceName): boolean` | Standalone function comparing fields |
+| Type Alias | `typeNameEquals(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
+1. **Identity check**: `a === b` returns true immediately
+2. **Field comparison**: Compares each non-skipped field
 
 ## Type-Specific Comparisons
 
@@ -48,25 +39,97 @@ The `@partialEq` decorator supports:
 
 ## Example
 
+```typescript before
+/** @derive(PartialEq, Hash) */
+class User {
+    id: number;
+    name: string;
+
+    /** @partialEq({ skip: true }) @hash({ skip: true }) */
+    cachedScore: number;
+}
+```
+
+```typescript after
+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;
+}
+```
+
+Generated output:
+
 ```typescript
-@derive(PartialEq, Hash)
 class User {
     id: number;
     name: string;
 
-    @partialEq(skip)  // Don't compare cached values
-    @hash(skip)
     cachedScore: number;
+
+    static equals(a: User, b: User): boolean {
+        return userEquals(a, b);
+    }
+
+    static hashCode(value: User): number {
+        return userHashCode(value);
+    }
 }
 
-// Generated:
-// 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;
-// }
+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
@@ -76,3 +139,98 @@ 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
+
+To maintain the hash contract, skip the same fields in both `PartialEq` and `Hash`:
+
+```typescript before
+/** @derive(PartialEq, Hash) */
+class User {
+    id: number;
+    name: string;
+
+    /** @partialEq({ skip: true }) @hash({ skip: true }) */
+    cachedScore: number;
+}
+```
+
+```typescript after
+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;
+}
+```
+
+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;
+}
+```

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

@@ -8,26 +8,18 @@ between values where some pairs may be incomparable.
 
 | Type | Generated Code | Description |
 |------|----------------|-------------|
-| Class | `compareTo(other): Option<number>` | Instance method with optional result |
-| Enum | `partialCompareEnumName(a: EnumName, b: EnumName): Option<number>` | Standalone function returning Option |
-| Interface | `partialCompareInterfaceName(a: InterfaceName, b: InterfaceName): Option<number>` | Standalone function with Option |
-| Type Alias | `partialCompareTypeName(a: TypeName, b: TypeName): Option<number>` | Standalone function with Option |
-
-## Configuration
-
-The `functionNamingStyle` option in `macroforge.json` controls naming:
-- `"prefix"` (default): Prefixes with type name (e.g., `myTypePartialCompare`)
-- `"suffix"`: Suffixes with type name (e.g., `partialCompareMyType`)
-- `"generic"`: Uses TypeScript generics (e.g., `partialCompare<T extends MyType>`)
-- `"namespace"`: Legacy namespace wrapping
+| Class | `classNamePartialCompare(a, b)` + `static compareTo(a, b)` | Standalone function + static wrapper method |
+| Enum | `enumNamePartialCompare(a: EnumName, b: EnumName): Option<number>` | Standalone function returning Option |
+| Interface | `interfaceNamePartialCompare(a: InterfaceName, b: InterfaceName): Option<number>` | Standalone function with Option |
+| Type Alias | `typeNamePartialCompare(a: TypeName, b: TypeName): Option<number>` | Standalone function with Option |
 
 ## Return Values
 
 Unlike `Ord`, `PartialOrd` returns an `Option<number>` to handle incomparable values:
 
-- **Option.some(-1)**: `this` is less than `other`
-- **Option.some(0)**: `this` is equal to `other`
-- **Option.some(1)**: `this` is greater than `other`
+- **Option.some(-1)**: `a` is less than `b`
+- **Option.some(0)**: `a` is equal to `b`
+- **Option.some(1)**: `a` is greater than `b`
 - **Option.none()**: Values are incomparable
 
 ## When to Use PartialOrd vs Ord
@@ -69,26 +61,72 @@ The `@ord` decorator supports:
 
 ## Example
 
+```typescript before
+/** @derive(PartialOrd) */
+class Temperature {
+    value: number | null;
+    unit: string;
+}
+```
+
+```typescript after
+import { Option } from 'macroforge/utils';
+
+class Temperature {
+    value: number | null;
+    unit: string;
+
+    static compareTo(a: Temperature, b: Temperature): Option<number> {
+        return temperaturePartialCompare(a, b);
+    }
+}
+
+export function temperaturePartialCompare(a: Temperature, b: Temperature): Option<number> {
+    if (a === b) return Option.some(0);
+    const cmp0 = (() => {
+        if (typeof (a.value as any)?.compareTo === 'function') {
+            const optResult = (a.value as any).compareTo(b.value);
+            return Option.isNone(optResult) ? null : optResult.value;
+        }
+        return a.value === b.value ? 0 : null;
+    })();
+    if (cmp0 === null) return Option.none();
+    if (cmp0 !== 0) return Option.some(cmp0);
+    const cmp1 = a.unit.localeCompare(b.unit);
+    if (cmp1 === null) return Option.none();
+    if (cmp1 !== 0) return Option.some(cmp1);
+    return Option.some(0);
+}
+```
+
+Generated output:
+
 ```typescript
-@derive(PartialOrd)
 class Temperature {
-    value: number | null;  // null represents "unknown"
+    value: number | null;
     unit: string;
+
+    static compareTo(a: Temperature, b: Temperature): Option<number> {
+        return temperaturePartialCompare(a, b);
+    }
 }
 
-// Generated:
-// compareTo(other: unknown): Option<number> {
-//     if (this === other) return Option.some(0);
-//     if (!(other instanceof Temperature)) return Option.none();
-//     const typedOther = other as Temperature;
-//     const cmp0 = ...;  // Compare value field
-//     if (cmp0 === null) return Option.none();
-//     if (cmp0 !== 0) return Option.some(cmp0);
-//     const cmp1 = ...;  // Compare unit field
-//     if (cmp1 === null) return Option.none();
-//     if (cmp1 !== 0) return Option.some(cmp1);
-//     return Option.some(0);
-// }
+export function temperaturePartialCompare(a: Temperature, b: Temperature): Option<number> {
+    if (a === b) return Option.some(0);
+    const cmp0 = (() => {
+        if (typeof (a.value as any)?.compareTo === 'function') {
+            const optResult = (a.value as any).compareTo(b.value);
+            return Option.isNone(optResult) ? null : optResult.value;
+        }
+        return a.value === b.value ? 0 : null;
+    })();
+    if (cmp0 === null) return Option.none();
+    if (cmp0 !== 0) return Option.some(cmp0);
+    const cmp1 = a.unit.localeCompare(b.unit);
+    if (cmp1 === null) return Option.none();
+    if (cmp1 !== 0) return Option.some(cmp1);
+    return Option.some(0);
+}
 ```
 
 ## Required Import

package/docs/builtin-macros/serialize/example.md

@@ -0,0 +1,139 @@
+## Example
+
+```typescript before
+/** @derive(Serialize) */
+class User {
+    id: number;
+
+    /** @serde({ rename: "userName" }) */
+    name: string;
+
+    /** @serde({ skipSerializing: true }) */
+    password: string;
+
+    /** @serde({ flatten: true }) */
+    metadata: UserMetadata;
+}
+```
+
+```typescript after
+import { SerializeContext } from 'macroforge/serde';
+
+class User {
+    id: number;
+
+    name: string;
+
+    password: string;
+
+    metadata: UserMetadata;
+    /** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata  */
+
+    static serialize(value: User): string {
+        return userSerialize(value);
+    }
+    /** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context  */
+
+    static serializeWithContext(value: User, ctx: SerializeContext): Record<string, unknown> {
+        return userSerializeWithContext(value, ctx);
+    }
+}
+
+/** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata */ export function userSerialize(
+    value: User
+): string {
+    const ctx = SerializeContext.create();
+    return JSON.stringify(userSerializeWithContext(value, ctx));
+} /** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context */
+export function userSerializeWithContext(
+    value: User,
+    ctx: SerializeContext
+): Record<string, unknown> {
+    const existingId = ctx.getId(value);
+    if (existingId !== undefined) {
+        return { __ref: existingId };
+    }
+    const __id = ctx.register(value);
+    const result: Record<string, unknown> = { __type: 'User', __id };
+    result['id'] = value.id;
+    result['userName'] = value.name;
+    {
+        const __flattened = userMetadataSerializeWithContext(value.metadata, ctx);
+        const { __type: _, __id: __, ...rest } = __flattened as any;
+        Object.assign(result, rest);
+    }
+    return result;
+}
+```
+
+Generated output:
+
+```typescript
+import { SerializeContext } from 'macroforge/serde';
+
+class User {
+    id: number;
+
+    name: string;
+
+    password: string;
+
+    metadata: UserMetadata;
+    /** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata  */
+
+    static serialize(value: User): string {
+        return userSerialize(value);
+    }
+    /** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context  */
+
+    static serializeWithContext(value: User, ctx: SerializeContext): Record<string, unknown> {
+        return userSerializeWithContext(value, ctx);
+    }
+}
+
+/** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata */ export function userSerialize(
+    value: User
+): string {
+    const ctx = SerializeContext.create();
+    return JSON.stringify(userSerializeWithContext(value, ctx));
+} /** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context */
+export function userSerializeWithContext(
+    value: User,
+    ctx: SerializeContext
+): Record<string, unknown> {
+    const existingId = ctx.getId(value);
+    if (existingId !== undefined) {
+        return { __ref: existingId };
+    }
+    const __id = ctx.register(value);
+    const result: Record<string, unknown> = { __type: 'User', __id };
+    result['id'] = value.id;
+    result['userName'] = value.name;
+    {
+        const __flattened = userMetadataSerializeWithContext(value.metadata, ctx);
+        const { __type: _, __id: __, ...rest } = __flattened as any;
+        Object.assign(result, rest);
+    }
+    return result;
+}
+```
+
+## Required Import
+
+The generated code automatically imports `SerializeContext` from `macroforge/serde`.

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

@@ -0,0 +1,32 @@
+# Serialize
+
+The `Serialize` macro generates JSON serialization methods with **cycle detection**
+and object identity tracking. This enables serialization of complex object graphs
+including circular references.
+
+## Generated Methods
+
+| Type | Generated Code | Description |
+|------|----------------|-------------|
+| Class | `classNameSerialize(value)` + `static serialize(value)` | Standalone function + static wrapper method |
+| Enum | `enumNameSerialize(value)`, `enumNameSerializeWithContext` | Standalone functions |
+| Interface | `interfaceNameSerialize(value)`, etc. | Standalone functions |
+| Type Alias | `typeNameSerialize(value)`, etc. | Standalone functions |
+
+## Cycle Detection Protocol
+
+The generated code handles circular references using `__id` and `__ref` markers:
+
+```json
+{
+    "__type": "User",
+    "__id": 1,
+    "name": "Alice",
+    "friend": { "__ref": 2 }  // Reference to object with __id: 2
+}
+```
+
+When an object is serialized:
+1. Check if it's already been serialized (has an `__id`)
+2. If so, return `{ "__ref": existingId }` instead
+3. Otherwise, register the object and serialize its fields

package/docs/builtin-macros/serialize/type-specific-serialization.md

@@ -0,0 +1,22 @@
+## Type-Specific Serialization
+
+| Type | Serialization Strategy |
+|------|------------------------|
+| Primitives | Direct value |
+| `Date` | `toISOString()` |
+| Arrays | For primitive-like element types, pass through; for `Date`/`Date | null`, map to ISO strings; otherwise map and call `SerializeWithContext(ctx)` when available |
+| `Map<K,V>` | For primitive-like values, `Object.fromEntries(map.entries())`; for `Date`/`Date | null`, convert to ISO strings; otherwise call `SerializeWithContext(ctx)` per value when available |
+| `Set<T>` | Convert to array; element handling matches `Array<T>` |
+| Nullable | Include `null` explicitly; for primitive-like and `Date` unions the generator avoids runtime `SerializeWithContext` checks |
+| Objects | Call `SerializeWithContext(ctx)` if available (to support user-defined implementations) |
+
+Note: the generator specializes some code paths based on the declared TypeScript type to
+avoid runtime feature detection on primitives and literal unions.
+
+## Field-Level Options
+
+The `@serde` decorator supports:
+
+- `skip` / `skipSerializing` - Exclude field from serialization
+- `rename = "jsonKey"` - Use different JSON property name
+- `flatten` - Merge nested object's fields into parent