@macroforge/mcp-server 0.1.17

package/docs/concepts/how-macros-work.md

@@ -0,0 +1,124 @@
+# How Macros Work
+
+*Macroforge performs compile-time code generation by parsing your TypeScript, expanding macros, and outputting transformed code. This happens before your code runs, resulting in zero runtime overhead.*
+
+## Compile-Time Expansion
+
+Unlike runtime solutions that use reflection or proxies, Macroforge expands macros at compile time:
+
+1. **Parse**: Your TypeScript code is parsed into an AST using SWC
+
+2. **Find**: Macroforge finds `@derive` decorators and their associated items
+
+3. **Expand**: Each macro generates new code based on the class structure
+
+4. **Output**: The transformed TypeScript is written out, ready for normal compilation
+
+```typescript
+// Your source code
+/** @derive(Debug) */
+class User {
+  name: string;
+}
+
+// After macro expansion
+class User {
+  name: string;
+
+  toString(): string {
+    return \`User { name: \${this.name} }\`;
+  }
+}
+```
+
+## Zero Runtime Overhead
+
+Because code generation happens at compile time, there's no:
+
+- Runtime reflection or metadata
+
+- Proxy objects or wrappers
+
+- Additional dependencies in your bundle
+
+- Performance cost at runtime
+
+The generated code is plain TypeScript that compiles to efficient JavaScript.
+
+## Source Mapping
+
+Macroforge tracks the relationship between your source code and the expanded output. This means:
+
+- Errors in generated code point back to your source
+
+- Debugging works correctly
+
+- IDE features like "go to definition" work as expected
+
+> **Note:**
+> The TypeScript plugin uses source mapping to show errors at the `@derive` decorator position, not in the generated code.
+
+## Execution Flow
+
+```text
+┌─────────────────────────────────────────────────────────┐
+│                    Your Source Code                      │
+│              (with @derive decorators)                   │
+└───────────────────────┬─────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────┐
+│                   SWC Parser                             │
+│            (TypeScript → AST)                            │
+└───────────────────────┬─────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────┐
+│                Macro Expansion Engine                    │
+│    - Finds @derive decorators                            │
+│    - Runs registered macros                              │
+│    - Generates new AST nodes                             │
+└───────────────────────┬─────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────┐
+│                 Code Generator                           │
+│            (AST → TypeScript)                            │
+└───────────────────────┬─────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────┐
+│                 Expanded TypeScript                      │
+│         (ready for normal compilation)                   │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Integration Points
+
+Macroforge integrates at two key points:
+
+### IDE (TypeScript Plugin)
+
+The TypeScript plugin intercepts language server calls to provide:
+
+- Diagnostics that reference your source, not expanded code
+
+- Completions for generated methods
+
+- Hover information showing what macros generate
+
+### Build (Vite Plugin)
+
+The Vite plugin runs macro expansion during the build process:
+
+- Transforms files before they reach the TypeScript compiler
+
+- Generates type declaration files (.d.ts)
+
+- Produces metadata for debugging
+
+## Next Steps
+
+- [Learn about the derive system]({base}/docs/concepts/derive-system)
+
+- [Explore the architecture]({base}/docs/concepts/architecture)

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

@@ -0,0 +1,84 @@
+# Custom Macros
+
+*Macroforge allows you to create custom derive macros in Rust. Your macros have full access to the class AST and can generate any TypeScript code.*
+
+## Overview
+
+Custom macros are written in Rust and compiled to native Node.js addons. The process involves:
+
+1. Creating a Rust crate with NAPI bindings
+
+2. Defining macro functions with `#[ts_macro_derive]`
+
+3. Using `ts_quote` to generate TypeScript code
+
+4. Building and publishing as an npm package
+
+## Quick Example
+
+```rust
+use macroforge_ts::ts_macro_derive::ts_macro_derive;
+use macroforge_ts::ts_quote::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> {
+    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}
+                    };
+                }
+            })
+        }
+        _ => Err(MacroforgeError::new(
+            input.decorator_span(),
+            "@derive(JSON) only works on classes",
+        )),
+    }
+}
+```
+
+## Using Custom Macros
+
+Once your macro package is published, users can import and use it:
+
+```typescript
+/** import macro { JSON } from "@my/macros"; */
+
+/** @derive(JSON) */
+class User {
+  name: string;
+  age: number;
+
+  constructor(name: string, age: number) {
+    this.name = name;
+    this.age = age;
+  }
+}
+
+const user = new User("Alice", 30);
+console.log(user.toJSON()); // { name: "Alice", age: 30 }
+```
+
+>
+> 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]({base}/docs/custom-macros/rust-setup)
+
+- [Use the ts_macro_derive attribute]({base}/docs/custom-macros/ts-macro-derive)
+
+- [Learn the ts_quote template syntax]({base}/docs/custom-macros/ts-quote)

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

@@ -0,0 +1,146 @@
+# Rust Setup
+
+*Create a new Rust crate that will contain your custom macros. This crate compiles to a native Node.js addon.*
+
+## Prerequisites
+
+- Rust toolchain (1.70 or later)
+
+- Node.js 18 or later
+
+- NAPI-RS CLI: `npm install -g @napi-rs/cli`
+
+## Create the Project
+
+```bash
+# Create a new directory
+mkdir my-macros
+cd my-macros
+
+# Initialize with NAPI-RS
+napi new --platform --name my-macros
+```
+
+## Configure Cargo.toml
+
+Update your `Cargo.toml` with the required dependencies:
+
+`Cargo.toml`
+```toml
+[package]
+name = "my-macros"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+macroforge_ts = "0.1"
+napi = { version = "3", features = ["napi8", "compat-mode"] }
+napi-derive = "3"
+
+[build-dependencies]
+napi-build = "2"
+
+[profile.release]
+lto = true
+strip = true
+```
+
+## Create build.rs
+
+`build.rs`
+```rust
+fn main() {
+    napi_build::setup();
+}
+```
+
+## Create src/lib.rs
+
+`src/lib.rs`
+```rust
+use macroforge_ts::ts_macro_derive::ts_macro_derive;
+use macroforge_ts::ts_quote::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> {
+    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}
+                    };
+                }
+            })
+        }
+        _ => Err(MacroforgeError::new(
+            input.decorator_span(),
+            "@derive(JSON) only works on classes",
+        )),
+    }
+}
+```
+
+## Create package.json
+
+`package.json`
+```json
+{
+  "name": "@my-org/macros",
+  "version": "0.1.0",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "napi": {
+    "name": "my-macros",
+    "triples": {
+      "defaults": true
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "*.node"
+  ],
+  "scripts": {
+    "build": "napi build --release",
+    "prepublishOnly": "napi build --release"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.0.0-alpha.0"
+  }
+}
+```
+
+## Build the Package
+
+```bash
+# Build the native addon
+npm run build
+
+# This creates:
+# - index.js (JavaScript bindings)
+# - index.d.ts (TypeScript types)
+# - *.node (native binary)
+```
+
+>
+> For cross-platform builds, use GitHub Actions with the NAPI-RS CI template.
+
+## Next Steps
+
+- [Learn the ts_macro_derive attribute]({base}/docs/custom-macros/ts-macro-derive)
+
+- [Master the ts_quote template syntax]({base}/docs/custom-macros/ts-quote)

package/docs/custom-macros/ts-macro-derive.md

@@ -0,0 +1,307 @@
+# ts_macro_derive
+
+*The `#[ts_macro_derive]` attribute is a Rust procedural macro that registers your function as a Macroforge derive macro.*
+
+## Basic Syntax
+
+```rust
+use macroforge_ts::ts_macro_derive::ts_macro_derive;
+use macroforge_ts::ts_syn::{TsStream, MacroforgeError};
+
+#[ts_macro_derive(MacroName)]
+pub fn my_macro(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
+    // Macro implementation
+}
+```
+
+## Attribute Options
+
+### Name (Required)
+
+The first argument is the macro name that users will reference in `@derive()`:
+
+```rust
+#[ts_macro_derive(JSON)]  // Users write: @derive(JSON)
+pub fn derive_json(...)
+```
+
+### Description
+
+Provides documentation for the macro:
+
+```rust
+#[ts_macro_derive(
+    JSON,
+    description = "Generates toJSON() returning a plain object"
+)]
+pub fn derive_json(...)
+```
+
+### Attributes
+
+Declare which field-level decorators your macro accepts:
+
+```rust
+#[ts_macro_derive(
+    Debug,
+    description = "Generates toString()",
+    attributes(debug)  // Allows @debug({ ... }) on fields
+)]
+pub fn derive_debug(...)
+```
+
+>
+> Declared attributes become available as `@attributeName(&#123; options &#125;)` decorators in TypeScript.
+
+## Function Signature
+
+```rust
+pub fn my_macro(mut input: TsStream) -> Result<TsStream, MacroforgeError>
+```
+
+| `input: TsStream` 
+| Token stream containing the class/interface AST 
+
+| `Result<TsStream, MacroforgeError>` 
+| Returns generated code or an error with source location
+
+## Parsing Input
+
+Use `parse_ts_macro_input!` to convert the token stream:
+
+```rust
+use macroforge_ts::ts_syn::{DeriveInput, Data, parse_ts_macro_input};
+
+#[ts_macro_derive(MyMacro)]
+pub fn my_macro(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
+    let input = parse_ts_macro_input!(input as DeriveInput);
+
+    // Access class data
+    match &input.data {
+        Data::Class(class) => {
+            let class_name = input.name();
+            let fields = class.fields();
+            // ...
+        }
+        Data::Interface(interface) => {
+            // Handle interfaces
+        }
+        Data::Enum(_) => {
+            // Handle enums (if supported)
+        }
+    }
+}
+```
+
+## DeriveInput Structure
+
+```rust
+struct DeriveInput {
+    pub ident: Ident,           // The type name
+    pub span: SpanIR,           // Span of the type definition
+    pub attrs: Vec<Attribute>,  // Decorators (excluding @derive)
+    pub data: Data,             // The parsed type data
+    pub context: MacroContextIR, // Macro context with spans
+
+    // Helper methods
+    fn name(&self) -> &str;              // Get the type name
+    fn decorator_span(&self) -> SpanIR;  // Span of @derive decorator
+    fn as_class(&self) -> Option<&DataClass>;
+    fn as_interface(&self) -> Option<&DataInterface>;
+    fn as_enum(&self) -> Option<&DataEnum>;
+}
+
+enum Data {
+    Class(DataClass),
+    Interface(DataInterface),
+    Enum(DataEnum),
+    TypeAlias(DataTypeAlias),
+}
+
+impl DataClass {
+    fn fields(&self) -> &[FieldIR];
+    fn methods(&self) -> &[MethodSigIR];
+    fn field_names(&self) -> impl Iterator<Item = &str>;
+    fn field(&self, name: &str) -> Option<&FieldIR>;
+    fn body_span(&self) -> SpanIR;      // For inserting code into class body
+    fn type_params(&self) -> &[String]; // Generic type parameters
+    fn heritage(&self) -> &[String];    // extends/implements clauses
+    fn is_abstract(&self) -> bool;
+}
+
+impl DataInterface {
+    fn fields(&self) -> &[InterfaceFieldIR];
+    fn methods(&self) -> &[InterfaceMethodIR];
+    fn field_names(&self) -> impl Iterator<Item = &str>;
+    fn field(&self, name: &str) -> Option<&InterfaceFieldIR>;
+    fn body_span(&self) -> SpanIR;
+    fn type_params(&self) -> &[String];
+    fn heritage(&self) -> &[String];    // extends clauses
+}
+
+impl DataEnum {
+    fn variants(&self) -> &[EnumVariantIR];
+    fn variant_names(&self) -> impl Iterator<Item = &str>;
+    fn variant(&self, name: &str) -> Option<&EnumVariantIR>;
+}
+
+impl DataTypeAlias {
+    fn body(&self) -> &TypeBody;
+    fn type_params(&self) -> &[String];
+    fn is_union(&self) -> bool;
+    fn is_object(&self) -> bool;
+    fn as_union(&self) -> Option<&[TypeMember]>;
+    fn as_object(&self) -> Option<&[InterfaceFieldIR]>;
+}
+```
+
+## Accessing Field Data
+
+### Class Fields (FieldIR)
+
+```rust
+struct FieldIR {
+    pub name: String,               // Field name
+    pub span: SpanIR,               // Field span
+    pub ts_type: String,            // TypeScript type annotation
+    pub optional: bool,             // Whether field has ?
+    pub readonly: bool,             // Whether field is readonly
+    pub visibility: Visibility,     // Public, Protected, Private
+    pub decorators: Vec<DecoratorIR>, // Field decorators
+}
+```
+
+### Interface Fields (InterfaceFieldIR)
+
+```rust
+struct InterfaceFieldIR {
+    pub name: String,
+    pub span: SpanIR,
+    pub ts_type: String,
+    pub optional: bool,
+    pub readonly: bool,
+    pub decorators: Vec<DecoratorIR>,
+    // Note: No visibility field (interfaces are always public)
+}
+```
+
+### Enum Variants (EnumVariantIR)
+
+```rust
+struct EnumVariantIR {
+    pub name: String,
+    pub span: SpanIR,
+    pub value: EnumValue,  // Auto, String(String), or Number(f64)
+    pub decorators: Vec<DecoratorIR>,
+}
+```
+
+### Decorator Structure
+
+```rust
+struct DecoratorIR {
+    pub name: String,      // e.g., "serde"
+    pub args_src: String,  // Raw args text, e.g., "skip, rename: 'id'"
+    pub span: SpanIR,
+}
+```
+
+>
+> To check for decorators, iterate through `field.decorators` and check `decorator.name`. For parsing options, you can write helper functions like the built-in macros do.
+
+## Adding Imports
+
+If your macro generates code that requires imports, use the `add_import` method on `TsStream`:
+
+```rust
+// Add an import to be inserted at the top of the file
+let mut output = body! {
+    validate(): ValidationResult {
+        return validateFields(this);
+    }
+};
+
+// This will add: import { validateFields, ValidationResult } from "my-validation-lib";
+output.add_import("validateFields", "my-validation-lib");
+output.add_import("ValidationResult", "my-validation-lib");
+
+Ok(output)
+```
+
+>
+> Imports are automatically deduplicated. If the same import already exists in the file, it won't be added again.
+
+## Returning Errors
+
+Use `MacroforgeError` to report errors with source locations:
+
+```rust
+#[ts_macro_derive(ClassOnly)]
+pub fn class_only(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
+    let input = parse_ts_macro_input!(input as DeriveInput);
+
+    match &input.data {
+        Data::Class(_) => {
+            // Generate code...
+            Ok(body! { /* ... */ })
+        }
+        _ => Err(MacroforgeError::new(
+            input.decorator_span(),
+            "@derive(ClassOnly) can only be used on classes",
+        )),
+    }
+}
+```
+
+## Complete Example
+
+```rust
+use macroforge_ts::ts_macro_derive::ts_macro_derive;
+use macroforge_ts::ts_quote::body;
+use macroforge_ts::ts_syn::{
+    Data, DeriveInput, FieldIR, MacroforgeError, TsStream, parse_ts_macro_input,
+};
+
+// Helper function to check if a field has a decorator
+fn has_decorator(field: &FieldIR, name: &str) -> bool {
+    field.decorators.iter().any(|d| d.name.eq_ignore_ascii_case(name))
+}
+
+#[ts_macro_derive(
+    Validate,
+    description = "Generates a validate() method",
+    attributes(validate)
+)]
+pub fn derive_validate(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
+    let input = parse_ts_macro_input!(input as DeriveInput);
+
+    match &input.data {
+        Data::Class(class) => {
+            let validations: Vec<_> = class.fields()
+                .iter()
+                .filter(|f| has_decorator(f, "validate"))
+                .collect();
+
+            Ok(body! {
+                validate(): string[] {
+                    const errors: string[] = [];
+                    {#for field in validations}
+                        if (!this.@{field.name}) {
+                            errors.push("@{field.name} is required");
+                        }
+                    {/for}
+                    return errors;
+                }
+            })
+        }
+        _ => Err(MacroforgeError::new(
+            input.decorator_span(),
+            "@derive(Validate) only works on classes",
+        )),
+    }
+}
+```
+
+## Next Steps
+
+- [Learn the ts_quote template syntax]({base}/docs/custom-macros/ts-quote)