@macroforge/mcp-server 0.1.76 → 0.1.78

package/docs/builtin-macros/clone.md

@@ -9,21 +9,24 @@ independent copies of values.
 | Type | Generated Code | Description |
 |------|----------------|-------------|
 | Class | `classNameClone(value)` + `static clone(value)` | Standalone function + static wrapper method |
-| Enum | `enumNameClone(value: EnumName): EnumName` | Standalone function (enums are primitives, returns value as-is) |
-| Interface | `interfaceNameClone(value: InterfaceName): InterfaceName` | Standalone function creating a new object literal |
-| Type Alias | `typeNameClone(value: TypeName): TypeName` | Standalone function with spread copy for objects |
+| Enum | `enumNameClone(value): EnumName` | Standalone function (enums are primitives, returns value as-is) |
+| Interface | `ifaceNameClone(value): InterfaceName` | Standalone function creating a new object literal |
+| Type Alias | `typeNameClone(value): TypeName` | Standalone function with spread copy for objects |
 
+Names use **camelCase** conversion (e.g., `Point` → `pointClone`).
 
-## Cloning Strategy
 
-The generated clone performs a **shallow copy** of all fields:
+## Cloning Strategy
 
-- **Primitives** (`string`, `number`, `boolean`): Copied by value
-- **Objects**: Reference is copied (not deep cloned)
-- **Arrays**: Reference is copied (not deep cloned)
+The generated clone is **type-aware** when a type registry is available:
 
-For deep cloning of nested objects, those objects should also derive `Clone`
-and the caller should clone them explicitly.
+- **Primitives** (`string`, `number`, `boolean`, `bigint`): Copied by value
+- **`Date`**: Deep cloned via `new Date(x.getTime())`
+- **Arrays**: Spread copy `[...arr]`, or deep map if element type has `Clone`
+- **`Map`/`Set`**: New collection, deep copy if value type has `Clone`
+- **Objects with `@derive(Clone)`**: Deep cloned via their standalone clone function
+- **Optional fields**: Null-checked — `null`/`undefined` pass through unchanged
+- **Other objects**: Shallow copy (reference)
 
 ## Example
 

package/docs/builtin-macros/debug.md

@@ -11,11 +11,13 @@ method `static toString(value)` returning a string like `"ClassName { field1: va
 **Enums**: Generates a standalone function `enumNameToString(value)` that performs
 reverse lookup on numeric enums.
 
-**Interfaces**: Generates a standalone function `interfaceNameToString(value)`.
+**Interfaces**: Generates a standalone function `ifaceNameToString(value)`.
 
 **Type Aliases**: Generates a standalone function using JSON.stringify for
 complex types, or field enumeration for object types.
 
+Names use **camelCase** conversion (e.g., `User` → `userToString`).
+
 
 ## Field-Level Options
 

package/docs/builtin-macros/default.md

@@ -8,10 +8,12 @@ a standard way to create "zero" or "empty" instances of types.
 
 | Type | Generated Code | Description |
 |------|----------------|-------------|
-| Class | `static defaultValue(): ClassName` | Static factory method |
-| Enum | `defaultValueEnumName(): EnumName` | Standalone function returning marked variant |
-| Interface | `defaultValueInterfaceName(): InterfaceName` | Standalone function returning object literal |
-| Type Alias | `defaultValueTypeName(): TypeName` | Standalone function with type-appropriate default |
+| Class | `static defaultValue()` + `classNameDefaultValue()` | Static factory method + standalone function |
+| Enum | `enumNameDefaultValue(): EnumName` | Standalone function returning `@default` variant |
+| Interface | `ifaceNameDefaultValue(): InterfaceName` | Standalone function returning object literal |
+| Type Alias | `typeNameDefaultValue(): TypeName` | Standalone function with type-appropriate default |
+
+Names use **camelCase** conversion (e.g., `UserSettings` → `userSettingsDefaultValue`).
 
 
 ## Default Values by Type
@@ -72,6 +74,10 @@ class UserSettings {
         return instance;
     }
 }
+
+export function userSettingsDefaultValue(): UserSettings {
+    return UserSettings.defaultValue();
+}
 ```
 
 ## Enum Defaults
@@ -99,10 +105,6 @@ enum Status {
 export function statusDefaultValue(): Status {
     return Status.Pending;
 }
-
-namespace Status {
-    export const defaultValue = statusDefaultValue;
-}
 ```
 
 ## Error Handling

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

@@ -53,7 +53,7 @@ class User {
      */
     static deserialize(
         input: unknown,
-        opts?: @{DESERIALIZE_OPTIONS}
+        opts?: @DESERIALIZE_OPTIONS
     ): Result<
         User,
         Array<{
@@ -65,9 +65,9 @@ class User {
             // Auto-detect: if string, parse as JSON first
             const data = typeof input === 'string' ? JSON.parse(input) : input;
 
-            const ctx = @{DESERIALIZE_CONTEXT}.create();
+            const ctx = @DESERIALIZE_CONTEXT.create();
             const resultOrRef = User.deserializeWithContext(data, ctx);
-            if (@{PENDING_REF}.is(resultOrRef)) {
+            if (@PENDING_REF.is(resultOrRef)) {
                 return Result.err([
                     {
                         field: '_root',
@@ -81,7 +81,7 @@ class User {
             }
             return Result.ok(resultOrRef);
         } catch (e) {
-            if (e instanceof @{DESERIALIZE_ERROR}) {
+            if (e instanceof @DESERIALIZE_ERROR) {
                 return Result.err(e.errors);
             }
             const message = e instanceof Error ? e.message : String(e);
@@ -95,12 +95,12 @@ class User {
     }
 
     /** @internal */
-    static deserializeWithContext(value: any, ctx: @{DESERIALIZE_CONTEXT}): User | @{PENDING_REF} {
+    static deserializeWithContext(value: any, ctx: @DESERIALIZE_CONTEXT): User | @PENDING_REF {
         if (value?.__ref !== undefined) {
             return ctx.getOrDefer(value.__ref);
         }
         if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-            throw new @{DESERIALIZE_ERROR}([
+            throw new @DESERIALIZE_ERROR([
                 {
                     field: '_root',
                     message: 'User.deserializeWithContext: expected an object'
@@ -134,7 +134,7 @@ class User {
             });
         }
         if (errors.length > 0) {
-            throw new @{DESERIALIZE_ERROR}(errors);
+            throw new @deserialize_error_expr(errors);
         }
         const instance = Object.create(User.prototype) as User;
         if (obj.__id !== undefined) {
@@ -160,7 +160,7 @@ class User {
             instance.age = __raw_age;
         }
         if (errors.length > 0) {
-            throw new @{DESERIALIZE_ERROR}(errors);
+            throw new @deserialize_error_expr(errors);
         }
         return instance;
     }

package/docs/builtin-macros/deserialize.md

@@ -150,7 +150,7 @@ class User {
      */
     static deserialize(
         input: unknown,
-        opts?: @{DESERIALIZE_OPTIONS}
+        opts?: @DESERIALIZE_OPTIONS
     ): Result<
         User,
         Array<{
@@ -162,9 +162,9 @@ class User {
             // Auto-detect: if string, parse as JSON first
             const data = typeof input === 'string' ? JSON.parse(input) : input;
 
-            const ctx = @{DESERIALIZE_CONTEXT}.create();
+            const ctx = @DESERIALIZE_CONTEXT.create();
             const resultOrRef = User.deserializeWithContext(data, ctx);
-            if (@{PENDING_REF}.is(resultOrRef)) {
+            if (@PENDING_REF.is(resultOrRef)) {
                 return Result.err([
                     {
                         field: '_root',
@@ -178,7 +178,7 @@ class User {
             }
             return Result.ok(resultOrRef);
         } catch (e) {
-            if (e instanceof @{DESERIALIZE_ERROR}) {
+            if (e instanceof @DESERIALIZE_ERROR) {
                 return Result.err(e.errors);
             }
             const message = e instanceof Error ? e.message : String(e);
@@ -192,12 +192,12 @@ class User {
     }
 
     /** @internal */
-    static deserializeWithContext(value: any, ctx: @{DESERIALIZE_CONTEXT}): User | @{PENDING_REF} {
+    static deserializeWithContext(value: any, ctx: @DESERIALIZE_CONTEXT): User | @PENDING_REF {
         if (value?.__ref !== undefined) {
             return ctx.getOrDefer(value.__ref);
         }
         if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-            throw new @{DESERIALIZE_ERROR}([
+            throw new @DESERIALIZE_ERROR([
                 {
                     field: '_root',
                     message: 'User.deserializeWithContext: expected an object'
@@ -231,7 +231,7 @@ class User {
             });
         }
         if (errors.length > 0) {
-            throw new @{DESERIALIZE_ERROR}(errors);
+            throw new @deserialize_error_expr(errors);
         }
         const instance = Object.create(User.prototype) as User;
         if (obj.__id !== undefined) {
@@ -257,7 +257,7 @@ class User {
             instance.age = __raw_age;
         }
         if (errors.length > 0) {
-            throw new @{DESERIALIZE_ERROR}(errors);
+            throw new @deserialize_error_expr(errors);
         }
         return instance;
     }

package/docs/builtin-macros/hash.md

@@ -21,10 +21,13 @@ 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
+    hash = (hash * 31 + fieldHash) | 0
 ```
 
-This algorithm is consistent with Java's `Objects.hash()` implementation.
+The `| 0` (bitwise OR with zero) at the end of each step coerces the result
+to a 32-bit signed integer, preventing floating-point drift from repeated
+multiplication. This is equivalent to casting to `i32` in Rust and consistent
+with Java's `Objects.hash()` implementation.
 
 ## Type-Specific Hashing
 
@@ -49,7 +52,7 @@ The `@hash` decorator supports:
 ## Example
 
 ```typescript before
-/** @derive(Hash, PartialEq) */
+/** @derive(Hash) */
 class User {
     id: number;
     name: string;
@@ -69,10 +72,6 @@ class User {
     static hashCode(value: User): number {
         return userHashCode(value);
     }
-
-    static equals(a: User, b: User): boolean {
-        return userEquals(a, b);
-    }
 }
 
 export function userHashCode(value: User): number {
@@ -92,11 +91,6 @@ export function userHashCode(value: User): number {
         0;
     return hash;
 }
-
-export function userEquals(a: User, b: User): boolean {
-    if (a === b) return true;
-    return a.id === b.id && a.name === b.name && a.cachedScore === b.cachedScore;
-}
 ```
 
 ## Hash Contract

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

@@ -40,12 +40,12 @@ The `@partialEq` decorator supports:
 ## Example
 
 ```typescript before
-/** @derive(PartialEq, Hash) */
+/** @derive(PartialEq) */
 class User {
     id: number;
     name: string;
 
-    /** @partialEq({ skip: true }) @hash({ skip: true }) */
+    /** @partialEq({ skip: true }) */
     cachedScore: number;
 }
 ```
@@ -60,34 +60,12 @@ class User {
     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;
-}
 ```
 
 ## Equality Contract
@@ -98,55 +76,5 @@ When implementing `PartialEq`, consider also implementing `Hash`:
 - **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;
-}
-```
+To maintain the hash contract, skip the same fields in both `PartialEq` and `Hash`,
+as shown in the example above using `@partialEq({ skip: true }) @hash({ skip: true })`.

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

@@ -9,18 +9,20 @@ between values where some pairs may be incomparable.
 | Type | Generated Code | Description |
 |------|----------------|-------------|
 | 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 |
+| Enum | `enumNamePartialCompare(a, b): number \| null` | Standalone function returning `number \| null` |
+| Interface | `ifaceNamePartialCompare(a, b): number \| null` | Standalone function returning `number \| null` |
+| Type Alias | `typeNamePartialCompare(a, b): number \| null` | Standalone function returning `number \| null` |
+
+Names use **camelCase** conversion (e.g., `Temperature` → `temperaturePartialCompare`).
 
 ## Return Values
 
-Unlike `Ord`, `PartialOrd` returns an `Option<number>` to handle incomparable values:
+Unlike `Ord`, `PartialOrd` returns `number | null` to handle incomparable values:
 
-- **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
+- **-1**: `a` is less than `b`
+- **0**: `a` is equal to `b`
+- **1**: `a` is greater than `b`
+- **null**: Values are incomparable
 
 ## When to Use PartialOrd vs Ord
 
@@ -36,8 +38,8 @@ Unlike `Ord`, `PartialOrd` returns an `Option<number>` to handle incomparable va
 Fields are compared **lexicographically** in declaration order:
 
 1. Compare first field
-2. If incomparable, return `Option.none()`
-3. If not equal, return that result wrapped in `Option.some()`
+2. If incomparable, return `null`
+3. If not equal, return that result
 4. Otherwise, compare next field
 5. Continue until a difference is found or all fields are equal
 
@@ -45,13 +47,13 @@ Fields are compared **lexicographically** in declaration order:
 
 | Type | Comparison Method |
 |------|-------------------|
-| `number`/`bigint` | Direct comparison, returns some() |
-| `string` | `localeCompare()` wrapped in some() |
-| `boolean` | false &lt; true, wrapped in some() |
-| null/undefined | Returns none() for mismatched nullability |
-| Arrays | Lexicographic, propagates none() on incomparable elements |
-| `Date` | Timestamp comparison, none() if invalid |
-| Objects | Unwraps nested Option from compareTo() |
+| `number`/`bigint` | Direct subtraction (`a - b`) |
+| `string` | `localeCompare()` |
+| `boolean` | `false < true` (cast to number) |
+| null/undefined | Returns `null` for mismatched nullability |
+| Arrays | Lexicographic, propagates `null` on incomparable elements |
+| `Date` | Timestamp comparison, `null` if invalid |
+| Objects | Delegates to `compareTo()` if available |
 
 ## Field-Level Options
 

package/docs/builtin-macros/serialize.md

@@ -94,7 +94,7 @@ class User {
 @param value - The value to serialize
 @param ctx - The serialization context  */
 
-    static serializeWithContext(value: User, ctx: @{SERIALIZE_CONTEXT}): Record<string, unknown> {
+    static serializeWithContext(value: User, ctx: @SERIALIZE_CONTEXT): Record<string, unknown> {
         return userSerializeWithContext(value, ctx);
     }
 }
@@ -104,7 +104,7 @@ class User {
 @returns JSON string representation with cycle detection metadata */ export function userSerialize(
     value: User
 ): string {
-    const ctx = @{SERIALIZE_CONTEXT}.create();
+    const ctx = @SERIALIZE_CONTEXT.create();
     return JSON.stringify(userSerializeWithContext(value, ctx));
 } /** @internal Serializes with an existing context for nested/cyclic object graphs.
 @param value - The value to serialize
@@ -123,7 +123,7 @@ export function userSerializeWithContext(
     result['userName'] = value.name;
     {
         const __flattened = userMetadataSerializeWithContext(value.metadata, ctx);
-        const { __type: _, __id: __, ...rest } = __flattened as any;
+        const { __type: _, __id: __, ...rest } = __flattened as any; // tag field name is configurable via `tag` option
         Object.assign(result, rest);
     }
     return result;

package/package.json

@@ -25,7 +25,7 @@
   "main": "dist/index.js",
   "name": "@macroforge/mcp-server",
   "peerDependencies": {
-    "macroforge": "^0.1.76"
+    "macroforge": "^0.1.78"
   },
   "peerDependenciesMeta": {
     "macroforge": {
@@ -46,5 +46,5 @@
     "test": "node --test tests/**/*.test.js"
   },
   "type": "module",
-  "version": "0.1.76"
+  "version": "0.1.78"
 }