@macroforge/mcp-server 0.1.37 → 0.1.39

package/docs/api/api-overview.md

@@ -2,14 +2,14 @@
  <span class="stats svelte-1c8t0id">52 exported items *Macroforge provides a programmatic API for expanding macros in TypeScript code.*
  ## Overview
  ```
-import {
+import &#123;
   expandSync,
   transformSync,
   checkSyntax,
   parseImportSources,
   NativePlugin,
   PositionMapper
-} from "macroforge";
+&#125; from "macroforge";
 ``` ## Core Functions
  | Function | Description |
 | --- | --- |
@@ -24,28 +24,28 @@ import {
 | [`PositionMapper`](../docs/api/position-mapper) | Maps positions between original and expanded code |
  ## Quick Example
  ```
-import { expandSync } from "macroforge";
+import &#123; expandSync &#125; from "macroforge";
 
-const sourceCode = `
+const sourceCode = \`
 /** @derive(Debug) */
-class User {
+class User &#123;
   name: string;
-  constructor(name: string) {
+  constructor(name: string) &#123;
     this.name = name;
-  }
-}
-`;
+  &#125;
+&#125;
+\`;
 
-const result = expandSync(sourceCode, "user.ts", {
+const result = expandSync(sourceCode, "user.ts", &#123;
   keepDecorators: false
-});
+&#125;);
 
 console.log(result.code);
 // Output: class with toString() method generated
 
-if (result.diagnostics.length > 0) {
+if (result.diagnostics.length > 0) &#123;
   console.error("Errors:", result.diagnostics);
-}
+&#125;
 ``` ## Detailed Reference
  - [`expandSync()`](../docs/api/expand-sync) - Full options and return types
  - [`transformSync()`](../docs/api/transform-sync) - Transform with source maps

package/docs/api/expand-sync.md

@@ -15,13 +15,13 @@ function expandSync(
 | `options` | `ExpandOptions` | Optional configuration |
  ## ExpandOptions
  ```
-interface ExpandOptions {
+interface ExpandOptions {
   // Keep @derive decorators in output (default: false)
   keepDecorators?: boolean;
-}
+}
 ``` ## ExpandResult
  ```
-interface ExpandResult {
+interface ExpandResult {
   // Transformed TypeScript code
   code: string;
 
@@ -36,17 +36,17 @@ interface ExpandResult {
 
   // Position mapping data for source maps
   sourceMapping?: SourceMappingResult;
-}
+}
 ``` ## MacroDiagnostic
  ```
-interface MacroDiagnostic {
+interface MacroDiagnostic {
   message: string;
   severity: "error" | "warning" | "info";
-  span: {
+  span: {
     start: number;
     end: number;
-  };
-}
+  };
+}
 ``` ## Example
  ```
 import { expandSync } from "macroforge";

package/docs/api/native-plugin.md

@@ -13,10 +13,10 @@ processFile(
   options?: ProcessFileOptions
 ): ExpandResult
 ``` ```
-interface ProcessFileOptions {
+interface ProcessFileOptions {
   // Cache key - if unchanged, returns cached result
   version?: string;
-}
+}
 ``` ### getMapper()
  Get the position mapper for a previously processed file:
  ```
@@ -39,36 +39,36 @@ setLogFile(path: string): void
 const plugin = new NativePlugin();
 
 // First call - performs expansion
-const result1 = plugin.processFile("user.ts", code, { version: "1" });
+const result1 = plugin.processFile("user.ts", code, { version: "1" });
 
 // Same version - returns cached result instantly
-const result2 = plugin.processFile("user.ts", code, { version: "1" });
+const result2 = plugin.processFile("user.ts", code, { version: "1" });
 
 // Different version - re-expands
-const result3 = plugin.processFile("user.ts", newCode, { version: "2" });
+const result3 = plugin.processFile("user.ts", newCode, { version: "2" });
 ``` ## Example: Language Server Integration
  ```
-import { NativePlugin } from "macroforge";
+import { NativePlugin } from "macroforge";
 
-class MacroforgeLanguageService {
+class MacroforgeLanguageService {
   private plugin = new NativePlugin();
 
-  processDocument(uri: string, content: string, version: number) {
+  processDocument(uri: string, content: string, version: number) {
     // Process with version-based caching
-    const result = this.plugin.processFile(uri, content, {
+    const result = this.plugin.processFile(uri, content, {
       version: String(version)
-    });
+    });
 
     // Get mapper for position translation
     const mapper = this.plugin.getMapper(uri);
 
-    return { result, mapper };
-  }
+    return { result, mapper };
+  }
 
-  getSemanticDiagnostics(uri: string, diagnostics: Diagnostic[]) {
+  getSemanticDiagnostics(uri: string, diagnostics: Diagnostic[]) {
     // Map positions from expanded to original
     return this.plugin.mapDiagnostics(uri, diagnostics);
-  }
-}
+  }
+}
 ``` ## Thread Safety
  The `NativePlugin` class is thread-safe and can be used from multiple async contexts. Each file is processed in an isolated thread with its own stack space.

package/docs/api/position-mapper.md

@@ -2,16 +2,16 @@
   *Bidirectional position mapper for translating between original and expanded source positions. This mapper enables IDE features like error reporting, go-to-definition, and hover to work correctly with macro-expanded code by translating positions between the original source (what the user wrote) and the expanded source (what the compiler sees).*
  ## Getting a Mapper
  ```
-import { NativePlugin, PositionMapper } from "macroforge";
+import { NativePlugin, PositionMapper } from "macroforge";
 
 const plugin = new NativePlugin();
-const result = plugin.processFile("user.ts", code, { version: "1" });
+const result = plugin.processFile("user.ts", code, { version: "1" });
 
 // Get the mapper for this file
 const mapper = plugin.getMapper("user.ts");
-if (mapper) {
+if (mapper) {
   // Use the mapper...
-}
+}
 ``` ## Methods
  ### isEmpty()
  Check if the mapper has any mappings:
@@ -39,10 +39,10 @@ generatedBy(pos: number): string | null
  ```
 mapSpanToOriginal(start: number, length: number): SpanResult | null
 
-interface SpanResult {
+interface SpanResult {
   start: number;
   length: number;
-}
+}
 ``` ### mapSpanToExpanded()
  Map a span from original to expanded code:
  ```

package/docs/api/transform-sync.md

@@ -13,7 +13,7 @@ function transformSync(
 | `filepath` | `string` | File path (used for error reporting) |
  ## TransformResult
  ```
-interface TransformResult {
+interface TransformResult {
   // Transformed TypeScript code
   code: string;
 
@@ -25,7 +25,7 @@ interface TransformResult {
 
   // Macro expansion metadata
   metadata?: string;
-}
+}
 ``` ## Comparison with expandSync()
  | Feature | `expandSync` | `transformSync` |
 | --- | --- | --- |
@@ -35,29 +35,29 @@ interface TransformResult {
 | Use Case | General purpose | Build tools |
  ## Example
  ```
-import { transformSync } from "macroforge";
+import { transformSync } from "macroforge";
 
-const sourceCode = `
+const sourceCode = \`
 /** @derive(Debug) */
-class User {
+class User {
   name: string;
-}
-`;
+}
+\`;
 
 const result = transformSync(sourceCode, "user.ts");
 
 console.log(result.code);
 
-if (result.types) {
+if (result.types) {
   // Write to .d.ts file
   fs.writeFileSync("user.d.ts", result.types);
-}
+}
 
-if (result.metadata) {
+if (result.metadata) {
   // Parse and use metadata
   const meta = JSON.parse(result.metadata);
   console.log("Macros expanded:", meta);
-}
+}
 ``` ## When to Use
  Use `transformSync` when:
  - Building custom integrations

package/docs/builtin-macros/clone.md

@@ -8,18 +8,11 @@ independent copies of values.
 
 | Type | Generated Code | Description |
 |------|----------------|-------------|
-| Class | `clone(): ClassName` | Instance method creating a new instance with copied fields |
-| Enum | `cloneEnumName(value: EnumName): EnumName` | Standalone function (enums are primitives, returns value as-is) |
-| Interface | `cloneInterfaceName(value: InterfaceName): InterfaceName` | Standalone function creating a new object literal |
-| Type Alias | `cloneTypeName(value: TypeName): TypeName` | Standalone function with spread copy for objects |
+| 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 |
 
-## Configuration
-
-The `functionNamingStyle` option in `macroforge.json` controls naming:
-- `"prefix"` (default): Prefixes with type name (e.g., `myTypeClone`)
-- `"suffix"`: Suffixes with type name (e.g., `cloneMyType`)
-- `"generic"`: Uses TypeScript generics (e.g., `clone<T extends MyType>`)
-- `"namespace"`: Legacy namespace wrapping
 
 ## Cloning Strategy
 
@@ -34,28 +27,55 @@ and the caller should clone them explicitly.
 
 ## Example
 
-```typescript
-@derive(Clone)
+```typescript before
+/** @derive(Clone) */
+class Point {
+    x: number;
+    y: number;
+}
+```
+
+```typescript after
 class Point {
     x: number;
     y: number;
+
+    static clone(value: Point): Point {
+        return pointClone(value);
+    }
+}
+
+export function pointClone(value: Point): Point {
+    const cloned = Object.create(Object.getPrototypeOf(value));
+    cloned.x = value.x;
+    cloned.y = value.y;
+    return cloned;
 }
+```
+
+Generated output:
+
+```typescript
+class Point {
+    x: number;
+    y: number;
 
-// Generated:
-// clone(): Point {
-//     const cloned = Object.create(Object.getPrototypeOf(this));
-//     cloned.x = this.x;
-//     cloned.y = this.y;
-//     return cloned;
-// }
+    static clone(value: Point): Point {
+        return pointClone(value);
+    }
+}
 
-const p1 = new Point();
-const p2 = p1.clone(); // Creates a new Point with same values
+export function pointClone(value: Point): Point {
+    const cloned = Object.create(Object.getPrototypeOf(value));
+    cloned.x = value.x;
+    cloned.y = value.y;
+    return cloned;
+}
 ```
 
 ## Implementation Notes
 
-- **Classes**: Uses `Object.create(Object.getPrototypeOf(this))` to preserve
+- **Classes**: Uses `Object.create(Object.getPrototypeOf(value))` to preserve
   the prototype chain, ensuring `instanceof` checks work correctly
 - **Enums**: Simply returns the value (enums are primitives in TypeScript)
 - **Interfaces/Type Aliases**: Creates new object literals with spread operator

package/docs/builtin-macros/debug.md

@@ -5,24 +5,17 @@ TypeScript classes, interfaces, enums, and type aliases.
 
 ## Generated Output
 
-**Classes**: Generates an instance method returning a string
-like `"ClassName { field1: value1, field2: value2 }"`.
+**Classes**: Generates a standalone function `classNameToString(value)` and a static wrapper
+method `static toString(value)` returning a string like `"ClassName { field1: value1, field2: value2 }"`.
 
-**Enums**: Generates a standalone function `toStringEnumName(value)` that performs
+**Enums**: Generates a standalone function `enumNameToString(value)` that performs
 reverse lookup on numeric enums.
 
-**Interfaces**: Generates a standalone function `toStringInterfaceName(value)`.
+**Interfaces**: Generates a standalone function `interfaceNameToString(value)`.
 
 **Type Aliases**: Generates a standalone function using JSON.stringify for
 complex types, or field enumeration for object types.
 
-## Configuration
-
-The `functionNamingStyle` option in `macroforge.json` controls naming:
-- `"prefix"` (default): Prefixes with type name (e.g., `myTypeToString`)
-- `"suffix"`: Suffixes with type name (e.g., `toStringMyType`)
-- `"generic"`: Uses TypeScript generics (e.g., `toString<T extends MyType>`)
-- `"namespace"`: Legacy namespace wrapping
 
 ## Field-Level Options
 
@@ -33,20 +26,59 @@ The `@debug` decorator supports:
 
 ## Example
 
+```typescript before
+/** @derive(Debug) */
+class User {
+    /** @debug({ rename: "id" }) */
+    userId: number;
+
+    /** @debug({ skip: true }) */
+    password: string;
+
+    email: string;
+}
+```
+
+```typescript after
+class User {
+    userId: number;
+
+    password: string;
+
+    email: string;
+
+    static toString(value: User): string {
+        return userToString(value);
+    }
+}
+
+export function userToString(value: User): string {
+    const parts: string[] = [];
+    parts.push('id: ' + value.userId);
+    parts.push('email: ' + value.email);
+    return 'User { ' + parts.join(', ') + ' }';
+}
+```
+
+Generated output:
+
 ```typescript
-@derive(Debug)
 class User {
-    @debug(rename = "id")
     userId: number;
 
-    @debug(skip)
     password: string;
 
     email: string;
+
+    static toString(value: User): string {
+        return userToString(value);
+    }
 }
 
-// Generated:
-// toString(): string {
-//     return "User { id: " + this.userId + ", email: " + this.email + " }";
-// }
+export function userToString(value: User): string {
+    const parts: string[] = [];
+    parts.push('id: ' + value.userId);
+    parts.push('email: ' + value.email);
+    return 'User { ' + parts.join(', ') + ' }';
+}
 ```

package/docs/builtin-macros/default.md

@@ -13,13 +13,6 @@ a standard way to create "zero" or "empty" instances of types.
 | Interface | `defaultValueInterfaceName(): InterfaceName` | Standalone function returning object literal |
 | Type Alias | `defaultValueTypeName(): TypeName` | Standalone function with type-appropriate default |
 
-## Configuration
-
-The `functionNamingStyle` option in `macroforge.json` controls naming:
-- `"prefix"` (default): Prefixes with type name (e.g., `myTypeDefaultValue`)
-- `"suffix"`: Suffixes with type name (e.g., `defaultValueMyType`)
-- `"generic"`: Uses TypeScript generics (e.g., `defaultValue<T extends MyType>`)
-- `"namespace"`: Legacy namespace wrapping
 
 ## Default Values by Type
 
@@ -50,47 +43,105 @@ The `@default` decorator allows specifying explicit default values:
 
 ## Example
 
-```typescript
-@derive(Default)
+```typescript before
+/** @derive(Default) */
 class UserSettings {
-    @default("light")
+    /** @default("light") */
     theme: string;
 
-    @default(10)
+    /** @default(10) */
     pageSize: number;
 
-    notifications: boolean;  // Uses type default: false
+    notifications: boolean; // Uses type default: false
 }
+```
+
+```typescript after
+class UserSettings {
+    theme: string;
 
-// Generated:
-// static defaultValue(): UserSettings {
-//     const instance = new UserSettings();
-//     instance.theme = "light";
-//     instance.pageSize = 10;
-//     instance.notifications = false;
-//     return instance;
-// }
+    pageSize: number;
+
+    notifications: boolean; // Uses type default: false
+
+    static defaultValue(): UserSettings {
+        const instance = new UserSettings();
+        instance.theme = 'light';
+        instance.pageSize = 10;
+        instance.notifications = false;
+        return instance;
+    }
+}
+```
+
+Generated output:
+
+```typescript
+class UserSettings {
+    theme: string;
+
+    pageSize: number;
+
+    notifications: boolean; // Uses type default: false
+
+    static defaultValue(): UserSettings {
+        const instance = new UserSettings();
+        instance.theme = 'light';
+        instance.pageSize = 10;
+        instance.notifications = false;
+        return instance;
+    }
+}
 ```
 
 ## Enum Defaults
 
 For enums, mark one variant with `@default`:
 
+```typescript before
+/** @derive(Default) */
+enum Status {
+    /** @default */
+    Pending,
+    Active,
+    Completed
+}
+```
+
+```typescript after
+enum Status {
+    /** @default */
+    Pending,
+    Active,
+    Completed
+}
+
+export function statusDefaultValue(): Status {
+    return Status.Pending;
+}
+
+export const Status = {
+    defaultValue: statusDefaultValue
+} as const;
+```
+
+Generated output:
+
 ```typescript
-@derive(Default)
 enum Status {
-    @default
+    /** @default */
     Pending,
     Active,
     Completed
 }
 
-// Generated:
-// export namespace Status {
-//     export function defaultValue(): Status {
-//         return Status.Pending;
-//     }
-// }
+export function statusDefaultValue(): Status {
+    return Status.Pending;
+}
+
+export const Status = {
+    defaultValue: statusDefaultValue
+} as const;
 ```
 
 ## Error Handling

package/docs/builtin-macros/deserialize/cycleforward-reference-support.md

@@ -0,0 +1,11 @@
+## Cycle/Forward-Reference Support
+
+Uses deferred patching to handle references:
+
+1. When encountering `{ "__ref": id }`, returns a `PendingRef` marker
+2. Continues deserializing other fields
+3. After all objects are created, `ctx.applyPatches()` resolves all pending references
+
+References only apply to object-shaped, serializable values. The generator avoids probing for
+`__ref` on primitive-like fields (including literal unions and `T | null` where `T` is primitive-like),
+and it parses `Date` / `Date | null` from ISO strings without treating them as references.