@macroforge/mcp-server 0.1.33 → 0.1.35

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

@@ -1,204 +1,78 @@
 # PartialEq
 
-*The `PartialEq` macro generates an `equals()` method for value-based equality comparison between objects.*
+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.
 
-## Basic Usage
+## Generated Output
 
-<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
+| 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 |
 
-```typescript
-const p1 = new Point(10, 20);
-const p2 = new Point(10, 20);
-const p3 = new Point(5, 5);
-
-console.log(p1.equals(p2)); // true (same values)
-console.log(p1.equals(p3)); // false (different values)
-console.log(p1 === p2);     // false (different references)
-```
-
-## How It Works
+## Configuration
 
-The PartialEq macro performs field-by-field comparison using these strategies:
+The `functionNamingStyle` option in `macroforge.json` controls naming:
+- `"suffix"` (default): Suffixes with type name (e.g., `equalsMyType`)
+- `"prefix"`: Prefixes with type name (e.g., `myTypeEquals`)
+- `"generic"`: Uses TypeScript generics (e.g., `equals<T extends MyType>`)
+- `"namespace"`: Legacy namespace wrapping
 
-- **Primitives** (string, number, boolean, null, undefined) → Strict equality (`===`)
+## Comparison Strategy
 
-- **Date** → Compares timestamps via `getTime()`
+The generated equality check:
 
-- **Array** → Length check + element-by-element comparison
+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
 
-- **Map** → Size check + entry comparison
+## Type-Specific Comparisons
 
-- **Set** → Size check + membership verification
+| 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 `===` |
 
-- **Objects** → Calls `equals()` if available, otherwise `===`
+## Field-Level Options
 
-## Field Options
+The `@partialEq` decorator supports:
 
-### @partialEq(skip)
+- `skip` - Exclude the field from equality comparison
 
-Use `@partialEq(skip)` to exclude a field from equality comparison:
-
-<MacroExample before={data.examples.skip.before} after={data.examples.skip.after} />
+## Example
 
 ```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.equals(user2)); // true (createdAt is skipped)
-```
-
-## Type Safety
-
-The generated `equals()` method accepts `unknown` and performs runtime type checking:
-
-<InteractiveMacro code={`/** @derive(PartialEq) */
+@derive(PartialEq, Hash)
 class User {
-  name: string;
-  constructor(name: string) {
-    this.name = name;
-  }
-}`} />
-
-```typescript
-const user = new User("Alice");
-
-console.log(user.equals(new User("Alice"))); // true
-console.log(user.equals("Alice")); // false (not a User instance)
-```
-
-## With Nested Objects
+    id: number;
+    name: string;
 
-For objects with nested fields, PartialEq recursively calls `equals()` if available:
-
-<InteractiveMacro code={`/** @derive(PartialEq) */
-class Address {
-  city: string;
-  zip: string;
-
-  constructor(city: string, zip: string) {
-    this.city = city;
-    this.zip = zip;
-  }
+    @partialEq(skip)  // Don't compare cached values
+    @hash(skip)
+    cachedScore: number;
 }
 
-/** @derive(PartialEq) */
-class Person {
-  name: string;
-  address: Address;
-
-  constructor(name: string, address: Address) {
-    this.name = name;
-    this.address = address;
-  }
-}`} />
-
-```typescript
-const addr1 = new Address("NYC", "10001");
-const addr2 = new Address("NYC", "10001");
-
-const p1 = new Person("Alice", addr1);
-const p2 = new Person("Alice", addr2);
-
-console.log(p1.equals(p2)); // true (deep equality via Address.equals)
-```
-
-## Interface Support
-
-PartialEq works with interfaces. For interfaces, a namespace is generated with an `equals` function:
-
-<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
-
-```typescript
-const p1: Point = { x: 10, y: 20 };
-const p2: Point = { x: 10, y: 20 };
-const p3: Point = { x: 5, y: 5 };
-
-console.log(Point.equals(p1, p2)); // true
-console.log(Point.equals(p1, p3)); // false
-```
-
-## Enum Support
-
-PartialEq works with enums. For enums, strict equality comparison is used:
-
-<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
-
-```typescript
-console.log(Status.equals(Status.Active, Status.Active));   // true
-console.log(Status.equals(Status.Active, Status.Inactive)); // false
-```
-
-## Type Alias Support
-
-PartialEq works with type aliases. For object types, field-by-field comparison is used:
-
-<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
-
-```typescript
-const p1: Point = { x: 10, y: 20 };
-const p2: Point = { x: 10, y: 20 };
-
-console.log(Point.equals(p1, p2)); // true
-```
-
-For union types, strict equality is used:
-
-<InteractiveMacro code={`/** @derive(PartialEq) */
-type ApiStatus = "loading" | "success" | "error";`} />
-
-```typescript
-console.log(ApiStatus.equals("success", "success")); // true
-console.log(ApiStatus.equals("success", "error"));   // false
+// 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;
+// }
 ```
 
-## Common Patterns
-
-### Finding Items in Arrays
-
-<InteractiveMacro code={`/** @derive(PartialEq) */
-class Product {
-  sku: string;
-  name: string;
-
-  constructor(sku: string, name: string) {
-    this.sku = sku;
-    this.name = name;
-  }
-}`} />
-
-```typescript
-const products = [
-  new Product("A1", "Widget"),
-  new Product("B2", "Gadget"),
-  new Product("C3", "Gizmo")
-];
-
-const target = new Product("B2", "Gadget");
-const found = products.find(p => p.equals(target));
+## Equality Contract
 
-console.log(found); // Product { sku: "B2", name: "Gadget" }
-```
-
-### Use with Hash
-
-When using objects as keys in Map-like structures, combine PartialEq with Hash:
-
-<InteractiveMacro code={`/** @derive(PartialEq, Hash) */
-class Key {
-  id: number;
-  type: string;
-
-  constructor(id: number, type: string) {
-    this.id = id;
-    this.type = type;
-  }
-}`} />
-
-```typescript
-const k1 = new Key(1, "user");
-const k2 = new Key(1, "user");
+When implementing `PartialEq`, consider also implementing `Hash`:
 
-// Equal objects should have equal hash codes
-console.log(k1.equals(k2));                   // true
-console.log(k1.hashCode() === k2.hashCode()); // true
-```
+- **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-ord.md

@@ -1,188 +1,96 @@
 # PartialOrd
 
-*The `PartialOrd` macro generates a `compareTo()` method that implements partial ordering, returning `-1`, `0`, `1`, or `null` for incomparable values.*
+The `PartialOrd` macro generates a `compareTo()` method for **partial ordering**
+comparison. This is analogous to Rust's `PartialOrd` trait, enabling comparison
+between values where some pairs may be incomparable.
 
-## Basic Usage
+## Generated Output
 
-<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
+| 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 |
 
-```typescript
-const t1 = new Temperature(20);
-const t2 = new Temperature(30);
-const t3 = new Temperature(20);
-
-console.log(t1.compareTo(t2)); // -1 (t1 < t2)
-console.log(t2.compareTo(t1)); // 1  (t2 > t1)
-console.log(t1.compareTo(t3)); // 0  (t1 == t3)
+## Configuration
 
-// Returns null for incomparable types
-console.log(t1.compareTo("not a Temperature")); // null
-```
+The `functionNamingStyle` option in `macroforge.json` controls naming:
+- `"suffix"` (default): Suffixes with type name (e.g., `partialCompareMyType`)
+- `"prefix"`: Prefixes with type name (e.g., `myTypePartialCompare`)
+- `"generic"`: Uses TypeScript generics (e.g., `partialCompare<T extends MyType>`)
+- `"namespace"`: Legacy namespace wrapping
 
 ## Return Values
 
-The `compareTo()` method returns:
-
-- `-1` → `this` is less than `other`
-
-- `0` → `this` equals `other`
-
-- `1` → `this` is greater than `other`
-
-- `null` → Values are incomparable (e.g., different types)
-
-## Comparison Logic
-
-The PartialOrd macro compares fields in declaration order with type checking:
-
-- `number` / `bigint` → Direct numeric comparison
-
-- `string` → Uses `localeCompare()`
-
-- `boolean` → `false < true`
+Unlike `Ord`, `PartialOrd` returns an `Option<number>` to handle incomparable values:
 
-- `Date` → Compares timestamps; returns `null` if not both Date instances
+- **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.none()**: Values are incomparable
 
-- `Array` → Lexicographic comparison; returns `null` if not both arrays
+## When to Use PartialOrd vs Ord
 
-- `Object` → Calls `compareTo()` if available
+- **PartialOrd**: When some values may not be comparable
+  - Example: Floating-point NaN values
+  - Example: Mixed-type unions
+  - Example: Type mismatches between objects
 
-- **Type mismatch** → Returns `null`
+- **Ord**: When all values are guaranteed comparable (total ordering)
 
-## 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 incomparable, return `Option.none()`
+3. If not equal, return that result wrapped in `Option.some()`
+4. Otherwise, compare next field
+5. Continue until a difference is found or all fields are equal
 
-<MacroExample before={data.examples.skip.before} after={data.examples.skip.after} />
+## Type-Specific Comparisons
 
-```typescript
-const i1 = new Item(10, "Widget", "A useful widget");
-const i2 = new Item(10, "Widget", "Different description");
-
-console.log(i1.compareTo(i2)); // 0 (description is skipped)
-```
+| 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() |
 
-## Handling Null Results
+## Field-Level Options
 
-When using PartialOrd, always handle the `null` case:
+The `@ord` decorator supports:
 
-<InteractiveMacro code={`/** @derive(PartialOrd) */
-class Value {
-  amount: number;
+- `skip` - Exclude the field from ordering comparison
 
-  constructor(amount: number) {
-    this.amount = amount;
-  }
-}`} />
+## Example
 
 ```typescript
-function safeCompare(a: Value, b: unknown): string {
-  const result = a.compareTo(b);
-  if (result === null) {
-    return "incomparable";
-  } else if (result < 0) {
-    return "less than";
-  } else if (result > 0) {
-    return "greater than";
-  } else {
-    return "equal";
-  }
+@derive(PartialOrd)
+class Temperature {
+    value: number | null;  // null represents "unknown"
+    unit: string;
 }
 
-const v = new Value(100);
-console.log(safeCompare(v, new Value(50)));  // "greater than"
-console.log(safeCompare(v, "string"));       // "incomparable"
-```
-
-## Sorting with PartialOrd
-
-When sorting, handle `null` values appropriately:
-
-<InteractiveMacro code={`/** @derive(PartialOrd) */
-class Score {
-  value: number;
-
-  constructor(value: number) {
-    this.value = value;
-  }
-}`} />
-
-```typescript
-const scores = [
-  new Score(100),
-  new Score(50),
-  new Score(75)
-];
-
-// Safe sort that handles null (treats null as equal)
-scores.sort((a, b) => a.compareTo(b) ?? 0);
-// Result: [Score(50), Score(75), Score(100)]
-```
-
-## Interface Support
-
-PartialOrd 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 m1: Measurement = { value: 10, unit: "kg" };
-const m2: Measurement = { value: 10, unit: "lb" };
-
-console.log(Measurement.compareTo(m1, m2)); // 1 (kg > lb alphabetically)
-```
-
-## Enum Support
-
-PartialOrd works with enums:
-
-<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
-
-```typescript
-console.log(Size.compareTo(Size.Small, Size.Large)); // -1
-console.log(Size.compareTo(Size.Large, Size.Small)); // 1
-```
-
-## Type Alias Support
-
-PartialOrd works with type aliases:
-
-<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
-
-```typescript
-const i1: Interval = { start: 0, end: 10 };
-const i2: Interval = { start: 0, end: 20 };
-
-console.log(Interval.compareTo(i1, i2)); // -1
+// 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);
+// }
 ```
 
-## PartialOrd vs Ord
+## Required Import
 
-Choose between `Ord` and `PartialOrd` based on your use case:
-
-- **Ord** → Use when all values are always comparable (never returns null)
-
-- **PartialOrd** → Use when comparing with `unknown` types or when some values might be incomparable
-
-<InteractiveMacro code={`// PartialOrd is safer for public APIs that accept unknown input
-/** @derive(PartialOrd) */
-class SafeValue {
-  data: number;
-  constructor(data: number) {
-    this.data = data;
-  }
-
-  // Can safely compare with any value
-  isGreaterThan(other: unknown): boolean {
-    const result = this.compareTo(other);
-    return result !== null && result > 0;
-  }
-}`} />
-
-```typescript
-const safe = new SafeValue(100);
-console.log(safe.isGreaterThan(new SafeValue(50)));  // true
-console.log(safe.isGreaterThan("invalid"));          // false
-```
+The generated code automatically adds an import for `Option` from `macroforge/utils`.