hakorune/docs/guides/macro-box-nyash.md

# MacroBox in Nyash (Design Draft)

Status: Design draft (Phase 16+). This document specifies the Nyash-side API for user-extensible macros that execute during compilation (pre-MIR). Rust prototype exists; this spec focuses on the Nyash interface and constraints.

Philosophy
- Box Independence (loose coupling): macro expands against public interfaces only; avoid coupling to private internals.
- Deterministic, side-effect free: no IO, no randomness, no time/env dependence.
- Safety and staging: runs in a sandbox before MIR generation; never observes runtime state.

API (Nyash)
```nyash
box MacroBoxSpec {
  // Required entry. Receives AST JSON and returns transformed AST JSON.
  static function expand(json, ctx) { /* pure transform over JSON string */ }

  // Optional metadata.
  static function name() { return "MyMacro" }
}
```

Registration
- Declared in `nyash.toml` (planned):
```
[macros]
paths = [
  "apps/macros/my_macro.hako",
  "apps/macros/json_lints.hako"
]
```
- Loading policy: register via `NYASH_MACRO_PATHS=path1,path2`（推奨）。
- Runner route is default（self‑hosting優先）。内部子ルートは非推奨（`NYASH_MACRO_BOX_CHILD_RUNNER=0` 強制時のみ）。
- Isolation: loaded in a dedicated interpreter with IO disabled; only AST utilities and safe helpers exposed.
 - Interim mapping (prototype): `name()` may map to built-in MacroBoxes for effects (e.g., `"UppercasePrintMacro"`). Otherwise, identity transform.

Execution Order
- Built-in (Rust) macro passes
- User MacroBoxes (Nyash) in registration order
- Test harness injection
- Stop on fixed point, or when reaching the pass/cycle guard limits.

Guards
- Max passes: `NYASH_MACRO_MAX_PASSES` (default 32)
- Cycle window: `NYASH_MACRO_CYCLE_WINDOW` (default 8)

Constraints
- Pure transform: no external calls (FFI/hostcall) and no global writes.
- Public-only policy for derives: when generating methods like `equals` or `toString`, operate on public fields only.
- Diagnostics: write via `NYASH_MACRO_TRACE=1` (compiler-owned), not via print in user code.

Future Work
- Packaging: macro crates with versioning; integrity checks.
- Capability tokens: opt-in capabilities for limited read-only context (e.g., box names list).
- Attribute-style hooks: `@derive`, `@rewrite`, `@lint` as MacroBox conventions.