@macroforge/mcp-server 0.1.33 → 0.1.35

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,121 +1,62 @@
 # Clone
 
-*The `Clone` macro generates a `clone()` method that creates a copy of the object.*
+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
+## Generated Output
 
-<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
+| 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 |
 
-```typescript
-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:
+## Configuration
 
-1. Creates a new instance of the class
+The `functionNamingStyle` option in `macroforge.json` controls naming:
+- `"suffix"` (default): Suffixes with type name (e.g., `cloneMyType`)
+- `"prefix"`: Prefixes with type name (e.g., `myTypeClone`)
+- `"generic"`: Uses TypeScript generics (e.g., `clone<T extends MyType>`)
+- `"namespace"`: Legacy namespace wrapping
 
-2. Passes all field values to the constructor
+## Cloning Strategy
 
-3. Returns the new instance
+The generated clone performs a **shallow copy** of all fields:
 
-This creates a **shallow clone** - primitive values are copied, but object references remain the same.
+- **Primitives** (`string`, `number`, `boolean`): Copied by value
+- **Objects**: Reference is copied (not deep cloned)
+- **Arrays**: Reference is copied (not deep cloned)
 
-## With Nested Objects
+For deep cloning of nested objects, those objects should also derive `Clone`
+and the caller should clone them explicitly.
 
-<MacroExample before={data.examples.nested.before} after={data.examples.nested.after} />
+## Example
 
 ```typescript
-const original = new User("Alice", { city: "NYC", zip: "10001" });
-const copy = original.clone();
-
-// The address object is the same reference
-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:
-
-<InteractiveMacro code={`/** @derive(Clone, PartialEq) */
+@derive(Clone)
 class Point {
-  x: number;
-  y: number;
-
-  constructor(x: number, y: number) {
-    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)
+    x: number;
+    y: number;
+}
+
+// Generated:
+// clone(): Point {
+//     const cloned = Object.create(Object.getPrototypeOf(this));
+//     cloned.x = this.x;
+//     cloned.y = this.y;
+//     return cloned;
+// }
+
+const p1 = new Point();
+const p2 = p1.clone(); // Creates a new Point with same values
 ```
 
-## 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
-const original: Point = { x: 10, y: 20 };
-const copy = Point.clone(original);
+## Implementation Notes
 
-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:
-
-<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
-
-```typescript
-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:
-
-<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
-
-```typescript
-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):
-
-<InteractiveMacro code={`/** @derive(Clone) */
-type ApiStatus = "loading" | "success" | "error";`} />
-
-```typescript
-const status: ApiStatus = "success";
-const copy = ApiStatus.clone(status);
-console.log(copy); // "success"
-```
+- **Classes**: Uses `Object.create(Object.getPrototypeOf(this))` 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
+  for union/tuple types, or field-by-field copy for object types

package/docs/builtin-macros/debug.md

@@ -1,123 +1,52 @@
 # Debug
 
-*The `Debug` macro generates a `toString()` method that produces a human-readable string representation of your class.*
+The `Debug` macro generates a human-readable `toString()` method for
+TypeScript classes, interfaces, enums, and type aliases.
 
-## Basic Usage
+## Generated Output
 
-<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
+**Classes**: Generates an instance method returning a string
+like `"ClassName { field1: value1, field2: value2 }"`.
 
-```typescript
-const user = new User("Alice", 30);
-console.log(user.toString());
-// Output: User { name: Alice, age: 30 }
-```
-
-## Field Options
-
-Use the `@debug` field decorator to customize behavior:
-
-### Renaming Fields
-
-<MacroExample before={data.examples.rename.before} after={data.examples.rename.after} />
-
-```typescript
-const user = new User(42, "Alice");
-console.log(user.toString());
-// Output: User { userId: 42, name: Alice }
-```
-
-### Skipping Fields
-
-Use `skip: true` to exclude sensitive fields from the output:
-
-<MacroExample before={data.examples.skip.before} after={data.examples.skip.after} />
-
-```typescript
-const user = new User("Alice", "alice@example.com", "secret", "tok_xxx");
-console.log(user.toString());
-// Output: User { name: Alice, email: alice@example.com }
-// Note: password and authToken are not included
-```
-
-<Alert type="tip" title="Security">
-Always skip sensitive fields like passwords, tokens, and API keys to prevent accidental logging.
-</Alert>
-
-## Combining Options
+**Enums**: Generates a standalone function `toStringEnumName(value)` that performs
+reverse lookup on numeric enums.
 
-<InteractiveMacro code={`/** @derive(Debug) */
-class ApiResponse {
-  /** @debug({ rename: "statusCode" }) */
-  status: number;
+**Interfaces**: Generates a standalone function `toStringInterfaceName(value)`.
 
-  data: unknown;
+**Type Aliases**: Generates a standalone function using JSON.stringify for
+complex types, or field enumeration for object types.
 
-  /** @debug({ skip: true }) */
-  internalMetadata: Record<string, unknown>;
-}`} />
+## Configuration
 
-## All Options
+The `functionNamingStyle` option in `macroforge.json` controls naming:
+- `"suffix"` (default): Suffixes with type name (e.g., `toStringMyType`)
+- `"prefix"`: Prefixes with type name (e.g., `myTypeToString`)
+- `"generic"`: Uses TypeScript generics (e.g., `toString<T extends MyType>`)
+- `"namespace"`: Legacy namespace wrapping
 
-| `rename` 
-| `string` 
-| Display a different name in the output 
+## Field-Level Options
 
-| `skip` 
-| `boolean` 
-| Exclude this field from the output
+The `@debug` decorator supports:
 
-## Interface Support
+- `skip` - Exclude the field from debug output
+- `rename = "label"` - Use a custom label instead of the field name
 
-Debug also works with interfaces. For interfaces, a namespace is generated with a `toString` function:
-
-<MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
+## Example
 
 ```typescript
-const status: Status = { active: true, message: "OK" };
-console.log(Status.toString(status));
-// Output: Status { active: true, message: OK }
-```
-
-## Enum Support
+@derive(Debug)
+class User {
+    @debug(rename = "id")
+    userId: number;
 
-Debug also works with enums. For enums, a namespace is generated with a `toString` function that displays the enum name and variant:
+    @debug(skip)
+    password: string;
 
-<MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
-
-```typescript
-console.log(Priority.toString(Priority.High));
-// Output: Priority.High
+    email: string;
+}
 
-console.log(Priority.toString(Priority.Low));
-// Output: Priority.Low
+// Generated:
+// toString(): string {
+//     return "User { id: " + this.userId + ", email: " + this.email + " }";
+// }
 ```
-
-Works with both numeric and string enums:
-
-<InteractiveMacro code={`/** @derive(Debug) */
-enum Status {
-  Active = "active",
-  Inactive = "inactive",
-}`} />
-
-## Type Alias Support
-
-Debug works with type aliases. For object types, fields are displayed similar to interfaces:
-
-<MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
-
-```typescript
-const point: Point = { x: 10, y: 20 };
-console.log(Point.toString(point));
-// Output: Point { x: 10, y: 20 }
-```
-
-For union types, the value is displayed using JSON.stringify:
-
-<InteractiveMacro code={`/** @derive(Debug) */
-type ApiStatus = "loading" | "success" | "error";`} />
-
-```typescript
-console.log(ApiStatus.toString("success"));
-// Output: ApiStatus("success")
-```