@macroforge/mcp-server 0.1.33 → 0.1.35

package/docs/builtin-macros/hash.md

@@ -1,123 +1,81 @@
 # Hash
 
-*The `Hash` macro generates a `hashCode()` method that computes a numeric hash value based on field values.*
+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
+## Generated Output
 
-<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
+| 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 |
 
-```typescript
-const p1 = new Point(10, 20);
-const p2 = new Point(10, 20);
-const p3 = new Point(5, 5);
+## Configuration
 
-console.log(p1.hashCode()); // Same hash
-console.log(p2.hashCode()); // Same hash (equal values = equal hash)
-console.log(p3.hashCode()); // Different hash
-```
+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
 
 ## 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:
-
-<MacroExample before={data.examples.skip.before} after={data.examples.skip.after} />
-
-```typescript
-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:
-
-<InteractiveMacro code={`/** @derive(Hash, PartialEq) */
-class Product {
-  sku: string;
-  name: string;
-
-  constructor(sku: string, name: string) {
-    this.sku = sku;
-    this.name = name;
-  }
-}`} />
-
-```typescript
-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:
+Uses the standard polynomial rolling hash algorithm:
 
-<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
-
-```typescript
-const p: Point = { x: 10, y: 20 };
-console.log(Point.hashCode(p)); // numeric hash value
+```text
+hash = 17  // Initial seed
+for each field:
+    hash = (hash * 31 + fieldHash) | 0  // Bitwise OR keeps it 32-bit integer
 ```
 
-## Enum Support
+This algorithm is consistent with Java's `Objects.hash()` implementation.
 
-Hash works with enums. For string enums, it hashes the string value; for numeric enums, it uses the numeric value directly:
+## Type-Specific Hashing
 
-<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
+| 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 |
 
-```typescript
-console.log(Status.hashCode(Status.Active));   // consistent hash
-console.log(Status.hashCode(Status.Inactive)); // different hash
-```
+## Field-Level Options
 
-## Type Alias Support
+The `@hash` decorator supports:
 
-Hash works with type aliases. For object types, it hashes each field:
+- `skip` - Exclude the field from hash calculation
 
-<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
+## Example
 
 ```typescript
-const loc: Coordinates = { lat: 40.7128, lng: -74.0060 };
-console.log(Coordinates.hashCode(loc));
+@derive(Hash, PartialEq)
+class User {
+    id: number;
+    name: string;
+
+    @hash(skip)  // Cached value shouldn't affect hash
+    cachedScore: number;
+}
+
+// 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;
+// }
 ```
 
-For union types, it uses JSON stringification as a fallback:
+## Hash Contract
 
-<InteractiveMacro code={`/** @derive(Hash) */
-type Result = "success" | "error" | "pending";`} />
-
-```typescript
-console.log(Result.hashCode("success")); // hash of "success" string
-console.log(Result.hashCode("error"));   // hash of "error" string
-```
+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/macros-overview.md

@@ -1,50 +1,20 @@
 # Built-in Macros
-
-*Macroforge comes with built-in derive macros that cover the most common code generation needs. All macros work with classes, interfaces, enums, and type aliases.*
-
-## Overview
-
-| [`Debug`]({base}/docs/builtin-macros/debug) 
-| `toString(): string` 
-| Human-readable string representation 
-
-| [`Clone`]({base}/docs/builtin-macros/clone) 
-| `clone(): T` 
-| Creates a deep copy of the object 
-
-| [`Default`]({base}/docs/builtin-macros/default) 
-| `static default(): T` 
-| Creates an instance with default values 
-
-| [`Hash`]({base}/docs/builtin-macros/hash) 
-| `hashCode(): number` 
-| Generates a hash code for the object 
-
-| [`PartialEq`]({base}/docs/builtin-macros/partial-eq) 
-| `equals(other: T): boolean` 
-| Value equality comparison 
-
-| [`Ord`]({base}/docs/builtin-macros/ord) 
-| `compare(other: T): number` 
-| Total ordering comparison (-1, 0, 1) 
-
-| [`PartialOrd`]({base}/docs/builtin-macros/partial-ord) 
-| `partialCompare(other: T): number | null` 
-| Partial ordering comparison 
-
-| [`Serialize`]({base}/docs/builtin-macros/serialize) 
-| `toJSON(): Record<string, unknown>` 
-| JSON serialization with type handling 
-
-| [`Deserialize`]({base}/docs/builtin-macros/deserialize) 
-| `static 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
+ *Macroforge comes with built-in derive macros that cover the most common code generation needs. All macros work with classes, interfaces, enums, and type aliases.*
+ ## Overview
+ | Macro | Generates | Description |
+| --- | --- | --- |
+| [`Debug`](../docs/builtin-macros/debug) | `toString(): string` | Human-readable string representation |
+| [`Clone`](../docs/builtin-macros/clone) | `clone(): T` | Creates a deep copy of the object |
+| [`Default`](../docs/builtin-macros/default) | `static default(): T` | Creates an instance with default values |
+| [`Hash`](../docs/builtin-macros/hash) | `hashCode(): number` | Generates a hash code for the object |
+| [`PartialEq`](../docs/builtin-macros/partial-eq) | `equals(other: T): boolean` | Value equality comparison |
+| [`Ord`](../docs/builtin-macros/ord) | `compare(other: T): number` | Total ordering comparison (-1, 0, 1) |
+| [`PartialOrd`](../docs/builtin-macros/partial-ord) | `partialCompare(other: T): number | null` | Partial ordering comparison |
+| [`Serialize`](../docs/builtin-macros/serialize) | `toJSON(): Record<string, unknown>` | JSON serialization with type handling |
+| [`Deserialize`](../docs/builtin-macros/deserialize) | `static fromJSON(data: unknown): T` | JSON deserialization with validation |
+ ## Using Built-in Macros
+ Built-in macros don't require imports. Just use them with `@derive`:
+ ```
 /** @derive(Debug, Clone, PartialEq) */
 class User {
   name: string;
@@ -55,13 +25,9 @@ class User {
     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
+``` ## 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:
+ ```
 /** @derive(Debug, Clone, PartialEq) */
 interface Point {
   x: number;
@@ -82,13 +48,9 @@ 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
-```
-
-## Enum Support
-
-All built-in macros work with enums. For enums, methods are generated as functions in a namespace with the same name:
-
-```typescript
+``` ## Enum Support
+ All built-in macros work with enums. For enums, methods are generated as functions in a namespace with the same name:
+ ```
 /** @derive(Debug, Clone, PartialEq, Serialize, Deserialize) */
 enum Status {
   Active = "active",
@@ -111,13 +73,9 @@ 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
+``` ## Type Alias Support
+ All built-in macros work with type aliases. For object type aliases, field-aware methods are generated in a namespace:
+ ```
 /** @derive(Debug, Clone, PartialEq, Serialize, Deserialize) */
 type Point = {
   x: number;
@@ -138,24 +96,17 @@ 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
+``` Union type aliases also work, using JSON-based implementations:
+ ```
 /** @derive(Debug, PartialEq) */
 type ApiStatus = "loading" | "success" | "error";
 
 const status: ApiStatus = "success";
-console.log(ApiStatus.toString(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
+``` ## Combining Macros
+ All macros can be used together. They don't conflict and each generates independent methods:
+ ```
 const user = new User("Alice", 30);
 
 // Debug
@@ -168,26 +119,14 @@ 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) - Deep copying for all field types
-
-- [**Default**]({base}/docs/builtin-macros/default) - Default value generation with field attributes
-
-- [**Hash**]({base}/docs/builtin-macros/hash) - Hash code generation for use in maps and sets
-
-- [**PartialEq**]({base}/docs/builtin-macros/partial-eq) - Value-based equality comparison
-
-- [**Ord**]({base}/docs/builtin-macros/ord) - Total ordering for sorting
-
-- [**PartialOrd**]({base}/docs/builtin-macros/partial-ord) - Partial ordering comparison
-
-- [**Serialize**]({base}/docs/builtin-macros/serialize) - JSON serialization with serde-style options
-
-- [**Deserialize**]({base}/docs/builtin-macros/deserialize) - JSON deserialization with validation
+``` ## Detailed Documentation
+ Each macro has its own options and behaviors:
+ - [**Debug**](../docs/builtin-macros/debug) - Customizable field renaming and skipping
+ - [**Clone**](../docs/builtin-macros/clone) - Deep copying for all field types
+ - [**Default**](../docs/builtin-macros/default) - Default value generation with field attributes
+ - [**Hash**](../docs/builtin-macros/hash) - Hash code generation for use in maps and sets
+ - [**PartialEq**](../docs/builtin-macros/partial-eq) - Value-based equality comparison
+ - [**Ord**](../docs/builtin-macros/ord) - Total ordering for sorting
+ - [**PartialOrd**](../docs/builtin-macros/partial-ord) - Partial ordering comparison
+ - [**Serialize**](../docs/builtin-macros/serialize) - JSON serialization with serde-style options
+ - [**Deserialize**](../docs/builtin-macros/deserialize) - JSON deserialization with validation

package/docs/builtin-macros/ord.md

@@ -1,159 +1,91 @@
 # Ord
 
-*The `Ord` macro generates a `compareTo()` method that implements total ordering, always returning `-1`, `0`, or `1`.*
+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
+## Generated Output
 
-<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
+| 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 |
 
-```typescript
-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)
-```
-
-## 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
+## Configuration
 
-- `Object` → Calls `compareTo()` if available, otherwise 0
-
-- `null/undefined` → Treated as equal (returns 0)
+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
 
 ## Return Values
 
-The `compareTo()` method always returns:
-
-- `-1` → `this` is less than `other`
-
-- `0` → `this` equals `other`
+Unlike `PartialOrd`, `Ord` provides **total ordering** - every pair of values
+can be compared:
 
-- `1` → `this` is greater than `other`
+- **-1**: `this` is less than `other`
+- **0**: `this` is equal to `other`
+- **1**: `this` is greater than `other`
 
-Unlike `PartialOrd`, the `Ord` macro never returns `null` - it provides total ordering.
+The method **never returns null** - all values must be comparable.
 
-## Field Options
+## Comparison Strategy
 
-### @ord(skip)
+Fields are compared **lexicographically** in declaration order:
 
-Use `@ord(skip)` to exclude a field from ordering comparison:
+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
 
-<MacroExample before={data.examples.skip.before} after={data.examples.skip.after} />
-
-```typescript
-const t1 = new Task(1, "Bug fix", new Date("2024-01-01"));
-const t2 = new Task(1, "Bug fix", new Date("2024-12-01"));
+## Type-Specific Comparisons
 
-console.log(t1.compareTo(t2)); // 0 (createdAt is skipped)
-```
+| 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 |
 
-## Sorting Arrays
+## Field-Level Options
 
-The generated `compareTo()` method works directly with `Array.sort()`:
+The `@ord` decorator supports:
 
-<InteractiveMacro code={`/** @derive(Ord) */
-class Score {
-  points: number;
-  name: string;
+- `skip` - Exclude the field from ordering comparison
 
-  constructor(points: number, name: string) {
-    this.points = points;
-    this.name = name;
-  }
-}`} />
+## Example
 
 ```typescript
-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:
-
-<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
-
-```typescript
-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:
-
-<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
-
-```typescript
-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:
-
-<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
-
-```typescript
-const c1: Coordinate = { x: 10, y: 20 };
-const c2: Coordinate = { x: 10, y: 30 };
-
-console.log(Coordinate.compareTo(c1, c2)); // -1 (c1 < c2)
+@derive(Ord)
+class Version {
+    major: number;
+    minor: number;
+    patch: number;
+}
+
+// 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 of a type are comparable. Use `PartialOrd` when some values might be incomparable (e.g., different types at runtime).
-
-<InteractiveMacro code={`// 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;
-  }
-}`} />
-
-```typescript
-const v1 = new Version(1, 0);
-const v2 = new Version(2, 0);
-console.log(v1.compareTo(v2)); // Always -1, 0, or 1
-```
+- Use **Ord** when all values are comparable (total ordering)
+- Use **PartialOrd** when some values may be incomparable (returns `Option<number>`)