Las macros de Swift: qué generan y cómo inspeccionarlas

Durante años, cuando una arquitectura de Swift exigía andamiaje repetitivo, había tres salidas y ninguna buena: escribirlo a mano en cada feature, generarlo con un script externo que había que recordar ejecutar, o esquivarlo con reflexión en tiempo de ejecución, pagándolo en seguridad de tipos. Swift 5.9 abrió una cuarta puerta al permitir que el compilador ejecute, durante la propia compilación, programas que producen código fuente. TCA se subió a esa puerta antes que casi nadie, y por eso hoy una feature entera se declara con @Reducer sobre una struct y @ObservableState sobre su estado. La tentación es tratar esas anotaciones como magia y seguir adelante. Es un mal negocio: casi todos los errores desconcertantes que da TCA vienen de la expansión, y esa expansión se puede leer. Esta lección enseña qué escribe cada macro, por qué no puede mentirte, y cómo poner el código generado delante de los ojos.

Qué es una macro y en qué momento actúa

Una macro de Swift es un programa aparte —un ejecutable que el gestor de paquetes compila antes que tu código— que recibe un fragmento de sintaxis ya analizado y devuelve más sintaxis. El compilador analiza tu archivo, encuentra la anotación, lanza el proceso de la macro pasándole el árbol sintáctico del tipo que anotaste, recibe declaraciones nuevas, las inserta y solo entonces comprueba tipos sobre el resultado completo.

Cuatro propiedades separan esto de un #define de C, y las cuatro importan. Primera: la macro opera sobre sintaxis analizada, no sobre texto, así que no puede producir algo que no sea Swift sintácticamente válido. Segunda: es aditiva, solo puede añadir declaraciones y accesores, jamás borrar ni reescribir lo que escribiste; el código que lees sigue siendo el código que hay. Tercera: es higiénica, sus nombres internos no colisionan con los tuyos, y todo lo que introduce en tu ámbito tiene que declararlo en su definición. Y cuarta: el resultado pasa por el verificador de tipos como cualquier otro código, de modo que una macro no puede colar algo que no compilaría si lo hubieras escrito tú.

// Declaración de una macro: la firma vive en tu módulo,
// la implementación vive en un plugin del compilador.
@attached(member, names: named(State), named(Action))
@attached(extension, conformances: Reducer)
public macro Reducer() = #externalMacro(
  module: "ComposableArchitectureMacros",
  type: "ReducerMacro"
)

Las macros se dividen en dos familias: las autónomas, que se invocan con almohadilla —#Preview, #externalMacro— y aparecen donde va una expresión o una declaración; y las adjuntas, que se escriben con arroba delante de una declaración y la amplían. Las adjuntas se clasifican por rol, y el rol determina qué puede añadir y dónde.

TCA los usa casi todos, y a menudo varios a la vez sobre la misma anotación.

Los roles que usa TCA

@Reducer es la más ambiciosa y combina varios roles a la vez. Sobre una struct de feature añade la conformidad al protocolo Reducer, sintetiza los typealias de State y Action a partir de tus tipos anidados, aplica @CasePathable y @dynamicMemberLookup al enum de acciones para habilitar los key paths de caso, envuelve tu body con @ReducerBuilder, y de paso emite diagnósticos propios cuando detecta errores frecuentes, como implementar body y reduce a la vez. Aplicada a un enum de destinos de navegación, hace algo aún más vistoso: genera los enums anidados State y Action con un caso por destino y su reducer compuesto.

@Reducer
struct Contador {
  @ObservableState
  struct State: Equatable { var cuenta = 0 }
  enum Action { case incrementar, decrementar }
  var body: some ReducerOf<Self> {
    Reduce { state, action in
      switch action {
      case .incrementar: state.cuenta += 1; return .none
      case .decrementar: state.cuenta -= 1; return .none
      }
    }
  }
}

// Lo que la expansión añade, en esencia:
// extension Contador: ComposableArchitecture.Reducer {}
// @CasePathable @dynamicMemberLookup enum Action { ... }
// typealias State = ...  /  typealias Action = ...

@ObservableState juega en otro registro: usa el rol accessor para reescribir el acceso a cada propiedad almacenada del estado, de modo que leerla registre una dependencia de observación y escribirla notifique el cambio. Para ello introduce un registrador y un identificador internos y añade la conformidad al protocolo de observación.

@ObservableState
struct State: Equatable {
  var cuenta = 0
}

// Expansión, en esencia: cada propiedad deja de ser almacenada
// y pasa a mediar sus accesos por un registrador interno.
// var cuenta: Int {
//   get { _$observationRegistrar.access(self, keyPath: \.cuenta); return _cuenta }
//   set { _$observationRegistrar.mutate(self, keyPath: \.cuenta, &_cuenta, newValue) }
// }

Ese es el mecanismo que permite a SwiftUI redibujar solo las vistas que leyeron el campo que cambió, en lugar de invalidar la pantalla entera; sin macro tendrías que escribir a mano un par de accesores por propiedad, y bastaría olvidar uno para que una vista dejara de actualizarse sin ningún error visible.

@DependencyClient, de la librería hermana de dependencias, ilustra un tercer estilo de aportación. Aplicada a una struct de closures, sintetiza un inicializador con cada closure como argumento con valor por defecto y rellena las que nadie proporcione con implementaciones que reportan un fallo al ser llamadas. El resultado es que olvidar inyectar una dependencia en un test deja de producir un comportamiento silencioso y produce un mensaje que nombra la closure exacta que faltaba.

Poner la expansión delante de los ojos

Nada de esto es opaco, y tratarlo como opaco es el error que alarga las depuraciones. Hay tres vías para leer lo que la macro escribió.

En Xcode, pulsa con el botón derecho sobre la anotación y elige expandir la macro: se abre un panel con el código generado, y desde ahí puedes saltar a él como a cualquier otro archivo. Desde la línea de comandos, el compilador vuelca todas las expansiones en la salida de la compilación.

# Volcar el codigo que generan todas las macros del paquete
swift build -Xswiftc -dump-macro-expansions 2>&1 | tee expansiones.txt

# Aislar lo generado para una feature concreta
grep -n -A 30 "Contador" expansiones.txt

Guardar ese volcado tiene un uso que se agradece al actualizar: comparar el archivo de dos versiones de TCA muestra exactamente qué cambió en el andamiaje generado, que suele explicar avisos nuevos mucho mejor que las notas de la versión. Y en el depurador, el código expandido aparece como un búfer con nombre prefijado por @__swiftmacro_, en el que se puede entrar paso a paso y poner puntos de interrupción como en cualquier otro archivo, de modo que ni siquiera en ejecución el código generado es una caja cerrada.

El coste, los límites y por qué son deliberados

Las macros no salen gratis. El plugin es un ejecutable que hay que compilar antes que tu módulo, se lanza como proceso separado y en Xcode corre dentro de una caja de arena, así que una compilación limpia paga ese arranque y, en un proyecto con muchas features anotadas, la expansión se nota en los tiempos. De ahí también el aviso que Xcode muestra la primera vez que añades un paquete con macros y te pide confirmar que confías en él: una macro es código de terceros que se ejecuta en tu máquina durante la compilación, y ese consentimiento explícito es la contrapartida razonable a semejante poder. La contrapartida es que ese trabajo ocurre una vez por compilación y no deja ni rastro en ejecución: el binario contiene el código expandido y nada más, sin reflexión ni indirecciones.

Hay además un coste ergonómico que conviene anticipar: los diagnósticos. Cuando un error se origina en código generado, el mensaje puede señalar una declaración que tú no escribiste, y en los primeros meses eso desorienta. La cura es la costumbre de la sección anterior —expandir antes de conjeturar— y una segunda precaución práctica: mantener el estado y las acciones tan simples como el dominio permita, porque cuanto más exótico es lo que anotas, más lejos cae el diagnóstico de la línea que lo provocó.

Los límites son igual de importantes. Una macro no puede modificar ni eliminar el código existente, no puede ver otros archivos de tu módulo —solo recibe la sintaxis de lo que anota, así que no puede razonar sobre tipos declarados en otra parte— y no puede saltarse la comprobación de tipos posterior. Estas restricciones parecen mezquinas hasta que las lees como lo que son: garantías. Un sistema donde el código generado pudiera reescribir el tuyo o depender de todo el módulo sería imposible de auditar y de reproducir. Aquí, en cambio, la relación entre lo que escribes y lo que se compila es una función determinista que puedes inspeccionar cuando quieras.

flowchart LR
SRC[tu codigo anotado] --> PARSE[analisis sintactico]
PARSE --> PLUG[plugin de macro en proceso aparte]
PLUG --> EXP[sintaxis generada solo aditiva]
EXP --> MERGE[fusion con tu arbol sintactico]
MERGE --> TC[verificacion de tipos del conjunto]
TC --> BIN[binario sin rastro de la macro]
style PLUG fill:#cba6f7,color:#11111b
style TC fill:#a6e3a1,color:#11111b