SwiftSyntax: manipular el árbol y escribir tu primera macro

Una macro es una función de sintaxis a sintaxis, así que todo el trabajo real ocurre en la biblioteca que representa esa sintaxis. SwiftSyntax es el parser oficial de Swift expuesto como paquete: el mismo que usa el compilador desde que se reescribió en Swift, con una propiedad que casi ningún parser tiene y que aquí resulta decisiva. Su árbol conserva todo lo que había en el archivo original —cada espacio, cada comentario, cada salto de línea— de modo que imprimir el árbol devuelve el fuente byte por byte. Esa fidelidad total es lo que permite que una herramienta reescriba un fragmento sin destrozar el formato del resto, y es también la razón de que la biblioteca tenga tantos tipos y tanta ceremonia. Aprender macros es, en la práctica, aprender a moverse por ese árbol con soltura.

El árbol: nodos, tokens y trivia

Todo en SwiftSyntax es un valor inmutable. Modificar un nodo devuelve un árbol nuevo que comparte con el anterior todo lo que no cambió, igual que una estructura persistente; no hay mutación en sitio y no hay riesgo de dejar un árbol a medias. Los tipos son estrictos y numerosos: una declaración de estructura es un StructDeclSyntax, un caso de enumeración es un EnumCaseDeclSyntax, una llamada a función es un FunctionCallExprSyntax. El tipo borrado Syntax sirve para hablar de cualquiera de ellos, y el protocolo SyntaxProtocol reúne lo común.

En las hojas están los TokenSyntax: las palabras clave, los identificadores, la puntuación. Y colgando de cada token está la trivia, todo lo que no significa nada para el compilador pero sí para quien lee: espacios, tabuladores, saltos de línea y comentarios. Cada token lleva la trivia de delante y la de detrás, y por eso el árbol puede reimprimirse sin pérdida alguna.

let arbol = Parser.parse(source: "let x = 1  // nota")
print(arbol.description == "let x = 1  // nota")   // true

Esa igualdad es la garantía de fidelidad, y conviene interiorizar lo que implica para una macro: si construyes un nodo sin trivia, el resultado se imprimirá pegado. Los espacios y saltos de línea que ves en un código generado legible están ahí porque alguien los puso.

Navegar y consultar

Un árbol se recorre por dos vías. La directa consiste en pedir hijos por nombre y convertir el tipo con as, que devuelve un opcional y por tanto obliga a decidir qué pasa si no encaja.

guard let enumDecl = declaration.as(EnumDeclSyntax.self) else { return [] }
let casos = enumDecl.memberBlock.members
    .compactMap { $0.decl.as(EnumCaseDeclSyntax.self) }
    .flatMap { $0.elements }

Fíjate en la forma del camino: de la declaración al memberBlock, de ahí a members, que es una colección de MemberBlockItemSyntax, y de cada elemento a su decl, que es genérica y hay que convertir. Es verboso a propósito. Cada paso es un tipo distinto porque la gramática de Swift distingue esos niveles, y la verbosidad compra que el compilador te avise si el camino no existe.

La segunda vía es el recorrido genérico con SyntaxVisitor y su primo mutable SyntaxRewriter, que heredan de una clase con un método por cada tipo de nodo y sirven cuando no sabes dónde está lo que buscas. Y para las macros adjuntas hay un protocolo que conviene conocer: DeclGroupSyntax unifica todo lo que tiene un bloque de miembros —struct, class, enum, actor, extension, protocol—, y la firma de MemberMacro recibe precisamente un some DeclGroupSyntax, de modo que puedes leer los miembros sin saber aún qué clase de tipo te ha tocado.

Construir sintaxis nueva

Aquí es donde SwiftSyntaxBuilder cambia la vida. Los nodos son construibles por interpolación de cadenas, de manera que puedes escribir el código generado casi como lo escribirías a mano:

let nombre = "volumen"

// raw inserta codigo: el identificador aparece desnudo
let a: DeclSyntax = "var \(raw: nombre)Doble: Int { \(raw: nombre) * 2 }"

// literal inserta un dato ya escapado, con sus comillas
let b: DeclSyntax = "let etiqueta = \(literal: nombre)"

La distinción entre esas dos formas de interpolar es la fuente de errores más común y merece grabarse. raw inserta el texto tal cual y se usa para identificadores, tipos y fragmentos de código. literal inserta el valor convertido en un literal de Swift, con sus comillas y sus escapes, y se usa cuando quieres que en el código generado aparezca un dato. Y si interpolas un nodo de sintaxis sin adorno, se inserta su código fuente, que suele ser lo que quieres al reenviar un argumento recibido.

Existe también la vía estructurada, construyendo los nodos con sus inicializadores y con los resultBuilder de la biblioteca. Es más segura y muchísimo más verbosa; en la práctica se reserva para las transformaciones donde hay que preservar trivia con precisión, y la interpolación se lleva el resto.

flowchart TB
ent[Entrada la declaracion anotada] --> val[Validar la forma con as y guard]
val -->|no encaja| diag[Emitir diagnostico con context]
val -->|encaja| ext[Extraer los datos del arbol]
ext --> con[Construir DeclSyntax por interpolacion]
con --> sal[Devolver el array de declaraciones]
style ent fill:#cba6f7,color:#11111b
style diag fill:#f38ba8,color:#11111b
style sal fill:#a6e3a1,color:#11111b

Una macro completa

Vamos a escribir una macro adjunta que, dado un enum, añada una propiedad booleana por cada caso. Es el ejemplo canónico porque necesita leer el árbol, derivar nombres de los datos y validar la entrada. Primero la declaración, en el módulo público:

@attached(member, names: arbitrary)
public macro DeteccionDeCasos() =
    #externalMacro(module: "MisMacrosMacros", type: "DeteccionDeCasosMacro")

El arbitrary es obligado aquí: los nombres generados dependen de los casos del enum, así que no hay forma de anunciarlos. Ahora la implementación:

import SwiftSyntax
import SwiftSyntaxMacros
import SwiftDiagnostics

public struct DeteccionDeCasosMacro: MemberMacro {
    public static func expansion(
        of node: AttributeSyntax,
        providingMembersOf declaration: some DeclGroupSyntax,
        in context: some MacroExpansionContext
    ) throws -> [DeclSyntax] {

        guard let enumDecl = declaration.as(EnumDeclSyntax.self) else {
            context.diagnose(Diagnostic(node: node, message: MensajeMacro.soloEnums))
            return []
        }

        let elementos = enumDecl.memberBlock.members
            .compactMap { $0.decl.as(EnumCaseDeclSyntax.self) }
            .flatMap { $0.elements }

        return elementos.map { elemento in
            let caso = elemento.name.text
            let capitalizado = caso.prefix(1).uppercased() + caso.dropFirst()
            return """
                var es\(raw: capitalizado): Bool {
                    if case .\(raw: caso) = self { return true }
                    return false
                }
                """
        }
    }
}

Y el resultado, desde el lado de quien la usa:

@DeteccionDeCasos
enum Estado { case cargando, listo, fallo }

// Genera esCargando, esListo y esFallo
if pantalla.estado.esCargando { mostrarSpinner() }

Queda el detalle que separa una macro de juguete de una publicable: los diagnósticos. Lanzar un error desde expansion produce un mensaje genérico sin posición útil; lo correcto es emitirlo con context.diagnose sobre el nodo exacto que falla, con severidad y, si procede, con una corrección automática.

enum MensajeMacro: String, DiagnosticMessage {
    case soloEnums
    var message: String { "DeteccionDeCasos solo puede aplicarse a un enum" }
    var severity: DiagnosticSeverity { .error }
    var diagnosticID: MessageID { MessageID(domain: "MisMacros", id: rawValue) }
}

Con eso, aplicar la macro a un struct produce un error subrayado en el atributo, con tu texto, exactamente como lo haría el compilador. Devolver un array vacío después de diagnosticar es lo habitual: evita una cascada de errores derivados en el código que esperaba los miembros.