@macroforge/mcp-server 0.1.17

package/docs/api/expand-sync.md

@@ -0,0 +1,121 @@
+# expandSync()
+
+*Expands macros in TypeScript code synchronously and returns the transformed output.*
+
+## Signature
+
+```typescript
+function expandSync(
+  code: string,
+  filepath: string,
+  options?: ExpandOptions
+): ExpandResult
+```
+
+## Parameters
+
+| `code` 
+| `string` 
+| TypeScript source code to transform 
+
+| `filepath` 
+| `string` 
+| File path (used for error reporting) 
+
+| `options` 
+| `ExpandOptions` 
+| Optional configuration
+
+## ExpandOptions
+
+```typescript
+interface ExpandOptions {
+  // Keep @derive decorators in output (default: false)
+  keepDecorators?: boolean;
+}
+```
+
+## ExpandResult
+
+```typescript
+interface ExpandResult {
+  // Transformed TypeScript code
+  code: string;
+
+  // Generated type declarations (.d.ts content)
+  types?: string;
+
+  // Macro expansion metadata (JSON string)
+  metadata?: string;
+
+  // Warnings and errors from macro expansion
+  diagnostics: MacroDiagnostic[];
+
+  // Position mapping data for source maps
+  sourceMapping?: SourceMappingResult;
+}
+```
+
+## MacroDiagnostic
+
+```typescript
+interface MacroDiagnostic {
+  message: string;
+  severity: "error" | "warning" | "info";
+  span: {
+    start: number;
+    end: number;
+  };
+}
+```
+
+## Example
+
+```typescript
+import { expandSync } from "macroforge";
+
+const sourceCode = \`
+import { Debug } from "macroforge";
+
+/** @derive(Debug) */
+class User {
+  name: string;
+  age: number;
+
+  constructor(name: string, age: number) {
+    this.name = name;
+    this.age = age;
+  }
+}
+\`;
+
+const result = expandSync(sourceCode, "user.ts");
+
+console.log("Transformed code:");
+console.log(result.code);
+
+if (result.types) {
+  console.log("Type declarations:");
+  console.log(result.types);
+}
+
+if (result.diagnostics.length > 0) {
+  for (const diag of result.diagnostics) {
+    console.log(\`[\${diag.severity}] \${diag.message}\`);
+  }
+}
+```
+
+## Error Handling
+
+Syntax errors and macro errors are returned in the `diagnostics` array, not thrown as exceptions:
+
+```typescript
+const result = expandSync(invalidCode, "file.ts");
+
+for (const diag of result.diagnostics) {
+  if (diag.severity === "error") {
+    console.error(\`Error at \${diag.span.start}: \${diag.message}\`);
+  }
+}
+```

package/docs/api/native-plugin.md

@@ -0,0 +1,106 @@
+# NativePlugin
+
+*A stateful plugin class with version-based caching, designed for integration with language servers and IDEs.*
+
+## Constructor
+
+```typescript
+const plugin = new NativePlugin();
+```
+
+## Methods
+
+### processFile()
+
+Process a file with version-based caching:
+
+```typescript
+processFile(
+  filepath: string,
+  code: string,
+  options?: ProcessFileOptions
+): ExpandResult
+```
+
+```typescript
+interface ProcessFileOptions {
+  // Cache key - if unchanged, returns cached result
+  version?: string;
+}
+```
+
+### getMapper()
+
+Get the position mapper for a previously processed file:
+
+```typescript
+getMapper(filepath: string): NativeMapper | null
+```
+
+### mapDiagnostics()
+
+Map diagnostics from expanded positions to original positions:
+
+```typescript
+mapDiagnostics(
+  filepath: string,
+  diagnostics: JsDiagnostic[]
+): JsDiagnostic[]
+```
+
+### log() / setLogFile()
+
+Logging utilities for debugging:
+
+```typescript
+log(message: string): void
+setLogFile(path: string): void
+```
+
+## Caching Behavior
+
+The plugin caches expansion results by file path and version:
+
+```typescript
+const plugin = new NativePlugin();
+
+// First call - performs expansion
+const result1 = plugin.processFile("user.ts", code, { version: "1" });
+
+// Same version - returns cached result instantly
+const result2 = plugin.processFile("user.ts", code, { version: "1" });
+
+// Different version - re-expands
+const result3 = plugin.processFile("user.ts", newCode, { version: "2" });
+```
+
+## Example: Language Server Integration
+
+```typescript
+import { NativePlugin } from "macroforge";
+
+class MacroforgeLanguageService {
+  private plugin = new NativePlugin();
+
+  processDocument(uri: string, content: string, version: number) {
+    // Process with version-based caching
+    const result = this.plugin.processFile(uri, content, {
+      version: String(version)
+    });
+
+    // Get mapper for position translation
+    const mapper = this.plugin.getMapper(uri);
+
+    return { result, mapper };
+  }
+
+  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

@@ -0,0 +1,127 @@
+# PositionMapper
+
+*Maps positions between original source code and macro-expanded code. Essential for accurate error reporting and debugging.*
+
+## Getting a Mapper
+
+```typescript
+import { NativePlugin, PositionMapper } from "macroforge";
+
+const plugin = new NativePlugin();
+const result = plugin.processFile("user.ts", code, { version: "1" });
+
+// Get the mapper for this file
+const mapper = plugin.getMapper("user.ts");
+if (mapper) {
+  // Use the mapper...
+}
+```
+
+## Methods
+
+### isEmpty()
+
+Check if the mapper has any mappings:
+
+```typescript
+isEmpty(): boolean
+```
+
+### originalToExpanded()
+
+Map a position from original to expanded code:
+
+```typescript
+originalToExpanded(pos: number): number
+```
+
+### expandedToOriginal()
+
+Map a position from expanded to original code:
+
+```typescript
+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
+isInGenerated(pos: number): boolean
+```
+
+### generatedBy()
+
+Get the name of the macro that generated code at a position:
+
+```typescript
+generatedBy(pos: number): string | null
+```
+
+### mapSpanToOriginal()
+
+Map a span (range) from expanded to original code:
+
+```typescript
+mapSpanToOriginal(start: number, length: number): SpanResult | null
+
+interface SpanResult {
+  start: number;
+  length: number;
+}
+```
+
+### mapSpanToExpanded()
+
+Map a span from original to expanded code:
+
+```typescript
+mapSpanToExpanded(start: number, length: number): SpanResult
+```
+
+## Example: Error Position Mapping
+
+```typescript
+import { NativePlugin } from "macroforge";
+
+const plugin = new NativePlugin();
+
+function mapError(filepath: string, expandedPos: number, message: string) {
+  const mapper = plugin.getMapper(filepath);
+  if (!mapper) return null;
+
+  // Check if the error is in generated code
+  if (mapper.isInGenerated(expandedPos)) {
+    const macroName = mapper.generatedBy(expandedPos);
+    return {
+      message: \`Error in code generated by @derive(\${macroName}): \${message}\`,
+      // Find the @derive decorator position
+      position: findDecoratorPosition(filepath)
+    };
+  }
+
+  // Map to original position
+  const originalPos = mapper.expandedToOriginal(expandedPos);
+  if (originalPos !== null) {
+    return {
+      message,
+      position: originalPos
+    };
+  }
+
+  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

package/docs/api/transform-sync.md

@@ -0,0 +1,98 @@
+# transformSync()
+
+*A lower-level transform function that returns additional metadata alongside the transformed code.*
+
+## Signature
+
+```typescript
+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
+interface TransformResult {
+  // Transformed TypeScript code
+  code: string;
+
+  // Source map (JSON string, not yet implemented)
+  map?: string;
+
+  // Generated type declarations
+  types?: string;
+
+  // 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
+import { transformSync } from "macroforge";
+
+const sourceCode = \`
+/** @derive(Debug) */
+class User {
+  name: string;
+}
+\`;
+
+const result = transformSync(sourceCode, "user.ts");
+
+console.log(result.code);
+
+if (result.types) {
+  // Write to .d.ts file
+  fs.writeFileSync("user.d.ts", result.types);
+}
+
+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
+
+- 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

@@ -0,0 +1,180 @@
+# Clone
+
+*The `Clone` macro generates a `clone()` method that creates a copy of the object.*
+
+## Basic Usage
+
+```typescript
+/** @derive(Clone) */
+class Point {
+  x: number;
+  y: number;
+
+  constructor(x: number, y: number) {
+    this.x = x;
+    this.y = y;
+  }
+}
+
+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)
+```
+
+## Generated Code
+
+```typescript
+clone(): Point {
+  return new Point(this.x, this.y);
+}
+```
+
+## 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
+
+```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;
+  }
+}
+
+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 Eq
+
+Clone works well with Eq for creating independent copies that compare as equal:
+
+```typescript
+/** @derive(Clone, Eq) */
+class Point {
+  x: number;
+  y: number;
+
+  constructor(x: number, y: number) {
+    this.x = x;
+    this.y = y;
+  }
+}
+
+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:
+
+```typescript
+/** @derive(Clone) */
+interface Point {
+  x: number;
+  y: number;
+}
+
+// Generated:
+// 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:
+
+```typescript
+/** @derive(Clone) */
+enum Status {
+  Active = "active",
+  Inactive = "inactive",
+}
+
+// Generated:
+// 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:
+
+```typescript
+/** @derive(Clone) */
+type Point = {
+  x: number;
+  y: number;
+};
+
+// Generated:
+// export namespace Point {
+//   export function clone(value: Point): Point {
+//     return { ...value };
+//   }
+// }
+
+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):
+
+```typescript
+/** @derive(Clone) */
+type ApiStatus = "loading" | "success" | "error";
+
+const status: ApiStatus = "success";
+const copy = ApiStatus.clone(status);
+console.log(copy); // "success"
+```