@macroforge/mcp-server 0.1.17

package/docs/builtin-macros/serialize.md

@@ -0,0 +1,321 @@
+# Serialize
+
+*The `Serialize` macro generates a `toJSON()` method that converts your object to a JSON-compatible format with automatic handling of complex types like Date, Map, Set, and nested objects.*
+
+## Basic Usage
+
+```typescript
+/** @derive(Serialize) */
+class User {
+  name: string;
+  age: number;
+  createdAt: Date;
+
+  constructor(name: string, age: number) {
+    this.name = name;
+    this.age = age;
+    this.createdAt = new Date();
+  }
+}
+
+const user = new User("Alice", 30);
+console.log(JSON.stringify(user));
+// {"name":"Alice","age":30,"createdAt":"2024-01-15T10:30:00.000Z"}
+```
+
+## Generated Code
+
+```typescript
+toJSON(): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  result["name"] = this.name;
+  result["age"] = this.age;
+  result["createdAt"] = this.createdAt.toISOString();
+  return result;
+}
+```
+
+## Automatic Type Handling
+
+Serialize automatically handles various TypeScript types:
+
+| `string`, `number`, `boolean` 
+| Direct copy 
+
+| `Date` 
+| `.toISOString()` 
+
+| `T[]` 
+| Maps items, calling `toJSON()` if available 
+
+| `Map<K, V>` 
+| `Object.fromEntries()` 
+
+| `Set<T>` 
+| `Array.from()` 
+
+| Nested objects 
+| Calls `toJSON()` if available
+
+```typescript
+/** @derive(Serialize) */
+class DataContainer {
+  items: string[];
+  metadata: Map<string, number>;
+  tags: Set<string>;
+  nested: User;
+}
+```
+
+## Serde Options
+
+Use the `@serde` decorator for fine-grained control over serialization:
+
+### Renaming Fields
+
+```typescript
+/** @derive(Serialize) */
+class User {
+  /** @serde({ rename: "user_id" }) */
+  id: string;
+
+  /** @serde({ rename: "full_name" }) */
+  name: string;
+}
+
+const user = new User();
+user.id = "123";
+user.name = "Alice";
+console.log(JSON.stringify(user));
+// {"user_id":"123","full_name":"Alice"}
+```
+
+### Skipping Fields
+
+```typescript
+/** @derive(Serialize) */
+class User {
+  name: string;
+  email: string;
+
+  /** @serde({ skip: true }) */
+  password: string;
+
+  /** @serde({ skip_serializing: true }) */
+  internalId: string;
+}
+```
+
+<Alert type="tip" title="skip vs skip_serializing">
+Use `skip: true` to exclude from both serialization and deserialization.
+Use `skip_serializing: true` to only skip during serialization.
+</Alert>
+
+### Rename All Fields
+
+Apply a naming convention to all fields at the container level:
+
+```typescript
+/** @derive(Serialize) */
+/** @serde({ rename_all: "camelCase" }) */
+class ApiResponse {
+  user_name: string;    // becomes "userName"
+  created_at: Date;     // becomes "createdAt"
+  is_active: boolean;   // becomes "isActive"
+}
+```
+
+Supported conventions:
+
+- `camelCase`
+
+- `snake_case`
+
+- `PascalCase`
+
+- `SCREAMING_SNAKE_CASE`
+
+- `kebab-case`
+
+### Flattening Nested Objects
+
+```typescript
+/** @derive(Serialize) */
+class Address {
+  city: string;
+  zip: string;
+}
+
+/** @derive(Serialize) */
+class User {
+  name: string;
+
+  /** @serde({ flatten: true }) */
+  address: Address;
+}
+
+const user = new User();
+user.name = "Alice";
+user.address = { city: "NYC", zip: "10001" };
+console.log(JSON.stringify(user));
+// {"name":"Alice","city":"NYC","zip":"10001"}
+```
+
+## All Options
+
+### Container Options (on class/interface)
+
+| `rename_all` 
+| `string` 
+| Apply naming convention to all fields
+
+### Field Options (on properties)
+
+| `rename` 
+| `string` 
+| Use a different JSON key 
+
+| `skip` 
+| `boolean` 
+| Exclude from serialization and deserialization 
+
+| `skip_serializing` 
+| `boolean` 
+| Exclude from serialization only 
+
+| `flatten` 
+| `boolean` 
+| Merge nested object fields into parent
+
+## Interface Support
+
+Serialize also works with interfaces. For interfaces, a namespace is generated with a `toJSON` function:
+
+```typescript
+/** @derive(Serialize) */
+interface ApiResponse {
+  status: number;
+  message: string;
+  timestamp: Date;
+}
+
+// Generated:
+// export namespace ApiResponse {
+//   export function toJSON(self: ApiResponse): Record<string, unknown> {
+//     const result: Record<string, unknown> = {};
+//     result["status"] = self.status;
+//     result["message"] = self.message;
+//     result["timestamp"] = self.timestamp.toISOString();
+//     return result;
+//   }
+// }
+
+const response: ApiResponse = {
+  status: 200,
+  message: "OK",
+  timestamp: new Date()
+};
+
+console.log(JSON.stringify(ApiResponse.toJSON(response)));
+// {"status":200,"message":"OK","timestamp":"2024-01-15T10:30:00.000Z"}
+```
+
+## Enum Support
+
+Serialize also works with enums. The `toJSON` function returns the underlying enum value (string or number):
+
+```typescript
+/** @derive(Serialize) */
+enum Status {
+  Active = "active",
+  Inactive = "inactive",
+  Pending = "pending",
+}
+
+// Generated:
+// export namespace Status {
+//   export function toJSON(value: Status): string | number {
+//     return value;
+//   }
+// }
+
+console.log(Status.toJSON(Status.Active));  // "active"
+console.log(Status.toJSON(Status.Pending)); // "pending"
+```
+
+Works with numeric enums too:
+
+```typescript
+/** @derive(Serialize) */
+enum Priority {
+  Low = 1,
+  Medium = 2,
+  High = 3,
+}
+
+console.log(Priority.toJSON(Priority.High)); // 3
+```
+
+## Type Alias Support
+
+Serialize works with type aliases. For object types, fields are serialized with full type handling:
+
+```typescript
+/** @derive(Serialize) */
+type UserProfile = {
+  id: string;
+  name: string;
+  createdAt: Date;
+};
+
+// Generated:
+// export namespace UserProfile {
+//   export function toJSON(value: UserProfile): Record<string, unknown> {
+//     const result: Record<string, unknown> = {};
+//     result["id"] = value.id;
+//     result["name"] = value.name;
+//     result["createdAt"] = value.createdAt.toISOString();
+//     return result;
+//   }
+// }
+
+const profile: UserProfile = {
+  id: "123",
+  name: "Alice",
+  createdAt: new Date("2024-01-15")
+};
+
+console.log(JSON.stringify(UserProfile.toJSON(profile)));
+// {"id":"123","name":"Alice","createdAt":"2024-01-15T00:00:00.000Z"}
+```
+
+For union types, the value is returned directly:
+
+```typescript
+/** @derive(Serialize) */
+type ApiStatus = "loading" | "success" | "error";
+
+console.log(ApiStatus.toJSON("success")); // "success"
+```
+
+## Combining with Deserialize
+
+Use both Serialize and Deserialize for complete JSON round-trip support:
+
+```typescript
+/** @derive(Serialize, Deserialize) */
+class User {
+  name: string;
+  createdAt: Date;
+}
+
+// Serialize
+const user = new User();
+user.name = "Alice";
+user.createdAt = new Date();
+const json = JSON.stringify(user);
+
+// Deserialize
+const parsed = User.fromJSON(JSON.parse(json));
+console.log(parsed.createdAt instanceof Date); // true
+```

package/docs/concepts/architecture.md

@@ -0,0 +1,139 @@
+# Architecture
+
+*Macroforge is built as a native Node.js module using Rust and NAPI-RS. It leverages SWC for fast TypeScript parsing and code generation.*
+
+## Overview
+
+```text
+┌─────────────────────────────────────────────────────────┐
+│                    Node.js / Vite                        │
+├─────────────────────────────────────────────────────────┤
+│                   NAPI-RS Bindings                       │
+├─────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐   │
+│  │   ts_syn    │  │   ts_quote   │  │ts_macro_derive│   │
+│  │  (parsing)  │  │ (templating) │  │  (proc-macro) │   │
+│  └─────────────┘  └──────────────┘  └───────────────┘   │
+├─────────────────────────────────────────────────────────┤
+│                    SWC Core                              │
+│            (TypeScript parsing & codegen)                │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Core Components
+
+### SWC Core
+
+The foundation layer provides:
+
+- Fast TypeScript/JavaScript parsing
+
+- AST representation
+
+- Code generation (AST → source code)
+
+### ts_syn
+
+A Rust crate that provides:
+
+- TypeScript-specific AST types
+
+- Parsing utilities for macro input
+
+- Derive input structures (class fields, decorators, etc.)
+
+### ts_quote
+
+Template-based code generation similar to Rust's `quote!`:
+
+- `ts_template!` - Generate TypeScript code from templates
+
+- `body!` - Generate class body members
+
+- Control flow: `{"{#for}"}`, `{"{#if}"}`, `{"{$let}"}`
+
+### ts_macro_derive
+
+The procedural macro attribute for defining derive macros:
+
+- `#[ts_macro_derive(Name)]` attribute
+
+- Automatic registration with the macro system
+
+- Error handling and span tracking
+
+### NAPI-RS Bindings
+
+Bridges Rust and Node.js:
+
+- Exposes `expandSync`, `transformSync`, etc.
+
+- Provides the `NativePlugin` class for caching
+
+- Handles data marshaling between Rust and JavaScript
+
+## Data Flow
+
+```text
+1. Source Code (TypeScript with @derive)
+   │
+   ▼
+2. NAPI-RS receives JavaScript string
+   │
+   ▼
+3. SWC parses to AST
+   │
+   ▼
+4. Macro expander finds @derive decorators
+   │
+   ▼
+5. For each macro:
+   │  a. Extract class/interface data
+   │  b. Run macro function
+   │  c. Generate new AST nodes
+   │
+   ▼
+6. Merge generated nodes into AST
+   │
+   ▼
+7. SWC generates source code
+   │
+   ▼
+8. Return to JavaScript with source mapping
+```
+
+## Performance Characteristics
+
+- **Thread-safe**: Each expansion runs in an isolated thread with a 32MB stack
+
+- **Caching**: `NativePlugin` caches results by file version
+
+- **Binary search**: Position mapping uses O(log n) lookups
+
+- **Zero-copy**: SWC's arena allocator minimizes allocations
+
+## Re-exported Crates
+
+For custom macro development, `macroforge_ts` re-exports everything you need:
+
+```rust
+// All available via macroforge_ts::*
+pub extern crate ts_syn;         // AST types, parsing
+pub extern crate ts_quote;       // Code generation templates
+pub extern crate ts_macro_derive; // #[ts_macro_derive] attribute
+pub extern crate inventory;       // Macro registration
+pub extern crate serde_json;      // Serialization
+pub extern crate napi;            // Node.js bindings
+pub extern crate napi_derive;     // NAPI proc-macros
+
+// SWC modules
+pub use ts_syn::swc_core;
+pub use ts_syn::swc_common;
+pub use ts_syn::swc_ecma_ast;
+```
+
+## Next Steps
+
+- [Write custom macros]({base}/docs/custom-macros)
+
+- [Explore the API reference]({base}/docs/api)

package/docs/concepts/derive-system.md

@@ -0,0 +1,173 @@
+# The Derive System
+
+*The derive system is inspired by Rust's derive macros. It allows you to automatically implement common patterns by annotating your classes with `@derive`.*
+
+## Syntax Reference
+
+Macroforge uses JSDoc comments for all macro annotations. This ensures compatibility with standard TypeScript tooling.
+
+### The @derive Statement
+
+The `@derive` decorator triggers macro expansion on a class or interface:
+
+```typescript
+/** @derive(MacroName) */
+class MyClass { }
+
+/** @derive(Debug, Clone, PartialEq) */
+class AnotherClass { }
+```
+
+Syntax rules:
+
+- Must be inside a JSDoc comment (`/** */`)
+
+- Must appear immediately before the class/interface declaration
+
+- Multiple macros can be comma-separated: `@derive(A, B, C)`
+
+- Multiple `@derive` statements can be stacked
+
+```typescript
+// Single derive with multiple macros
+/** @derive(Debug, Clone) */
+class User { }
+
+// Multiple derive statements (equivalent)
+/** @derive(Debug) */
+/** @derive(Clone) */
+class User { }
+```
+
+### The import macro Statement
+
+To use macros from external packages, you must declare them with `import macro`:
+
+```typescript
+/** 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
+
+```typescript
+/** import macro { JSON, Validate } from "@my/macros"; */
+/** import macro { Builder } from "@other/macros"; */
+
+/** @derive(JSON, Validate, Builder) */
+class User {
+  name: string;
+  email: string;
+}
+```
+
+>
+> 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:
+
+```typescript
+/** @attributeName(options) */
+```
+
+The attribute name and available options depend on the macro. Common patterns:
+
+```typescript
+/** @derive(Debug, Serialize) */
+class User {
+  /** @debug({ rename: "userId" }) */
+  /** @serde({ rename: "user_id" }) */
+  id: number;
+
+  name: string;
+
+  /** @debug({ skip: true }) */
+  /** @serde({ skip: true }) */
+  password: string;
+
+  /** @serde({ flatten: true }) */
+  metadata: Record<string, unknown>;
+}
+```
+
+Syntax rules:
+
+- Must be inside a JSDoc comment immediately before the field
+
+- Options use object literal syntax: `@attr(&#123; key: value &#125;)`
+
+- Boolean options: `@attr(&#123; skip: true &#125;)`
+
+- String options: `@attr(&#123; rename: "newName" &#125;)`
+
+- Multiple attributes can be on separate lines or combined
+
+Common field attributes by macro:
+
+| Debug 
+| `@debug` 
+| `skip`, `rename` 
+
+| Clone 
+| `@clone` 
+| `skip`, `clone_with` 
+
+| Serialize/Deserialize 
+| `@serde` 
+| `skip`, `rename`, `flatten`, `default` 
+
+| Hash 
+| `@hash` 
+| `skip` 
+
+| PartialEq/Ord 
+| `@eq`, `@ord` 
+| `skip`
+
+## How It Works
+
+1. **Declaration**: You write `@derive(MacroName)` before a class
+
+2. **Discovery**: Macroforge finds all derive decorators in your code
+
+3. **Expansion**: Each named macro receives the class AST and generates code
+
+4. **Injection**: Generated methods/properties are added to the class
+
+## What Can Be Derived
+
+The derive system works on:
+
+- **Classes**: The primary target for derive macros
+
+- **Interfaces**: Some macros can generate companion functions
+
+> **Warning:**
+> Enums are not currently supported by the derive system.
+
+## Built-in vs Custom Macros
+
+Macroforge comes with built-in macros that work out of the box. You can also create custom macros in Rust and use them via the `import macro` statement.
+
+| Built-in 
+| No 
+| Debug, Clone, Default, Hash, Ord, PartialEq, PartialOrd, Serialize, Deserialize 
+
+| Custom 
+| Yes 
+| Any macro from an external package
+
+## Next Steps
+
+- [Explore built-in macros]({base}/docs/builtin-macros)
+
+- [Create custom macros]({base}/docs/custom-macros)