@macroforge/mcp-server 0.1.33 → 0.1.35

package/docs/getting-started/first-macro.md

@@ -1,16 +1,64 @@
 # Your First Macro
-
-*Let's create a class that uses Macroforge's derive macros to automatically generate useful methods.*
-
-## Creating a Class with Derive Macros
-
-Start by creating a simple `User` class. We'll use the `@derive` decorator to automatically generate methods.
-
-<MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
-
-## Using the Generated Methods
-
-```typescript
+ *Let's create a class that uses Macroforge's derive macros to automatically generate useful methods.*
+ ## Creating a Class with Derive Macros
+ Start by creating a simple `User` class. We'll use the `@derive` decorator to automatically generate methods.
+ **Before:**
+```
+/** @derive(Debug, Clone, PartialEq) */
+export class User {
+    name: string;
+    age: number;
+    email: string;
+
+    constructor(name: string, age: number, email: string) {
+        this.name = name;
+        this.age = age;
+        this.email = email;
+    }
+}
+```  
+**After:**
+```
+export class User {
+    name: string;
+    age: number;
+    email: string;
+
+    constructor(name: string, age: number, email: string) {
+        this.name = name;
+        this.age = age;
+        this.email = email;
+    }
+
+    toString(): string {
+        const parts: string[] = [];
+        parts.push('name: ' + this.name);
+        parts.push('age: ' + this.age);
+        parts.push('email: ' + this.email);
+        return 'User { ' + parts.join(', ') + ' }';
+    }
+
+    clone(): User {
+        const cloned = Object.create(Object.getPrototypeOf(this));
+        cloned.name = this.name;
+        cloned.age = this.age;
+        cloned.email = this.email;
+        return cloned;
+    }
+
+    equals(other: unknown): boolean {
+        if (this === other) return true;
+        if (!(other instanceof User)) return false;
+        const typedOther = other as User;
+        return (
+            this.name === typedOther.name &&
+            this.age === typedOther.age &&
+            this.email === typedOther.email
+        );
+    }
+}
+``` ## Using the Generated Methods
+ ```
 const user = new User("Alice", 30, "alice@example.com");
 
 // Debug: toString()
@@ -26,29 +74,56 @@ console.log(user.equals(copy)); // true
 
 const different = new User("Bob", 25, "bob@example.com");
 console.log(user.equals(different)); // false
+``` ## Customizing Behavior
+ You can customize how macros work using field-level decorators. For example, with the Debug macro:
+ **Before:**
 ```
-
-## Customizing Behavior
-
-You can customize how macros work using field-level decorators. For example, with the Debug macro:
-
-<MacroExample before={data.examples.customizing.before} after={data.examples.customizing.after} />
-
-```typescript
+/** @derive(Debug) */
+export class User {
+    /** @debug({ rename: "userId" }) */
+    id: number;
+
+    name: string;
+
+    /** @debug({ skip: true }) */
+    password: string;
+
+    constructor(id: number, name: string, password: string) {
+        this.id = id;
+        this.name = name;
+        this.password = password;
+    }
+}
+```  
+**After:**
+```
+export class User {
+    id: number;
+
+    name: string;
+
+    password: string;
+
+    constructor(id: number, name: string, password: string) {
+        this.id = id;
+        this.name = name;
+        this.password = password;
+    }
+
+    toString(): string {
+        const parts: string[] = [];
+        parts.push('userId: ' + this.id);
+        parts.push('name: ' + this.name);
+        return 'User { ' + parts.join(', ') + ' }';
+    }
+}
+``` ```
 const user = new User(42, "Alice", "secret123");
 console.log(user.toString());
 // Output: User { userId: 42, name: Alice }
 // Note: 'id' is renamed to 'userId', 'password' is skipped
-```
-
-<Alert type="tip" title="Field-level decorators">
-Field-level decorators let you control exactly how each field is handled by the macro.
-</Alert>
-
-## Next Steps
-
-- [Learn how macros work under the hood]({base}/docs/concepts)
-
-- [Explore all Debug options]({base}/docs/builtin-macros/debug)
-
-- [Create your own custom macros]({base}/docs/custom-macros)
+```  **Field-level decorators Field-level decorators let you control exactly how each field is handled by the macro. ## Next Steps
+ - [Learn how macros work under the hood](../../docs/concepts)
+ - [Explore all Debug options](../../docs/builtin-macros/debug)
+ - [Create your own custom macros](../../docs/custom-macros)
+**

package/docs/getting-started/installation.md

@@ -1,42 +1,20 @@
 # Installation
-
-*Get started with Macroforge in just a few minutes. Install the package and configure your project to start using TypeScript macros.*
-
-## Requirements
-
-- Node.js 24.0 or later
-
-- TypeScript 5.9 or later
-
-## Install the Package
-
-Install Macroforge using your preferred package manager:
-
-`npm`
-```bash
+ *Get started with Macroforge in just a few minutes. Install the package and configure your project to start using TypeScript macros.*
+ ## Requirements
+ - Node.js 24.0 or later
+ - TypeScript 5.9 or later
+ ## Install the Package
+ Install Macroforge using your preferred package manager:
+ ```
 npm install macroforge
-```
-
-`bun`
-```bash
+``` ```
 bun add macroforge
-```
-
-`pnpm`
-```bash
+``` ```
 pnpm add macroforge
-```
-
-> **Note:**
-> Macroforge includes pre-built native binaries for macOS (x64, arm64), Linux (x64, arm64), and Windows (x64, arm64).
-
-## Basic Usage
-
-The simplest way to use Macroforge is with the built-in derive macros. Add a `@derive` comment decorator to your class:
-
-`user.ts`
-```typescript
-/** @derive(Debug, Clone, Eq) */
+```  **Info Macroforge includes pre-built native binaries for macOS (x64, arm64), Linux (x64, arm64), and Windows (x64, arm64). ## Basic Usage
+ The simplest way to use Macroforge is with the built-in derive macros. Add a `@derive` comment decorator to your class:
+ ```
+/** @derive(Debug, Clone, PartialEq) */
 class User {
   name: string;
   age: number;
@@ -48,17 +26,12 @@ class User {
 }
 
 // After macro expansion, User has:
-// - toString(): string         (from Debug)
-// - clone(): User              (from Clone)
-// - equals(other: User): boolean  (from Eq)
-```
-
-## IDE Integration
-
-For the best development experience, add the TypeScript plugin to your `tsconfig.json`:
-
-`tsconfig.json`
-```json
+// - toString(): string              (from Debug)
+// - clone(): User                   (from Clone)
+// - equals(other: unknown): boolean (from PartialEq)
+``` ## IDE Integration
+ For the best development experience, add the TypeScript plugin to your `tsconfig.json`:
+ ```
 {
   "compilerOptions": {
     "plugins": [
@@ -68,22 +41,13 @@ For the best development experience, add the TypeScript plugin to your `tsconfig
     ]
   }
 }
-```
-
-This enables features like:
-
-- Accurate error positions in your source code
-
-- Autocompletion for generated methods
-
-- Type checking for expanded code
-
-## Build Integration (Vite)
-
-If you're using Vite, add the plugin to your config for automatic macro expansion during build:
-
-`vite.config.ts`
-```typescript
+``` This enables features like:
+ - Accurate error positions in your source code
+ - Autocompletion for generated methods
+ - Type checking for expanded code
+ ## Build Integration (Vite)
+ If you're using Vite, add the plugin to your config for automatic macro expansion during build:
+ ```
 import macroforge from "@macroforge/vite-plugin";
 import { defineConfig } from "vite";
 
@@ -95,14 +59,9 @@ export default defineConfig({
     })
   ]
 });
-```
-
-## Next Steps
-
-Now that you have Macroforge installed, learn how to use it:
-
-- [Create your first macro]({base}/docs/getting-started/first-macro)
-
-- [Understand how macros work]({base}/docs/concepts)
-
-- [Explore built-in macros]({base}/docs/builtin-macros)
+``` ## Next Steps
+ Now that you have Macroforge installed, learn how to use it:
+ - [Create your first macro](../docs/getting-started/first-macro)
+ - [Understand how macros work](../docs/concepts)
+ - [Explore built-in macros](../docs/builtin-macros)
+**

package/docs/integration/cli.md

@@ -1,117 +1,64 @@
 # Command Line Interface
-
-*The `macroforge` CLI provides commands for expanding macros and running type checks with macro support.*
-
-## Installation
-
-The CLI is a Rust binary. You can install it using Cargo:
-
-```bash
+  *This binary provides command-line utilities for working with Macroforge TypeScript macros. It is designed for development workflows, enabling macro expansion and type checking without requiring Node.js integration.*
+ ## Installation
+ The CLI is a Rust binary. You can install it using Cargo:
+ ```
 cargo install macroforge_ts
-```
-
-Or build from source:
-
-```bash
+``` Or build from source:
+ ```
 git clone https://github.com/rymskip/macroforge-ts.git
 cd macroforge-ts/crates
 cargo build --release --bin macroforge
 
 # The binary is at target/release/macroforge
-```
-
-## Commands
-
-### macroforge expand
-
-Expands macros in a TypeScript file and outputs the transformed code.
-
-```bash
+``` ## Commands
+ ### macroforge expand
+ Expands macros in a TypeScript file and outputs the transformed code.
+ ```
 macroforge expand <input> [options]
-```
-
-#### Arguments
-
-| `<input>` 
-| Path to the TypeScript or TSX file to expand
-
-#### Options
-
-| `--out <path>` 
-| Write the expanded JavaScript/TypeScript to a file 
-
-| `--types-out <path>` 
-| Write the generated `.d.ts` declarations to a file 
-
-| `--print` 
-| Print output to stdout even when `--out` is specified 
-
-| `--builtin-only` 
-| Use only built-in Rust macros (faster, but no external macro support)
-
-#### Examples
-
-Expand a file and print to stdout:
-
-```bash
+``` #### Arguments
+ | Argument | Description |
+| --- | --- |
+| `<input>` | Path to the TypeScript or TSX file to expand |
+ #### Options
+ | Option | Description |
+| --- | --- |
+| `--out <path>` | Write the expanded JavaScript/TypeScript to a file |
+| `--types-out <path>` | Write the generated `.d.ts` declarations to a file |
+| `--print` | Print output to stdout even when `--out` is specified |
+| `--builtin-only` | Use only built-in Rust macros (faster, but no external macro support) |
+ #### Examples
+ Expand a file and print to stdout:
+ ```
 macroforge expand src/user.ts
-```
-
-Expand and write to a file:
-
-```bash
+``` Expand and write to a file:
+ ```
 macroforge expand src/user.ts --out dist/user.js
-```
-
-Expand with both runtime output and type declarations:
-
-```bash
+``` Expand with both runtime output and type declarations:
+ ```
 macroforge expand src/user.ts --out dist/user.js --types-out dist/user.d.ts
-```
-
-Use fast built-in macros only (no external macro support):
-
-```bash
+``` Use fast built-in macros only (no external macro support):
+ ```
 macroforge expand src/user.ts --builtin-only
-```
-
->
-> By default, the CLI uses Node.js for full macro support (including external macros). It must be run from your project's root directory where `macroforge` and any external macro packages are installed in `node_modules`.
-
-### macroforge tsc
-
-Runs TypeScript type checking with macro expansion. This wraps `tsc --noEmit` and expands macros before type checking, so your generated methods are properly type-checked.
-
-```bash
+``` > **Note:** By default, the CLI uses Node.js for full macro support (including external macros). It must be run from your project's root directory where macroforge and any external macro packages are installed in node_modules. ### macroforge tsc
+ Runs TypeScript type checking with macro expansion. This wraps `tsc --noEmit` and expands macros before type checking, so your generated methods are properly type-checked.
+ ```
 macroforge tsc [options]
-```
-
-#### Options
-
-| `-p, --project <path>` 
-| Path to `tsconfig.json` (defaults to `tsconfig.json` in current directory)
-
-#### Examples
-
-Type check with default tsconfig.json:
-
-```bash
+``` #### Options
+ | Option | Description |
+| --- | --- |
+| `-p, --project <path>` | Path to `tsconfig.json` (defaults to `tsconfig.json` in current directory) |
+ #### Examples
+ Type check with default tsconfig.json:
+ ```
 macroforge tsc
-```
-
-Type check with a specific config:
-
-```bash
+``` Type check with a specific config:
+ ```
 macroforge tsc -p tsconfig.build.json
-```
-
-## Output Format
-
-### Expanded Code
-
-When expanding a file like this:
-
-```typescript
+``` ## Output Format
+ ### Expanded Code
+ When expanding a file like this:
+ ```
 /** @derive(Debug) */
 class User {
   name: string;
@@ -122,11 +69,8 @@ class User {
     this.age = age;
   }
 }
-```
-
-The CLI outputs the expanded code with the generated methods:
-
-```typescript
+``` The CLI outputs the expanded code with the generated methods:
+ ```
 class User {
   name: string;
   age: number;
@@ -137,71 +81,41 @@ class User {
   }
 
   [Symbol.for("nodejs.util.inspect.custom")](): string {
-    return \`User { name: \${this.name}, age: \${this.age} }\`;
+    return `User { name: ${this.name}, age: ${this.age} }`;
   }
 }
-```
-
-### Diagnostics
-
-Errors and warnings are printed to stderr in a readable format:
-
-```text
+``` ### Diagnostics
+ Errors and warnings are printed to stderr in a readable format:
+ ```
 [macroforge] error at src/user.ts:5:1: Unknown derive macro: InvalidMacro
 [macroforge] warning at src/user.ts:10:3: Field 'unused' is never used
-```
-
-## Use Cases
-
-### CI/CD Type Checking
-
-Use `macroforge tsc` in your CI pipeline to type-check with macro expansion:
-
-```json
+``` ## Use Cases
+ ### CI/CD Type Checking
+ Use `macroforge tsc` in your CI pipeline to type-check with macro expansion:
+ ```
 # package.json
 {
   "scripts": {
     "typecheck": "macroforge tsc"
   }
 }
-```
-
-### Debugging Macro Output
-
-Use `macroforge expand` to inspect what code your macros generate:
-
-```bash
+``` ### Debugging Macro Output
+ Use `macroforge expand` to inspect what code your macros generate:
+ ```
 macroforge expand src/models/user.ts | less
-```
-
-### Build Pipeline
-
-Generate expanded files as part of a custom build:
-
-```bash
+``` ### Build Pipeline
+ Generate expanded files as part of a custom build:
+ ```
 #!/bin/bash
 for file in src/**/*.ts; do
   outfile="dist/$(basename "$file" .ts).js"
   macroforge expand "$file" --out "$outfile"
 done
-```
-
-## Built-in vs Full Mode
-
-By default, the CLI uses Node.js for full macro support including external macros. Use `--builtin-only` for faster expansion when you only need built-in macros:
-
-| Built-in macros 
-| Yes 
-| Yes 
-
-| External macros 
-| Yes 
-| No 
-
-| Performance 
-| Standard 
-| Faster 
-
-| Dependencies 
-| Requires `macroforge` in node_modules 
-| None
+``` ## Built-in vs Full Mode
+ By default, the CLI uses Node.js for full macro support including external macros. Use `--builtin-only` for faster expansion when you only need built-in macros:
+ | Feature | Default (Node.js) | `--builtin-only` (Rust) |
+| --- | --- | --- |
+| Built-in macros | Yes | Yes |
+| External macros | Yes | No |
+| Performance | Standard | Faster |
+| Dependencies | Requires `macroforge` in node_modules | None |

package/docs/integration/configuration.md

@@ -1,13 +1,8 @@
 # Configuration
-
-*Macroforge can be configured with a `macroforge.json` file in your project root.*
-
-## Configuration File
-
-Create a `macroforge.json` file:
-
-`macroforge.json`
-```json
+ *Macroforge can be configured with a `macroforge.json` file in your project root.*
+ ## Configuration File
+ Create a `macroforge.json` file:
+ ```
 {
   "allowNativeMacros": true,
   "macroPackages": [],
@@ -19,54 +14,29 @@ Create a `macroforge.json` file:
     "maxDiagnostics": 100
   }
 }
-```
-
-## Options Reference
-
-### allowNativeMacros
-
-| Type 
-| `boolean` 
-
-| Default 
-| `true`
-
-Enable or disable native (Rust) macro packages. Set to `false` to only allow built-in macros.
-
-### macroPackages
-
-| Type 
-| `string[]` 
-
-| Default 
-| `[]`
-
-List of npm packages that provide macros. Macroforge will look for macros in these packages.
-
-```json
+``` ## Options Reference
+ ### allowNativeMacros
+ | Type | `boolean` |
+| Default | `true` |
+ Enable or disable native (Rust) macro packages. Set to `false` to only allow built-in macros.
+ ### macroPackages
+ | Type | `string[]` |
+| Default | `[]` |
+ List of npm packages that provide macros. Macroforge will look for macros in these packages.
+ ```
 {
   "macroPackages": [
     "@my-org/custom-macros",
     "community-macros"
   ]
 }
-```
-
-### keepDecorators
-
-| Type 
-| `boolean` 
-
-| Default 
-| `false`
-
-Keep `@derive` decorators in the output. Useful for debugging.
-
-### limits
-
-Configure resource limits for macro expansion:
-
-```json
+``` ### keepDecorators
+ | Type | `boolean` |
+| Default | `false` |
+ Keep `@derive` decorators in the output. Useful for debugging.
+ ### limits
+ Configure resource limits for macro expansion:
+ ```
 {
   "limits": {
     // Maximum time for a single macro expansion (ms)
@@ -82,13 +52,9 @@ Configure resource limits for macro expansion:
     "maxDiagnostics": 100
   }
 }
-```
-
-## Macro Runtime Overrides
-
-Override settings for specific macros:
-
-```json
+``` ## Macro Runtime Overrides
+ Override settings for specific macros:
+ ```
 {
   "macroRuntimeOverrides": {
     "@my-org/macros": {
@@ -96,21 +62,12 @@ Override settings for specific macros:
     }
   }
 }
-```
-
-> **Warning:**
-> Be careful when increasing limits, as this could allow malicious macros to consume excessive resources.
-
-## Environment Variables
-
-Some settings can be overridden with environment variables:
-
-| `MACROFORGE_DEBUG` 
-| Enable debug logging 
-
-| `MACROFORGE_LOG_FILE` 
-| Write logs to a file
-
-```bash
+```  **Warning Be careful when increasing limits, as this could allow malicious macros to consume excessive resources. ## Environment Variables
+ Some settings can be overridden with environment variables:
+ | Variable | Description |
+| --- | --- |
+| `MACROFORGE_DEBUG` | Enable debug logging |
+| `MACROFORGE_LOG_FILE` | Write logs to a file |
+ ```
 MACROFORGE_DEBUG=1 npm run dev
-```
+```**