Macro authoring API

Macros are compile-time with <name>(...) clauses that splice declarations into the host AST before lowering. Every shipped stdlib macro (see scaffold-macros.md) is written against this API; future project-local macros will use the same surface.

This doc is the authoring reference — what types and helpers the API exposes. For each macro's source-equivalent and intent, see scaffold-macros.md.

Where macros live

The shape of a macro module is the same in both cases. Each macro file default-exports a single defineMacro({ ... }) call.

The entry point

import { defineMacro } from "../../api/index.js";

export default defineMacro({
  name: "<macro-name>",
  target: "aggregate" | "ui" | "context",
  apiVersion: 1,
  description: "<one-line>",
  params: { /* declared parameters, see below */ },
  expand(ctx) {
    // Inspect ctx.target, build AST fragments via factories,
    // return them. The expander splices them into the host's
    // members[] array.
  },
});

defineMacro is an identity function — its only role is to infer the ExpandContext type so ctx.args is typed against the declared params.

target — which host the macro attaches to

The three host kinds:

The expander rejects a macro applied at the wrong target with a validator error pointing at the with clause.

params — typed parameter declarations

params: {
  modules:    { kind: "refList", of: "Module" },
  contexts:   { kind: "refList", of: "BoundedContext", default: [] },
  prefix:     { kind: "string", default: "" },
  audited:    { kind: "bool", default: true },
}

Each value is a ParamType:

ref / refList's of: selects the AST kind the validator will cross-reference the argument against (NamedDeclKind in src/macros/api/define.ts). Accepted values:

Aggregate | Subdomain | BoundedContext | Workflow | ValueObject | EnumDecl
  | Criterion | Policy

Policy resolves the FUNCTION form only (policy Name(): bool = …) — never the anonymous / read-ladder policy { … } block, which has no name to call and is not a boolean gate. It is what lets a macro splice an authorization gate into a body it owns: see crudish(requires: <Policy>) in scaffold-macros.md. Note that requires is admissible as a macro-arg NAME (and only there — MacroArgName in the grammar), so the parameter can be spelled with the same word the gate itself uses.

A user-typed with myMacro(target: NonExistent) errors at parse time with the same "no such X" diagnostic any other reference would.

expand(ctx) — the body

expand({ target, args, origin, invokeMacro }): MemberTypeOf[T][]

The returned array's element type is enforced at the TS level: target: "aggregate" requires AggregateMember[], "ui" requires UiMember[], etc.

Factory functions

AST construction must go through the factories so synthesised nodes carry origin metadata. The full surface is src/macros/api/:

factories.ts — domain-side AST nodes

ui-factories.ts — UI-side AST nodes

Inspection helpers

When macros run

Macro expansion is AST phase ②, between parse and scope/link (see technical.md). Implications:

• Macros see the raw AST, before name resolution or type inference. References inside a with X(...) arg are resolved by the validator before expansion via the param kind (ref/refList), so target and args are already pointing at concrete AST nodes.
• Synthesised members participate in scope computation, so other declarations can reference them by name.
• Macros do NOT see IR. A macro that needs to know an aggregate's fields inspects target.members (AST), not AggregateIR.fields. Use the inspection helpers (targetFields, etc.) for this.

Composability

Composer macros call leaf macros via invokeMacro. The rule is outside-in only:

• A context macro can call an aggregate macro against each child aggregate (softDeleteByDefault calls softDelete per aggregate).
• A ui macro can call other ui macros (scaffold calls scaffoldSubdomain).
• An aggregate macro cannot call a context macro — the expander's splice-time descendant check rejects it.

The factories tag each returned node with the invocation's target, not the caller's. So when softDeleteByDefault runs at context scope and calls softDelete against a child aggregate, the returned AggregateMember[] is spliced into that aggregate, not the context.

Worked example

A trivial trait macro that adds a tag: string field to every host aggregate:

import {
  defineMacro,
  field,
  primType,
} from "../../api/index.js";

export default defineMacro({
  name: "tagged",
  target: "aggregate",
  apiVersion: 1,
  description: "Adds a `tag: string` field to the host aggregate.",
  expand({ target }) {
    if (target.members.some(m => m.$type === "Property" && m.name === "tag")) {
      return []; // idempotent — don't double-add
    }
    return [field("tag", primType("string"))];
  },
});

Usage:

aggregate Order with tagged {
  total: int
}

…lowers to:

aggregate Order {
  total: int
  tag: string                          // <- spliced by `tagged`
}

Cross-references

• scaffold-macros.md — the stdlib macros this API ships. Read those for examples of every helper in use.
• capabilities.md — the filter / stamp / implements surface that contextFilter / contextStamp / implementsCapability factories emit.
• technical.md — phase ② macro expansion in the compiler pipeline.
• language.md — the with <macro>(...) clause surface (where macros are invoked).