@macroforge/mcp-server 0.1.32 → 0.1.34

package/docs/api/position-mapper.md

@@ -1,10 +1,7 @@
 # PositionMapper
-
-*Maps positions between original source code and macro-expanded code. Essential for accurate error reporting and debugging.*
-
-## Getting a Mapper
-
-```typescript
+  *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";
 
 const plugin = new NativePlugin();
@@ -15,76 +12,43 @@ const mapper = plugin.getMapper("user.ts");
 if (mapper) {
   // Use the mapper...
 }
-```
-
-## Methods
-
-### isEmpty()
-
-Check if the mapper has any mappings:
-
-```typescript
+``` ## Methods
+ ### isEmpty()
+ Check if the mapper has any mappings:
+ ```
 isEmpty(): boolean
-```
-
-### originalToExpanded()
-
-Map a position from original to expanded code:
-
-```typescript
+``` ### originalToExpanded()
+ Map a position from original to expanded code:
+ ```
 originalToExpanded(pos: number): number
-```
-
-### expandedToOriginal()
-
-Map a position from expanded to original code:
-
-```typescript
+``` ### expandedToOriginal()
+ Map a position from expanded to original code:
+ ```
 expandedToOriginal(pos: number): number | null
-```
-
-Returns `null` if the position is in generated code.
-
-### isInGenerated()
-
-Check if a position is in macro-generated code:
-
-```typescript
+``` Returns `null` if the position is in generated code.
+ ### isInGenerated()
+ Check if a position is in macro-generated code:
+ ```
 isInGenerated(pos: number): boolean
-```
-
-### generatedBy()
-
-Get the name of the macro that generated code at a position:
-
-```typescript
+``` ### generatedBy()
+ Get the name of the macro that generated code at a position:
+ ```
 generatedBy(pos: number): string | null
-```
-
-### mapSpanToOriginal()
-
-Map a span (range) from expanded to original code:
-
-```typescript
+``` ### mapSpanToOriginal()
+ Map a span (range) from expanded to original code:
+ ```
 mapSpanToOriginal(start: number, length: number): SpanResult | null
 
 interface SpanResult {
   start: number;
   length: number;
 }
-```
-
-### mapSpanToExpanded()
-
-Map a span from original to expanded code:
-
-```typescript
+``` ### mapSpanToExpanded()
+ Map a span from original to expanded code:
+ ```
 mapSpanToExpanded(start: number, length: number): SpanResult
-```
-
-## Example: Error Position Mapping
-
-```typescript
+``` ## Example: Error Position Mapping
+ ```
 import { NativePlugin } from "macroforge";
 
 const plugin = new NativePlugin();
@@ -97,7 +61,7 @@ function mapError(filepath: string, expandedPos: number, message: string) {
   if (mapper.isInGenerated(expandedPos)) {
     const macroName = mapper.generatedBy(expandedPos);
     return {
-      message: \`Error in code generated by @derive(\${macroName}): \${message}\`,
+      message: `Error in code generated by @derive(${macroName}): ${message}`,
       // Find the @derive decorator position
       position: findDecoratorPosition(filepath)
     };
@@ -114,14 +78,8 @@ function mapError(filepath: string, expandedPos: number, message: string) {
 
   return null;
 }
-```
-
-## Performance
-
-Position mapping uses binary search with O(log n) complexity:
-
-- Fast lookups even for large files
-
-- Minimal memory overhead
-
-- Thread-safe access
+``` ## Performance
+ Position mapping uses binary search with O(log n) complexity:
+ - Fast lookups even for large files
+ - Minimal memory overhead
+ - Thread-safe access

package/docs/api/transform-sync.md

@@ -1,29 +1,18 @@
 # transformSync()
-
-*A lower-level transform function that returns additional metadata alongside the transformed code.*
-
-## Signature
-
-```typescript
+  *Synchronously transforms TypeScript code through the macro expansion system. This is similar to [`expand_sync`] but returns a [`TransformResult`] which includes source map information (when available).*
+ ## Signature
+ ```
 function transformSync(
   code: string,
   filepath: string
 ): TransformResult
-```
-
-## Parameters
-
-| `code` 
-| `string` 
-| TypeScript source code to transform 
-
-| `filepath` 
-| `string` 
-| File path (used for error reporting)
-
-## TransformResult
-
-```typescript
+``` ## Parameters
+ | Parameter | Type | Description |
+| --- | --- | --- |
+| `code` | `string` | TypeScript source code to transform |
+| `filepath` | `string` | File path (used for error reporting) |
+ ## TransformResult
+ ```
 interface TransformResult {
   // Transformed TypeScript code
   code: string;
@@ -37,37 +26,23 @@ interface TransformResult {
   // Macro expansion metadata
   metadata?: string;
 }
-```
-
-## Comparison with expandSync()
-
-| Options 
-| Yes 
-| No 
-
-| Diagnostics 
-| Yes 
-| No 
-
-| Source Mapping 
-| Yes 
-| Limited 
-
-| Use Case 
-| General purpose 
-| Build tools
-
-## Example
-
-```typescript
+``` ## Comparison with expandSync()
+ | Feature | `expandSync` | `transformSync` |
+| --- | --- | --- |
+| Options | Yes | No |
+| Diagnostics | Yes | No |
+| Source Mapping | Yes | Limited |
+| Use Case | General purpose | Build tools |
+ ## Example
+ ```
 import { transformSync } from "macroforge";
 
-const sourceCode = \`
+const sourceCode = `
 /** @derive(Debug) */
 class User {
   name: string;
 }
-\`;
+`;
 
 const result = transformSync(sourceCode, "user.ts");
 
@@ -83,16 +58,9 @@ if (result.metadata) {
   const meta = JSON.parse(result.metadata);
   console.log("Macros expanded:", meta);
 }
-```
-
-## When to Use
-
-Use `transformSync` when:
-
-- Building custom integrations
-
-- You need raw output without diagnostics
-
-- You're implementing a build tool plugin
-
-Use `expandSync` for most other use cases, as it provides better error handling.
+``` ## When to Use
+ Use `transformSync` when:
+ - Building custom integrations
+ - You need raw output without diagnostics
+ - You're implementing a build tool plugin
+ Use `expandSync` for most other use cases, as it provides better error handling.

package/docs/builtin-macros/clone.md

@@ -1,36 +1,82 @@
 # Clone
-
-*The `Clone` macro generates a `clone()` method that creates a copy of the object.*
-
-## Basic Usage
-
-<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
-
-```typescript
+  *The `Clone` macro generates a `clone()` method for deep copying objects. This is analogous to Rust's `Clone` trait, providing a way to create independent copies of values.*
+ ## Basic Usage
+ **Before:**
+```
+/** @derive(Clone) */
+class Point {
+    x: number;
+    y: number;
+
+    constructor(x: number, y: number) {
+        this.x = x;
+        this.y = y;
+    }
+}
+```  
+**After:**
+```
+class Point {
+    x: number;
+    y: number;
+
+    constructor(x: number, y: number) {
+        this.x = x;
+        this.y = y;
+    }
+
+    clone(): Point {
+        const cloned = Object.create(Object.getPrototypeOf(this));
+        cloned.x = this.x;
+        cloned.y = this.y;
+        return cloned;
+    }
+}
+``` ```
 const original = new Point(10, 20);
 const copy = original.clone();
 
 console.log(copy.x, copy.y); // 10, 20
 console.log(original === copy); // false (different instances)
+``` ## How It Works
+ The Clone macro:
+ 1. Creates a new instance of the class
+ 2. Passes all field values to the constructor
+ 3. Returns the new instance
+ This creates a **shallow clone** - primitive values are copied, but object references remain the same.
+ ## With Nested Objects
+ **Before:**
 ```
-
-## How It Works
-
-The Clone macro:
-
-1. Creates a new instance of the class
-
-2. Passes all field values to the constructor
-
-3. Returns the new instance
-
-This creates a **shallow clone** - primitive values are copied, but object references remain the same.
-
-## With Nested Objects
-
-<MacroExample before={data.examples.nested.before} after={data.examples.nested.after} />
-
-```typescript
+/** @derive(Clone) */
+class User {
+    name: string;
+    address: { city: string; zip: string };
+
+    constructor(name: string, address: { city: string; zip: string }) {
+        this.name = name;
+        this.address = address;
+    }
+}
+```  
+**After:**
+```
+class User {
+    name: string;
+    address: { city: string; zip: string };
+
+    constructor(name: string, address: { city: string; zip: string }) {
+        this.name = name;
+        this.address = address;
+    }
+
+    clone(): User {
+        const cloned = Object.create(Object.getPrototypeOf(this));
+        cloned.name = this.name;
+        cloned.address = this.address;
+        return cloned;
+    }
+}
+``` ```
 const original = new User("Alice", { city: "NYC", zip: "10001" });
 const copy = original.clone();
 
@@ -40,15 +86,12 @@ console.log(original.address === copy.address); // true
 // Modifying the copy's address affects the original
 copy.address.city = "LA";
 console.log(original.address.city); // "LA"
+``` For deep cloning of nested objects, you would need to implement custom clone methods or use a deep clone utility.
+ ## Combining with PartialEq
+ Clone works well with PartialEq for creating independent copies that compare as equal:
+ **Source:**
 ```
-
-For deep cloning of nested objects, you would need to implement custom clone methods or use a deep clone utility.
-
-## Combining with PartialEq
-
-Clone works well with PartialEq for creating independent copies that compare as equal:
-
-<InteractiveMacro code={`/** @derive(Clone, PartialEq) */
+/** @derive(Clone, PartialEq) */
 class Point {
   x: number;
   y: number;
@@ -57,64 +100,103 @@ class Point {
     this.x = x;
     this.y = y;
   }
-}`} />
-
-```typescript
+}
+```  ```
 const original = new Point(10, 20);
 const copy = original.clone();
 
 console.log(original === copy);       // false (different instances)
 console.log(original.equals(copy));   // true (same values)
+``` ## Interface Support
+ Clone also works with interfaces. For interfaces, a namespace is generated with a `clone` function:
+ **Before:**
 ```
-
-## Interface Support
-
-Clone also works with interfaces. For interfaces, a namespace is generated with a `clone` function:
-
-<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
-
-```typescript
+/** @derive(Clone) */
+interface Point {
+    x: number;
+    y: number;
+}
+```  
+**After:**
+```
+interface Point {
+    x: number;
+    y: number;
+}
+
+export namespace Point {
+    export function clone(self: Point): Point {
+        return { x: self.x, y: self.y };
+    }
+}
+``` ```
 const original: Point = { x: 10, y: 20 };
 const copy = Point.clone(original);
 
 console.log(copy.x, copy.y);        // 10, 20
 console.log(original === copy);     // false (different objects)
+``` ## Enum Support
+ Clone also works with enums. For enums, the clone function simply returns the value as-is, since enum values are primitives and don't need cloning:
+ **Before:**
 ```
-
-## Enum Support
-
-Clone also works with enums. For enums, the clone function simply returns the value as-is, since enum values are primitives and don't need cloning:
-
-<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
-
-```typescript
+/** @derive(Clone) */
+enum Status {
+    Active = 'active',
+    Inactive = 'inactive'
+}
+```  
+**After:**
+```
+enum Status {
+    Active = 'active',
+    Inactive = 'inactive'
+}
+
+export namespace Status {
+    export function clone(value: Status): Status {
+        return value;
+    }
+}
+``` ```
 const original = Status.Active;
 const copy = Status.clone(original);
 
 console.log(copy);               // "active"
 console.log(original === copy);  // true (same primitive value)
+``` ## Type Alias Support
+ Clone works with type aliases. For object types, a shallow copy is created using spread:
+ **Before:**
 ```
-
-## Type Alias Support
-
-Clone works with type aliases. For object types, a shallow copy is created using spread:
-
-<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
-
-```typescript
+/** @derive(Clone) */
+type Point = {
+    x: number;
+    y: number;
+};
+```  
+**After:**
+```
+type Point = {
+    x: number;
+    y: number;
+};
+
+export namespace Point {
+    export function clone(value: Point): Point {
+        return { x: value.x, y: value.y };
+    }
+}
+``` ```
 const original: Point = { x: 10, y: 20 };
 const copy = Point.clone(original);
 
 console.log(copy.x, copy.y);     // 10, 20
 console.log(original === copy);  // false (different objects)
+``` For union types, the value is returned as-is (unions of primitives don't need cloning):
+ **Source:**
 ```
-
-For union types, the value is returned as-is (unions of primitives don't need cloning):
-
-<InteractiveMacro code={`/** @derive(Clone) */
-type ApiStatus = "loading" | "success" | "error";`} />
-
-```typescript
+/** @derive(Clone) */
+type ApiStatus = "loading" | "success" | "error";
+```  ```
 const status: ApiStatus = "success";
 const copy = ApiStatus.clone(status);
 console.log(copy); // "success"