@macroforge/mcp-server 0.1.40 → 0.1.49

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 rymskip
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/docs/BOOK.md

@@ -0,0 +1,165 @@
+# Macroforge Documentation
+
+*TypeScript Macros - Rust-Powered Code Generation*
+
+---
+
+## Table of Contents
+
+### Getting Started
+- [Installation](#installation)
+- [First Macro](#first-macro)
+
+### Core Concepts
+- [How Macros Work](#how-macros-work)
+- [The Derive System](#the-derive-system)
+- [Architecture](#architecture)
+
+### Built-in Macros
+- [Overview](#overview)
+- [Debug](#debug)
+- [Clone](#clone)
+- [Default](#default)
+- [Hash](#hash)
+- [Ord](#ord)
+- [PartialEq](#partialeq)
+- [PartialOrd](#partialord)
+- [Serialize](#serialize)
+- [Deserialize](#deserialize)
+
+### Custom Macros
+- [Overview](#overview)
+- [Rust Setup](#rust-setup)
+- [ts_macro_derive](#ts-macro-derive)
+- [Template Syntax](#template-syntax)
+
+### Integration
+- [Overview](#overview)
+- [CLI](#cli)
+- [TypeScript Plugin](#typescript-plugin)
+- [Vite Plugin](#vite-plugin)
+- [Configuration](#configuration)
+
+### Language Servers
+- [Overview](#overview)
+- [Svelte](#svelte)
+- [Zed Extensions](#zed-extensions)
+
+### API Reference
+- [Overview](#overview)
+- [expandSync()](#expandsync)
+- [transformSync()](#transformsync)
+- [NativePlugin](#nativeplugin)
+- [PositionMapper](#positionmapper)
+
+---
+
+# Getting Started
+
+
+---
+
+
+---
+
+# Core Concepts
+
+
+---
+
+
+---
+
+
+---
+
+# Built-in Macros
+
+
+---
+
+
+---
+
+
+---
+
+
+---
+
+
+---
+
+
+---
+
+
+---
+
+
+---
+
+
+---
+
+
+---
+
+# Custom Macros
+
+
+---
+
+
+---
+
+
+---
+
+
+---
+
+# Integration
+
+
+---
+
+
+---
+
+
+---
+
+
+---
+
+
+---
+
+# Language Servers
+
+
+---
+
+
+---
+
+
+---
+
+# API Reference
+
+
+---
+
+
+---
+
+
+---
+
+
+---
+
+
+---

package/docs/api/api-overview.md

@@ -1,53 +1,72 @@
 # API Reference
- <span class="stats svelte-1c8t0id">52 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";
-``` ## Core Functions
- | Function | Description |
-| --- | --- |
-| [`expandSync()`](../docs/api/expand-sync) | Expand macros synchronously |
+
+macroforge v0.1.43 33 exported items
+
+Macroforge provides a programmatic API for expanding macros in TypeScript code.
+
+## Overview
+
+TypeScript
+
+```
+import {
+  expandSync,
+  transformSync,
+  checkSyntax,
+  parseImportSources,
+  NativePlugin,
+  PositionMapper
+} from "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 |
- ## Classes
- | Class | Description |
-| --- | --- |
-| [`NativePlugin`](../docs/api/native-plugin) | Stateful plugin with caching |
+| `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 |
- ## Quick Example
- ```
-import &#123; expandSync &#125; from "macroforge";
-
-const sourceCode = \`
-/** @derive(Debug) */
-class User &#123;
-  name: string;
-  constructor(name: string) &#123;
-    this.name = name;
-  &#125;
-&#125;
+
+## Quick Example
+
+TypeScript
+
+```
+import { expandSync } from "macroforge";
+
+const sourceCode = \`
+/** @derive(Debug) */
+class User {
+  name: string;
+  constructor(name: string) {
+    this.name = name;
+  }
+}
 \`;
 
-const result = expandSync(sourceCode, "user.ts", &#123;
-  keepDecorators: false
-&#125;);
+const result = expandSync(sourceCode, "user.ts", {
+  keepDecorators: false
+});
 
 console.log(result.code);
-// Output: class with toString() method generated
-
-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
- - [`NativePlugin`](../docs/api/native-plugin) - Caching for language servers
- - [`PositionMapper`](../docs/api/position-mapper) - Position mapping utilities
+// Output: class with toString() method generated
+
+if (result.diagnostics.length > 0) {
+  console.error("Errors:", result.diagnostics);
+}
+```
+
+## 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

package/docs/api/expand-sync.md

@@ -1,54 +1,83 @@
 # expandSync()
-  *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
-``` ## Parameters
- | Parameter | Type | Description |
-| --- | --- | --- |
-| `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;
-}
-``` ## ExpandResult
- ```
-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
- ```
-interface MacroDiagnostic {
-  message: string;
-  severity: "error" | "warning" | "info";
-  span: {
-    start: number;
-    end: number;
-  };
-}
-``` ## Example
- ```
+
+macroforge v0.1.43
+
+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
+
+TypeScript
+
+```
+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               |
+
+## 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 = `
@@ -79,9 +108,15 @@ if (result.diagnostics.length > 0) {
     console.log(`[${diag.severity}] ${diag.message}`);
   }
 }
-``` ## Error Handling
- Syntax errors and macro errors are returned in the `diagnostics` array, not thrown as exceptions:
- ```
+```
+
+## 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) {

package/docs/api/native-plugin.md

@@ -1,74 +1,124 @@
 # NativePlugin
-  *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();
-``` ## Methods
- ### processFile()
- Process a file with version-based caching:
- ```
+
+macroforge v0.1.43
+
+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
+
+TypeScript
+
+```
+const plugin = new NativePlugin();
+```
+
+## Methods
+
+### processFile()
+
+Process a file with version-based caching:
+
+TypeScript
+
+```
 processFile(
-  filepath: string,
-  code: string,
-  options?: ProcessFileOptions
-): ExpandResult
-``` ```
-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
-``` ### mapDiagnostics()
- Map diagnostics from expanded positions to original positions:
- ```
+  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:
- ```
-log(message: string): void
-setLogFile(path: string): void
-``` ## Caching Behavior
- The plugin caches expansion results by file path and version:
- ```
-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
- ```
-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.
+  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.