@macroforge/mcp-server 0.1.40 → 0.1.42

package/docs/api/api-overview.md

@@ -1,53 +1,53 @@
 # API Reference
- <span class="stats svelte-1c8t0id">52 exported items *Macroforge provides a programmatic API for expanding macros in TypeScript code.*
+ <span class="stats svelte-1c8t0id">55 exported items *Macroforge provides a programmatic API for expanding macros in TypeScript code.*
  ## Overview
  ```
-import &#123;
-  expandSync,
-  transformSync,
-  checkSyntax,
-  parseImportSources,
-  NativePlugin,
-  PositionMapper
-&#125; from "macroforge";
+import&nbsp;&#123;
+&nbsp;&nbsp;expandSync,
+&nbsp;&nbsp;transformSync,
+&nbsp;&nbsp;checkSyntax,
+&nbsp;&nbsp;parseImportSources,
+&nbsp;&nbsp;NativePlugin,
+&nbsp;&nbsp;PositionMapper
+&#125;&nbsp;from&nbsp;"macroforge";
 ``` ## Core Functions
  | Function | Description |
 | --- | --- |
-| [`expandSync()`](../docs/api/expand-sync) | Expand macros synchronously |
-| [`transformSync()`](../docs/api/transform-sync) | Transform code with additional metadata |
-| `checkSyntax()` | Validate TypeScript syntax |
-| `parseImportSources()` | Extract import information |
+| [expandSync()](../docs/api/expand-sync) | Expand macros synchronously |
+| [transformSync()](../docs/api/transform-sync) | Transform code with additional metadata |
+| checkSyntax() | Validate TypeScript syntax |
+| parseImportSources() | Extract import information |
  ## Classes
  | Class | Description |
 | --- | --- |
-| [`NativePlugin`](../docs/api/native-plugin) | Stateful plugin with caching |
-| [`PositionMapper`](../docs/api/position-mapper) | Maps positions between original and expanded code |
+| [NativePlugin](../docs/api/native-plugin) | Stateful plugin with caching |
+| [PositionMapper](../docs/api/position-mapper) | Maps positions between original and expanded code |
  ## Quick Example
  ```
-import &#123; expandSync &#125; from "macroforge";
+import&nbsp;&#123;&nbsp;expandSync&nbsp;&#125;&nbsp;from&nbsp;"macroforge";
 
-const sourceCode = \`
-/** @derive(Debug) */
-class User &#123;
-  name: string;
-  constructor(name: string) &#123;
-    this.name = name;
-  &#125;
+const&nbsp;sourceCode&nbsp;=&nbsp;\`
+/**&nbsp;@derive(Debug)&nbsp;*/
+class&nbsp;User&nbsp;&#123;
+&nbsp;&nbsp;name:&nbsp;string;
+&nbsp;&nbsp;constructor(name:&nbsp;string)&nbsp;&#123;
+&nbsp;&nbsp;&nbsp;&nbsp;this.name&nbsp;=&nbsp;name;
+&nbsp;&nbsp;&#125;
 &#125;
 \`;
 
-const result = expandSync(sourceCode, "user.ts", &#123;
-  keepDecorators: false
+const&nbsp;result&nbsp;=&nbsp;expandSync(sourceCode,&nbsp;"user.ts",&nbsp;&#123;
+&nbsp;&nbsp;keepDecorators:&nbsp;false
 &#125;);
 
 console.log(result.code);
-// Output: class with toString() method generated
+//&nbsp;Output:&nbsp;class&nbsp;with&nbsp;toString()&nbsp;method&nbsp;generated
 
-if (result.diagnostics.length > 0) &#123;
-  console.error("Errors:", result.diagnostics);
+if&nbsp;(result.diagnostics.length&nbsp;>&nbsp;0)&nbsp;&#123;
+&nbsp;&nbsp;console.error("Errors:",&nbsp;result.diagnostics);
 &#125;
 ``` ## Detailed Reference
- - [`expandSync()`](../docs/api/expand-sync) - Full options and return types
- - [`transformSync()`](../docs/api/transform-sync) - Transform with source maps
- - [`NativePlugin`](../docs/api/native-plugin) - Caching for language servers
- - [`PositionMapper`](../docs/api/position-mapper) - Position mapping utilities
+ - [<code class="shiki-inline"><span class="line"><span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">expandSync<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">()</code>](../docs/api/expand-sync) - Full options and return types
+ - [<code class="shiki-inline"><span class="line"><span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">transformSync<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">()</code>](../docs/api/transform-sync) - Transform with source maps
+ - [<code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">NativePlugin</code>](../docs/api/native-plugin) - Caching for language servers
+ - [<code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">PositionMapper</code>](../docs/api/position-mapper) - Position mapping utilities

package/docs/api/expand-sync.md

@@ -2,50 +2,50 @@
   *Synchronously expands macros in TypeScript code. This is the standalone macro expansion function that doesn't use caching. For cached expansion, use [`NativePlugin::process_file`] instead.*
  ## Signature
  ```
-function expandSync(
-  code: string,
-  filepath: string,
-  options?: ExpandOptions
-): ExpandResult
+function expandSync(
+  code: string,
+  filepath: string,
+  options?: ExpandOptions
+): ExpandResult
 ``` ## Parameters
  | Parameter | Type | Description |
 | --- | --- | --- |
-| `code` | `string` | TypeScript source code to transform |
-| `filepath` | `string` | File path (used for error reporting) |
-| `options` | `ExpandOptions` | Optional configuration |
+| code | string | TypeScript source code to transform |
+| filepath | string | File path (used for error reporting) |
+| options | ExpandOptions | Optional configuration |
  ## ExpandOptions
  ```
-interface ExpandOptions {
-  // Keep @derive decorators in output (default: false)
-  keepDecorators?: boolean;
+interface ExpandOptions {
+  // Keep @derive decorators in output (default: false)
+  keepDecorators?: boolean;
 }
 ``` ## ExpandResult
  ```
-interface ExpandResult {
-  // Transformed TypeScript code
-  code: string;
+interface ExpandResult {
+  // Transformed TypeScript code
+  code: string;
 
-  // Generated type declarations (.d.ts content)
-  types?: string;
+  // Generated type declarations (.d.ts content)
+  types?: string;
 
-  // Macro expansion metadata (JSON string)
-  metadata?: string;
+  // Macro expansion metadata (JSON string)
+  metadata?: string;
 
-  // Warnings and errors from macro expansion
-  diagnostics: MacroDiagnostic[];
+  // Warnings and errors from macro expansion
+  diagnostics: MacroDiagnostic[];
 
-  // Position mapping data for source maps
-  sourceMapping?: SourceMappingResult;
+  // Position mapping data for source maps
+  sourceMapping?: SourceMappingResult;
 }
 ``` ## MacroDiagnostic
  ```
-interface MacroDiagnostic {
-  message: string;
-  severity: "error" | "warning" | "info";
-  span: {
-    start: number;
-    end: number;
-  };
+interface MacroDiagnostic {
+  message: string;
+  severity: "error" | "warning" | "info";
+  span: {
+    start: number;
+    end: number;
+  };
 }
 ``` ## Example
  ```
@@ -80,7 +80,7 @@ if (result.diagnostics.length > 0) {
   }
 }
 ``` ## Error Handling
- Syntax errors and macro errors are returned in the `diagnostics` array, not thrown as exceptions:
+ Syntax errors and macro errors are returned in the <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">diagnostics</code> array, not thrown as exceptions:
  ```
 const result = expandSync(invalidCode, "file.ts");
 

package/docs/api/native-plugin.md

@@ -2,73 +2,73 @@
   *The main plugin class for macro expansion with caching support. `NativePlugin` is designed to be instantiated once and reused across multiple file processing operations. It maintains a cache of expansion results keyed by filepath and version, enabling efficient incremental processing.*
  ## Constructor
  ```
-const plugin = new NativePlugin();
+const plugin = new NativePlugin();
 ``` ## Methods
  ### processFile()
  Process a file with version-based caching:
  ```
 processFile(
-  filepath: string,
-  code: string,
-  options?: ProcessFileOptions
-): ExpandResult
+  filepath: string,
+  code: string,
+  options?: ProcessFileOptions
+): ExpandResult
 ``` ```
-interface ProcessFileOptions {
-  // Cache key - if unchanged, returns cached result
-  version?: string;
+interface ProcessFileOptions {
+  // Cache key - if unchanged, returns cached result
+  version?: string;
 }
 ``` ### getMapper()
  Get the position mapper for a previously processed file:
  ```
-getMapper(filepath: string): NativeMapper | null
+getMapper(filepath: string): NativeMapper | null
 ``` ### mapDiagnostics()
  Map diagnostics from expanded positions to original positions:
  ```
 mapDiagnostics(
-  filepath: string,
-  diagnostics: JsDiagnostic[]
-): JsDiagnostic[]
+  filepath: string,
+  diagnostics: JsDiagnostic[]
+): JsDiagnostic[]
 ``` ### log() / setLogFile()
  Logging utilities for debugging:
  ```
-log(message: string): void
-setLogFile(path: string): void
+log(message: string): void
+setLogFile(path: string): void
 ``` ## Caching Behavior
  The plugin caches expansion results by file path and version:
  ```
-const plugin = new NativePlugin();
+const plugin = new NativePlugin();
 
-// First call - performs expansion
-const result1 = plugin.processFile("user.ts", code, { version: "1" });
+// 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" });
+// 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" });
+// Different version - re-expands
+const result3 = plugin.processFile("user.ts", newCode, { version: "2" });
 ``` ## Example: Language Server Integration
  ```
-import { NativePlugin } from "macroforge";
+import { NativePlugin } from "macroforge";
 
-class MacroforgeLanguageService {
-  private plugin = new NativePlugin();
+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)
-    });
+  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);
+    // Get mapper for position translation
+    const mapper = this.plugin.getMapper(uri);
 
-    return { result, mapper };
-  }
+    return { result, mapper };
+  }
 
-  getSemanticDiagnostics(uri: string, diagnostics: Diagnostic[]) {
-    // Map positions from expanded to original
-    return this.plugin.mapDiagnostics(uri, diagnostics);
-  }
+  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.
+ The <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">NativePlugin</code> 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,51 +2,51 @@
   *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 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...
+// 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:
  ```
-isEmpty(): boolean
+isEmpty(): boolean
 ``` ### originalToExpanded()
  Map a position from original to expanded code:
  ```
-originalToExpanded(pos: number): number
+originalToExpanded(pos: number): number
 ``` ### expandedToOriginal()
  Map a position from expanded to original code:
  ```
-expandedToOriginal(pos: number): number | null
-``` Returns `null` if the position is in generated code.
+expandedToOriginal(pos: number): number | null
+``` Returns <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#79B8FF;--shiki-light:#005CC5">null</code> if the position is in generated code.
  ### isInGenerated()
  Check if a position is in macro-generated code:
  ```
-isInGenerated(pos: number): boolean
+isInGenerated(pos:&nbsp;number):&nbsp;boolean
 ``` ### generatedBy()
  Get the name of the macro that generated code at a position:
  ```
-generatedBy(pos: number): string | null
+generatedBy(pos:&nbsp;number):&nbsp;string&nbsp;|&nbsp;null
 ``` ### mapSpanToOriginal()
  Map a span (range) from expanded to original code:
  ```
-mapSpanToOriginal(start: number, length: number): SpanResult | null
+mapSpanToOriginal(start:&nbsp;number,&nbsp;length:&nbsp;number):&nbsp;SpanResult&nbsp;|&nbsp;null
 
-interface SpanResult &#123;
-  start: number;
-  length: number;
+interface&nbsp;SpanResult&nbsp;&#123;
+&nbsp;&nbsp;start:&nbsp;number;
+&nbsp;&nbsp;length:&nbsp;number;
 &#125;
 ``` ### mapSpanToExpanded()
  Map a span from original to expanded code:
  ```
-mapSpanToExpanded(start: number, length: number): SpanResult
+mapSpanToExpanded(start:&nbsp;number,&nbsp;length:&nbsp;number):&nbsp;SpanResult
 ``` ## Example: Error Position Mapping
  ```
 import { NativePlugin } from "macroforge";

package/docs/api/transform-sync.md

@@ -2,32 +2,32 @@
   *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
+function transformSync(
+  code: string,
+  filepath: string
+): TransformResult
 ``` ## Parameters
  | Parameter | Type | Description |
 | --- | --- | --- |
-| `code` | `string` | TypeScript source code to transform |
-| `filepath` | `string` | File path (used for error reporting) |
+| code | string | TypeScript source code to transform |
+| filepath | string | File path (used for error reporting) |
  ## TransformResult
  ```
-interface TransformResult {
-  // Transformed TypeScript code
-  code: string;
+interface TransformResult {
+  // Transformed TypeScript code
+  code: string;
 
-  // Source map (JSON string, not yet implemented)
-  map?: string;
+  // Source map (JSON string, not yet implemented)
+  map?: string;
 
-  // Generated type declarations
-  types?: string;
+  // Generated type declarations
+  types?: string;
 
-  // Macro expansion metadata
-  metadata?: string;
+  // Macro expansion metadata
+  metadata?: string;
 }
 ``` ## Comparison with expandSync()
- | Feature | `expandSync` | `transformSync` |
+ | Feature | expandSync | transformSync |
 | --- | --- | --- |
 | Options | Yes | No |
 | Diagnostics | Yes | No |
@@ -35,32 +35,32 @@ interface TransformResult {
 | Use Case | General purpose | Build tools |
  ## Example
  ```
-import { transformSync } from "macroforge";
+import { transformSync } from "macroforge";
 
-const sourceCode = \`
-/** @derive(Debug) */
-class User {
-  name: string;
+const sourceCode = \`
+/** @derive(Debug) */
+class User {
+  name: string;
 }
 \`;
 
-const result = transformSync(sourceCode, "user.ts");
+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.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);
+if (result.metadata) {
+  // Parse and use metadata
+  const meta = JSON.parse(result.metadata);
+  console.log("Macros expanded:", meta);
 }
 ``` ## When to Use
- Use `transformSync` when:
+ Use <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">transformSync</code> 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.
+ Use <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">expandSync</code> for most other use cases, as it provides better error handling.