@macroforge/mcp-server 0.1.17

package/docs/builtin-macros/debug.md

@@ -0,0 +1,222 @@
+# Debug
+
+*The `Debug` macro generates a `toString()` method that produces a human-readable string representation of your class.*
+
+## Basic Usage
+
+```typescript
+/** @derive(Debug) */
+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.toString());
+// Output: User { name: Alice, age: 30 }
+```
+
+## Generated Code
+
+```typescript
+toString(): string {
+  const parts: string[] = [];
+  parts.push("name: " + this.name);
+  parts.push("age: " + this.age);
+  return "User { " + parts.join(", ") + " }";
+}
+```
+
+## Field Options
+
+Use the `@debug` field decorator to customize behavior:
+
+### Renaming Fields
+
+```typescript
+/** @derive(Debug) */
+class User {
+  /** @debug({ rename: "userId" }) */
+  id: number;
+
+  name: string;
+
+  constructor(id: number, name: string) {
+    this.id = id;
+    this.name = name;
+  }
+}
+
+const user = new User(42, "Alice");
+console.log(user.toString());
+// Output: User { userId: 42, name: Alice }
+```
+
+### Skipping Fields
+
+Use `skip: true` to exclude sensitive fields from the output:
+
+```typescript
+/** @derive(Debug) */
+class User {
+  name: string;
+  email: string;
+
+  /** @debug({ skip: true }) */
+  password: string;
+
+  /** @debug({ skip: true }) */
+  authToken: string;
+
+  constructor(name: string, email: string, password: string, authToken: string) {
+    this.name = name;
+    this.email = email;
+    this.password = password;
+    this.authToken = authToken;
+  }
+}
+
+const user = new User("Alice", "alice@example.com", "secret", "tok_xxx");
+console.log(user.toString());
+// Output: User { name: Alice, email: alice@example.com }
+// Note: password and authToken are not included
+```
+
+<Alert type="tip" title="Security">
+Always skip sensitive fields like passwords, tokens, and API keys to prevent accidental logging.
+</Alert>
+
+## Combining Options
+
+```typescript
+/** @derive(Debug) */
+class ApiResponse {
+  /** @debug({ rename: "statusCode" }) */
+  status: number;
+
+  data: unknown;
+
+  /** @debug({ skip: true }) */
+  internalMetadata: Record<string, unknown>;
+}
+```
+
+## All Options
+
+| `rename` 
+| `string` 
+| Display a different name in the output 
+
+| `skip` 
+| `boolean` 
+| Exclude this field from the output
+
+## Interface Support
+
+Debug also works with interfaces. For interfaces, a namespace is generated with a `toString` function:
+
+```typescript
+/** @derive(Debug) */
+interface Status {
+  active: boolean;
+  message: string;
+}
+
+// Generated:
+// export namespace Status {
+//   export function toString(self: Status): string {
+//     const parts: string[] = [];
+//     parts.push("active: " + self.active);
+//     parts.push("message: " + self.message);
+//     return "Status { " + parts.join(", ") + " }";
+//   }
+// }
+
+const status: Status = { active: true, message: "OK" };
+console.log(Status.toString(status));
+// Output: Status { active: true, message: OK }
+```
+
+## Enum Support
+
+Debug also works with enums. For enums, a namespace is generated with a `toString` function that displays the enum name and variant:
+
+```typescript
+/** @derive(Debug) */
+enum Priority {
+  Low = 1,
+  Medium = 2,
+  High = 3,
+}
+
+// Generated:
+// export namespace Priority {
+//   export function toString(value: Priority): string {
+//     const key = Priority[value as unknown as keyof typeof Priority];
+//     if (key !== undefined) {
+//       return "Priority." + key;
+//     }
+//     return "Priority(" + String(value) + ")";
+//   }
+// }
+
+console.log(Priority.toString(Priority.High));
+// Output: Priority.High
+
+console.log(Priority.toString(Priority.Low));
+// Output: Priority.Low
+```
+
+Works with both numeric and string enums:
+
+```typescript
+/** @derive(Debug) */
+enum Status {
+  Active = "active",
+  Inactive = "inactive",
+}
+
+console.log(Status.toString(Status.Active));
+// Output: Status.Active
+```
+
+## Type Alias Support
+
+Debug works with type aliases. For object types, fields are displayed similar to interfaces:
+
+```typescript
+/** @derive(Debug) */
+type Point = {
+  x: number;
+  y: number;
+};
+
+// Generated:
+// export namespace Point {
+//   export function toString(value: Point): string {
+//     const parts: string[] = [];
+//     parts.push("x: " + value.x);
+//     parts.push("y: " + value.y);
+//     return "Point { " + parts.join(", ") + " }";
+//   }
+// }
+
+const point: Point = { x: 10, y: 20 };
+console.log(Point.toString(point));
+// Output: Point { x: 10, y: 20 }
+```
+
+For union types, the value is displayed using JSON.stringify:
+
+```typescript
+/** @derive(Debug) */
+type ApiStatus = "loading" | "success" | "error";
+
+console.log(ApiStatus.toString("success"));
+// Output: ApiStatus("success")
+```

package/docs/builtin-macros/default.md

@@ -0,0 +1,192 @@
+# Default
+
+*The `Default` macro generates a static `default()` factory method that creates instances with default field values.*
+
+## Basic Usage
+
+```typescript
+/** @derive(Default) */
+class Config {
+  host: string;
+  port: number;
+  enabled: boolean;
+
+  constructor(host: string, port: number, enabled: boolean) {
+    this.host = host;
+    this.port = port;
+    this.enabled = enabled;
+  }
+}
+
+const config = Config.default();
+console.log(config.host);    // ""
+console.log(config.port);    // 0
+console.log(config.enabled); // false
+```
+
+## Generated Code
+
+The Default macro generates a static factory method:
+
+```typescript
+static default(): Config {
+    const instance = new Config();
+    instance.host = "";
+    instance.port = 0;
+    instance.enabled = false;
+    return instance;
+}
+```
+
+## Automatic Default Values
+
+The Default macro automatically determines default values based on field types:
+
+- `string` → `""` (empty string)
+
+- `number` → `0`
+
+- `boolean` → `false`
+
+- `bigint` → `0n`
+
+- `Array<T>` or `T[]` → `[]` (empty array)
+
+- `Map<K, V>` → `new Map()`
+
+- `Set<T>` → `new Set()`
+
+- `Date` → `new Date()`
+
+- Custom types → `null as any`
+
+## Custom Default Values
+
+Use the `@defaultValue()` decorator to specify custom default values for fields:
+
+```typescript
+/** @derive(Default) */
+class ServerConfig {
+  /** @defaultValue("localhost") */
+  host: string;
+
+  /** @defaultValue(8080) */
+  port: number;
+
+  /** @defaultValue(true) */
+  enabled: boolean;
+
+  /** @defaultValue(["info", "error"]) */
+  logLevels: string[];
+
+  constructor(host: string, port: number, enabled: boolean, logLevels: string[]) {
+    this.host = host;
+    this.port = port;
+    this.enabled = enabled;
+    this.logLevels = logLevels;
+  }
+}
+
+const config = ServerConfig.default();
+console.log(config.host);      // "localhost"
+console.log(config.port);      // 8080
+console.log(config.enabled);   // true
+console.log(config.logLevels); // ["info", "error"]
+```
+
+## Interface Support
+
+Default also works with interfaces. For interfaces, a namespace is generated with a `default_()` function (note the underscore to avoid conflicts with the reserved word):
+
+```typescript
+/** @derive(Default) */
+interface Point {
+  x: number;
+  y: number;
+}
+
+// Generated:
+// export namespace Point {
+//   export function default_(): Point {
+//     return {
+//       x: 0,
+//       y: 0
+//     } as Point;
+//   }
+// }
+
+const origin = Point.default_();
+console.log(origin); // { x: 0, y: 0 }
+```
+
+## Enum Support
+
+Default works with enums. For enums, it returns the first variant as the default value:
+
+```typescript
+/** @derive(Default) */
+enum Status {
+  Pending = "pending",
+  Active = "active",
+  Completed = "completed",
+}
+
+// Generated:
+// export namespace Status {
+//   export function default_(): Status {
+//     return Status.Pending;
+//   }
+// }
+
+const defaultStatus = Status.default_();
+console.log(defaultStatus); // "pending"
+```
+
+## Type Alias Support
+
+Default works with type aliases. For object types, it creates an object with default field values:
+
+```typescript
+/** @derive(Default) */
+type Dimensions = {
+  width: number;
+  height: number;
+};
+
+// Generated:
+// export namespace Dimensions {
+//   export function default_(): Dimensions {
+//     return {
+//       width: 0,
+//       height: 0
+//     } as Dimensions;
+//   }
+// }
+
+const dims = Dimensions.default_();
+console.log(dims); // { width: 0, height: 0 }
+```
+
+## Combining with Other Macros
+
+```typescript
+/** @derive(Default, Debug, Clone, PartialEq) */
+class User {
+  /** @defaultValue("Anonymous") */
+  name: string;
+
+  /** @defaultValue(0) */
+  age: number;
+
+  constructor(name: string, age: number) {
+    this.name = name;
+    this.age = age;
+  }
+}
+
+const user1 = User.default();
+const user2 = user1.clone();
+
+console.log(user1.toString());    // User { name: "Anonymous", age: 0 }
+console.log(user1.equals(user2)); // true
+```