Errores de macros y cómo leerlos

El primer error de macro que te encuentras es desconcertante por una razón concreta: no habla de nada que hayas escrito. Dice que tu tipo no conforma un protocolo que la macro debía darle, o que no encuentra una implementación externa cuyo nombre nunca viste, o que un tipo no existe cuando está a tres líneas de distancia. La causa de ese desconcierto es estructural: cuando la generación falla, el compilador no puede describir la ausencia de lo que iba a generarse, así que informa de las consecuencias río abajo. Leer bien esos mensajes consiste en aprender a remontar la corriente, y hay un puñado pequeño de causas reales detrás de casi todos ellos.

Dos familias de fallo, dos lecturas distintas

Antes de leer un mensaje, clasifícalo. Si la macro no llegó a expandirse, el problema es del entorno de compilación: el plugin no se construyó, no está autorizado, o la versión de la biblioteca de sintaxis no casa con la del compilador. Los mensajes de esta familia mencionan implementaciones externas, plugins o objetivos que deben habilitarse, y ninguno de ellos se arregla tocando tu código.

Si la macro expandió pero el resultado no compila, el problema es de tu fuente: la macro generó lo que sabe generar y ese código chocó con lo que tú escribiste. Los mensajes de esta familia hablan de conformidades, de tipos que faltan o de requisitos no satisfechos, y su rasgo distintivo es que señalan la línea del atributo de la macro aunque la causa esté dentro del cuerpo del tipo. Ese desplazamiento no es un defecto del compilador, es la consecuencia inevitable de que el código culpable pertenezca a un búfer generado.

Hay una tercera situación que conviene descartar antes que ninguna otra porque se disfraza de las dos anteriores: la macro expandió correctamente y el error es tuyo pero no tiene nada que ver con macros. Un error de tipo dentro de un Reduce, una dependencia mal declarada o un caso de switch sin cubrir producen mensajes normales que sencillamente aparecen en un archivo lleno de atributos, y el sesgo de atribución hace que sospeches de la macro. La señal para distinguirla es simple: si el mensaje cita una línea que tú escribiste y describe un problema que entiendes, no es un problema de macro por mucho que haya una macro cerca.

Catálogo de diagnósticos frecuentes

Los mensajes que siguen cubren la abrumadora mayoría de las incidencias reales con la macro de TCA. Interesa memorizar la columna del medio, porque es la que ningún mensaje dice.

Dos entradas merecen comentario. La del tiempo de verificación aparece cuando el body acumula muchos operadores encadenados y el result builder genera un árbol de sobrecargas demasiado grande; la solución nunca es simplificar la lógica sino romper el body en piezas con tipo explícito, típicamente propiedades que devuelven some ReducerOf<Self>. Y la del miembro dinámico se da casi siempre en enums que no son acciones de una feature: recuerda que la macro solo anota el enum llamado Action del tipo que decora, y ninguno más.

// Romper un body demasiado grande en piezas con tipo anotado
@Reducer
struct Grande {
  @ObservableState struct State: Equatable { var a = 0 }
  enum Action { case algo }

  var body: some ReducerOf<Self> {
    nucleo
      .ifLet(\.$hoja, action: \.hoja) { Hoja() }
  }

  private var nucleo: some ReducerOf<Self> {
    Reduce { state, action in
      return .none
    }
  }
}

Cuando la macro no expande

Esta es la familia que más tiempo hace perder porque invita a modificar código que estaba bien. El orden de descarte importa y conviene seguirlo sin saltarse pasos.

Hay dos comprobaciones adicionales que cierran los casos restantes. La primera es trivial y sorprendentemente común: falta la importación de la biblioteca, y sin ella el atributo de la macro no se resuelve. La segunda es que la primera compilación de un proyecto con macros construye la biblioteca de sintaxis entera y tarda varios minutos, así que un editor que parece colgado la primera vez suele estar trabajando, no roto.

flowchart TD
A[Error relacionado con la macro] --> B[Intenta expandir el panel]
B --> C[Panel coherente igual a fallo en tu fuente]
B --> D[Panel vacio igual a fallo del entorno]
C --> E[Revisa nombres State y Action]
C --> F[Revisa body o reduce]
C --> G[Revisa coordenadas de Scope]
D --> H[Autoriza el plugin]
D --> I[Limpia caches y reconstruye]
D --> J[Revisa versiones y la importacion]

El procedimiento de descarte

La tentación ante un error opaco es cambiar cosas hasta que compile, y esa estrategia funciona lo bastante a menudo como para consolidarse y lo bastante poco como para arruinarte una tarde. La alternativa es un procedimiento fijo, siempre el mismo, que en cinco pasos agota el espacio de causas sin depender de la intuición.

El primer paso es aislar la primera línea de error real. Un fallo de macro produce cascadas de diez o quince mensajes de los cuales solo el primero tiene información; los demás son consecuencias de que el tipo quedó mal formado. Filtra la lista y trabaja únicamente sobre el diagnóstico más temprano en orden de archivo y línea.

El segundo es intentar la expansión, que como vimos reparte el problema en las dos familias. El tercero, si el fallo es de tu fuente, es verificar las cuatro expectativas de la macro en este orden literal: existe un tipo anidado llamado State, existe otro llamado Action, existe exactamente uno entre body y reduce, y la importación de la biblioteca está presente. Ese orden no es arbitrario: va de la causa más frecuente a la menos.

// Caso mínimo de descarte: si esto compila, el entorno está sano
@Reducer
struct Sonda {
  @ObservableState
  struct State: Equatable { var x = 0 }
  enum Action { case toco }
  var body: some ReducerOf<Self> {
    Reduce { state, action in
      state.x += 1
      return .none
    }
  }
}

El cuarto paso es la sonda: pega ese fragmento mínimo en un archivo nuevo del mismo objetivo. Si compila, el entorno está sano y la causa está en tu feature; si no compila, la causa está en el entorno y ningún cambio en tu feature la arreglará. Es la comprobación más barata que existe y descarta la mitad del espacio de búsqueda en un ciclo de compilación.

El quinto es la bisección: si la sonda compila y tu feature no, copia la sonda y ve trasplantando piezas de tu feature de una en una, empezando por el estado, siguiendo por las acciones y terminando por el body. La pieza que rompe la sonda es la causa, sin margen de duda y sin necesidad de haber entendido el mensaje.