@macroforge/mcp-server 0.1.38 → 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/macros-overview.md

@@ -16,57 +16,57 @@
  Built-in macros don't require imports. Just use them with `@derive`:
  ```
 /** @derive(Debug, Clone, PartialEq) */
-class User {
+class User {
   name: string;
   age: number;
 
-  constructor(name: string, age: number) {
+  constructor(name: string, age: number) {
     this.name = name;
     this.age = age;
-  }
-}
+  }
+}
 ``` ## Interface Support
  All built-in macros work with interfaces. For interfaces, methods are generated as functions in a namespace with the same name, using `self` as the first parameter:
  ```
 /** @derive(Debug, Clone, PartialEq) */
-interface Point {
+interface Point {
   x: number;
   y: number;
-}
+}
 
 // Generated namespace:
-// namespace Point {
-//   export function toString(self: Point): string { ... }
-//   export function clone(self: Point): Point { ... }
-//   export function equals(self: Point, other: Point): boolean { ... }
-//   export function hashCode(self: Point): number { ... }
-// }
+// namespace Point {
+//   export function toString(self: Point): string { ... }
+//   export function clone(self: Point): Point { ... }
+//   export function equals(self: Point, other: Point): boolean { ... }
+//   export function hashCode(self: Point): number { ... }
+// }
 
-const point: Point = { x: 10, y: 20 };
+const point: Point = { x: 10, y: 20 };
 
 // Use the namespace functions
-console.log(Point.toString(point));     // "Point { x: 10, y: 20 }"
-const copy = Point.clone(point);        // { x: 10, y: 20 }
+console.log(Point.toString(point));     // "Point { x: 10, y: 20 }"
+const copy = Point.clone(point);        // { x: 10, y: 20 }
 console.log(Point.equals(point, copy)); // true
 ``` ## Enum Support
  All built-in macros work with enums. For enums, methods are generated as functions in a namespace with the same name:
  ```
 /** @derive(Debug, Clone, PartialEq, Serialize, Deserialize) */
-enum Status {
+enum Status {
   Active = "active",
   Inactive = "inactive",
   Pending = "pending",
-}
+}
 
 // Generated namespace:
-// namespace Status {
-//   export function toString(value: Status): string { ... }
-//   export function clone(value: Status): Status { ... }
-//   export function equals(a: Status, b: Status): boolean { ... }
-//   export function hashCode(value: Status): number { ... }
-//   export function toJSON(value: Status): string | number { ... }
-//   export function fromJSON(data: unknown): Status { ... }
-// }
+// namespace Status {
+//   export function toString(value: Status): string { ... }
+//   export function clone(value: Status): Status { ... }
+//   export function equals(a: Status, b: Status): boolean { ... }
+//   export function hashCode(value: Status): number { ... }
+//   export function toJSON(value: Status): string | number { ... }
+//   export function fromJSON(data: unknown): Status { ... }
+// }
 
 // Use the namespace functions
 console.log(Status.toString(Status.Active));     // "Status.Active"
@@ -77,24 +77,24 @@ const parsed = Status.fromJSON("active");        // Status.Active
  All built-in macros work with type aliases. For object type aliases, field-aware methods are generated in a namespace:
  ```
 /** @derive(Debug, Clone, PartialEq, Serialize, Deserialize) */
-type Point = {
+type Point = {
   x: number;
   y: number;
-};
+};
 
 // Generated namespace:
-// namespace Point {
-//   export function toString(value: Point): string { ... }
-//   export function clone(value: Point): Point { ... }
-//   export function equals(a: Point, b: Point): boolean { ... }
-//   export function hashCode(value: Point): number { ... }
-//   export function toJSON(value: Point): Record<string, unknown> { ... }
-//   export function fromJSON(data: unknown): Point { ... }
-// }
+// namespace Point &#123;
+//   export function toString(value: Point): string &#123; ... &#125;
+//   export function clone(value: Point): Point &#123; ... &#125;
+//   export function equals(a: Point, b: Point): boolean &#123; ... &#125;
+//   export function hashCode(value: Point): number &#123; ... &#125;
+//   export function toJSON(value: Point): Record&#x3C;string, unknown> &#123; ... &#125;
+//   export function fromJSON(data: unknown): Point &#123; ... &#125;
+// &#125;
 
-const point: Point = { x: 10, y: 20 };
-console.log(Point.toString(point));     // "Point { x: 10, y: 20 }"
-const copy = Point.clone(point);        // { x: 10, y: 20 }
+const point: Point = &#123; x: 10, y: 20 &#125;;
+console.log(Point.toString(point));     // "Point &#123; x: 10, y: 20 &#125;"
+const copy = Point.clone(point);        // &#123; x: 10, y: 20 &#125;
 console.log(Point.equals(point, copy)); // true
 ``` Union type aliases also work, using JSON-based implementations:
  ```
@@ -102,7 +102,7 @@ console.log(Point.equals(point, copy)); // true
 type ApiStatus = "loading" | "success" | "error";
 
 const status: ApiStatus = "success";
-console.log(ApiStatus.toString(status)); // "ApiStatus(\"success\")"
+console.log(ApiStatus.toString(status)); // "ApiStatus(\\"success\\")"
 console.log(ApiStatus.equals("success", "success")); // true
 ``` ## Combining Macros
  All macros can be used together. They don't conflict and each generates independent methods:
@@ -111,7 +111,7 @@ const user = new User("Alice", 30);
 
 // Debug
 console.log(user.toString());
-// "User { name: Alice, age: 30 }"
+// "User &#123; name: Alice, age: 30 &#125;"
 
 // Clone
 const copy = user.clone();

package/docs/concepts/architecture.md

@@ -37,8 +37,8 @@
  For custom macro development, `macroforge_ts` re-exports everything you need:
  ```
 // Convenient re-exports for macro development
-use macroforge_ts::macros::{ts_macro_derive, body, ts_template, above, below, signature};
-use macroforge_ts::ts_syn::{Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input};
+use macroforge_ts::macros::{ts_macro_derive, body, ts_template, above, below, signature};
+use macroforge_ts::ts_syn::{Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input};
 
 // Also available: raw crate access and SWC modules
 use macroforge_ts::swc_core;

package/docs/concepts/derive-system.md

@@ -25,21 +25,21 @@ class User {
 ```  ### The import macro Statement
  To use macros from external packages, you must declare them with `import macro`:
  ```
-/** import macro { MacroName } from "package-name"; */
+/** import macro { MacroName } from "package-name"; */
 ``` Syntax rules:
  - Must be inside a JSDoc comment (`/** */`)
  - Can appear anywhere in the file (typically at the top)
  - Multiple macros can be imported: `import macro { A, B } from "pkg";`
  - Multiple import statements can be used for different packages
  ```
-/** import macro { JSON, Validate } from "@my/macros"; */
-/** import macro { Builder } from "@other/macros"; */
+/** import macro { JSON, Validate } from "@my/macros"; */
+/** import macro { Builder } from "@other/macros"; */
 
 /** @derive(JSON, Validate, Builder) */
-class User {
+class User {
   name: string;
   email: string;
-}
+}
 ```  **Built-in macros Built-in macros (Debug, Clone, Default, Hash, Ord, PartialEq, PartialOrd, Serialize, Deserialize) do not require an import statement. ### Field Attributes
  Macros can define field-level attributes to customize behavior per field:
  ****Before:**

package/docs/custom-macros/custom-overview.md

@@ -8,52 +8,52 @@
  4. Building and publishing as an npm package
  ## Quick Example
  ```
-use macroforge_ts::macros::{ts_macro_derive, body};
-use macroforge_ts::ts_syn::{Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input};
+use macroforge_ts::macros::{ts_macro_derive, body};
+use macroforge_ts::ts_syn::{Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input};
 
 #[ts_macro_derive(
     JSON,
     description = "Generates toJSON() returning a plain object"
 )]
-pub fn derive_json(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
+pub fn derive_json(mut input: TsStream) -> Result&#x3C;TsStream, MacroforgeError> &#123;
     let input = parse_ts_macro_input!(input as DeriveInput);
 
-    match &input.data {
-        Data::Class(class) => {
-            Ok(body! {
-                toJSON(): Record<string, unknown> {
-                    return {
-                        {#for field in class.field_names()}
-                            @{field}: this.@{field},
-                        {/for}
-                    };
-                }
-            })
-        }
+    match &#x26;input.data &#123;
+        Data::Class(class) => &#123;
+            Ok(body! &#123;
+                toJSON(): Record&#x3C;string, unknown> &#123;
+                    return &#123;
+                        &#123;#for field in class.field_names()&#125;
+                            @&#123;field&#125;: this.@&#123;field&#125;,
+                        &#123;/for&#125;
+                    &#125;;
+                &#125;
+            &#125;)
+        &#125;
         _ => Err(MacroforgeError::new(
             input.decorator_span(),
             "@derive(JSON) only works on classes",
         )),
-    }
-}
+    &#125;
+&#125;
 ``` ## Using Custom Macros
  Once your macro package is published, users can import and use it:
  ```
-/** import macro { JSON } from "@my/macros"; */
+/** import macro &#123; JSON &#125; from "@my/macros"; */
 
 /** @derive(JSON) */
-class User {
+class User &#123;
   name: string;
   age: number;
 
-  constructor(name: string, age: number) {
+  constructor(name: string, age: number) &#123;
     this.name = name;
     this.age = age;
-  }
-}
+  &#125;
+&#125;
 
 const user = new User("Alice", 30);
-console.log(user.toJSON()); // { name: "Alice", age: 30 }
+console.log(user.toJSON()); // &#123; name: "Alice", age: 30 &#125;
 ``` > **Note:** The import macro comment tells Macroforge which package provides the macro. ## Getting Started
  Follow these guides to create your own macros:
  - [Set up a Rust macro crate](../docs/custom-macros/rust-setup)

package/docs/custom-macros/rust-setup.md

@@ -25,7 +25,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 macroforge_ts = "0.1"
-napi = { version = "3", features = ["napi8", "compat-mode"] }
+napi = { version = "3", features = ["napi8", "compat-mode"] }
 napi-derive = "3"
 
 [build-dependencies]
@@ -36,67 +36,67 @@ lto = true
 strip = true
 ``` ## Create build.rs
  ```
-fn main() {
+fn main() {
     napi_build::setup();
-}
+}
 ``` ## Create src/lib.rs
  ```
-use macroforge_ts::macros::{ts_macro_derive, body};
-use macroforge_ts::ts_syn::{
+use macroforge_ts::macros::{ts_macro_derive, body};
+use macroforge_ts::ts_syn::{
     Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input,
-};
+};
 
 #[ts_macro_derive(
     JSON,
     description = "Generates toJSON() returning a plain object"
 )]
-pub fn derive_json(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
+pub fn derive_json(mut input: TsStream) -> Result&#x3C;TsStream, MacroforgeError> &#123;
     let input = parse_ts_macro_input!(input as DeriveInput);
 
-    match &input.data {
-        Data::Class(class) => {
-            Ok(body! {
-                toJSON(): Record<string, unknown> {
-                    return {
-                        {#for field in class.field_names()}
-                            @{field}: this.@{field},
-                        {/for}
-                    };
-                }
-            })
-        }
+    match &#x26;input.data &#123;
+        Data::Class(class) => &#123;
+            Ok(body! &#123;
+                toJSON(): Record&#x3C;string, unknown> &#123;
+                    return &#123;
+                        &#123;#for field in class.field_names()&#125;
+                            @&#123;field&#125;: this.@&#123;field&#125;,
+                        &#123;/for&#125;
+                    &#125;;
+                &#125;
+            &#125;)
+        &#125;
         _ => Err(MacroforgeError::new(
             input.decorator_span(),
             "@derive(JSON) only works on classes",
         )),
-    }
-}
+    &#125;
+&#125;
 ``` ## Create package.json
  ```
-{
+&#123;
   "name": "@my-org/macros",
   "version": "0.1.0",
   "main": "index.js",
   "types": "index.d.ts",
-  "napi": {
+  "napi": &#123;
     "name": "my-macros",
-    "triples": {
+    "triples": &#123;
       "defaults": true
-    }
-  },
+    &#125;
+  &#125;,
   "files": [
     "index.js",
     "index.d.ts",
     "*.node"
   ],
-  "scripts": {
+  "scripts": &#123;
     "build": "napi build --release",
     "prepublishOnly": "napi build --release"
-  },
-  "devDependencies": {
+  &#125;,
+  "devDependencies": &#123;
     "@napi-rs/cli": "^3.0.0-alpha.0"
-  }
-}
+  &#125;
+&#125;
 ``` ## Build the Package
  ```
 # Build the native addon