Escribir un procesador: del símbolo al fichero

Un procesador de símbolos es, en su forma mínima, una clase con un método que recibe un buscador de símbolos y devuelve una lista. Esa simplicidad es engañosa en los dos sentidos: por un lado, el esqueleto se escribe en cinco minutos y funciona; por otro, la distancia entre ese esqueleto y un procesador que se comporta bien en un proyecto real es considerable, y casi toda esa distancia está en dos asuntos que el ejemplo introductorio de cualquier tutorial omite. El primero es qué hacer cuando algo va mal, porque un procesador que lanza una excepción produce un mensaje ilegible mientras que uno que informa correctamente produce un error de compilación tan bueno como el del propio compilador. El segundo es el modelo de rondas, es decir, el hecho de que el código que tú generas puede a su vez contener anotaciones que alguien debe procesar, y que por tanto el proceso se repite hasta que se estabiliza. Esta lección recorre el camino completo con un procesador que genera funciones de conversión a mapa.

El proveedor y el procesador

KSP no instancia tu procesador directamente: instancia un proveedor, que recibe el entorno de la construcción y decide cómo construir el procesador. Esta indirección parece burocrática pero cumple una función real, porque permite que el procesador reciba por constructor exactamente las piezas que necesita y no un objeto de entorno global, lo cual facilita enormemente probarlo.

class AMapaProcessorProvider : SymbolProcessorProvider {
    override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor =
        AMapaProcessor(
            codeGenerator = environment.codeGenerator,
            logger = environment.logger,
            paquetePorDefecto = environment.options["aMapa.paquete"] ?: "generado",
        )
}

class AMapaProcessor(
    private val codeGenerator: CodeGenerator,
    private val logger: KSPLogger,
    private val paquetePorDefecto: String,
) : SymbolProcessor {
    override fun process(resolver: Resolver): List<KSAnnotated> { /* ... */ return emptyList() }
}

El proveedor se descubre mediante el mecanismo de servicios de la plataforma, así que hay que declararlo en un fichero de recursos cuyo nombre es el de la interfaz y cuyo contenido es el nombre completo de tu clase. Olvidarse de ese fichero produce el síntoma más desconcertante de todos, que es un procesador que compila perfectamente y no se ejecuta jamás.

// modulo del procesador
dependencies {
    implementation("com.google.devtools.ksp:symbol-processing-api:2.2.20-2.0.4")
}
// recurso: META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider
// contenido unico: com.ejemplo.AMapaProcessorProvider

Conviene además que el procesador viva en su propio módulo, separado del módulo de las anotaciones. Quien use tu herramienta necesita las anotaciones en tiempo de compilación normal y el procesador solo como dependencia de procesamiento; mezclarlos arrastra la implementación entera al binario de todos tus usuarios.

Recorrer lo anotado

El buscador de símbolos ofrece una consulta directa por nombre completo de anotación. Lo que devuelve es una secuencia perezosa de elementos anotables, y el primer trabajo del procesador es filtrar los que no son del tipo que espera y rechazarlos con un mensaje claro en lugar de dejar que fallen más adelante con un error de conversión.

Antes de generar nada hay que validar. Un símbolo puede referirse a tipos que todavía no existen porque los generará otro procesador en esta misma construcción; intentar resolverlos ahora daría un tipo erróneo. La llamada de validación comprueba precisamente eso, y los símbolos que no la superan no se descartan: se devuelven al final para que se reintenten en la ronda siguiente.

override fun process(resolver: Resolver): List<KSAnnotated> {
    val simbolos = resolver.getSymbolsWithAnnotation("com.ejemplo.AMapa")
    val (validos, aplazados) = simbolos.partition { it.validate() }

    validos.filterIsInstance<KSClassDeclaration>()
        .filter { comprobarForma(it) }
        .forEach { generarPara(it) }

    validos.filterNot { it is KSClassDeclaration }
        .forEach { logger.error("AMapa solo se aplica a clases", it) }

    return aplazados
}

private fun comprobarForma(clase: KSClassDeclaration): Boolean = when {
    Modifier.DATA !in clase.modifiers -> {
        logger.error("AMapa exige una clase de datos", clase); false
    }
    clase.typeParameters.isNotEmpty() -> {
        logger.error("AMapa no admite clases genericas", clase); false
    }
    else -> true
}

Para recorrer estructuras más profundas conviene usar el visitante en vez de anidar condicionales sobre el tipo de cada nodo. La variante que acumula datos permite ir construyendo el modelo intermedio mientras se baja por el árbol, y evita el patrón de mutar una lista externa desde dentro del recorrido.

Generar el fichero

La escritura pasa siempre por el generador de código, nunca por el sistema de ficheros directamente. La razón es la declaración de dependencias: al crear un fichero se indica de qué fuentes depende su contenido, y con esa información la herramienta sabe qué debe regenerar cuando algo cambia. Un procesador que declara mal sus dependencias produce construcciones incrementales incorrectas, que es el peor tipo de fallo porque solo aparece cuando alguien edita justo el fichero equivocado.

private fun generarPara(clase: KSClassDeclaration) {
    val fuente = clase.containingFile ?: return
    val paquete = clase.packageName.asString()
    val nombre = clase.simpleName.asString()
    val props = clase.getAllProperties()
        .filter { it.hasBackingField }
        .map { it.simpleName.asString() }
        .toList()

    codeGenerator.createNewFile(
        dependencies = Dependencies(aggregating = false, fuente),
        packageName = paquete,
        fileName = nombre + "AMapa",
    ).bufferedWriter().use { out ->
        out.appendLine("package " + paquete)
        out.appendLine()
        out.appendLine("fun " + nombre + ".aMapa(): Map<String, Any?> = mapOf(")
        props.forEach { p -> out.appendLine("    \"" + p + "\" to " + p + ",") }
        out.appendLine(")")
    }
}

La distinción entre agregar y no agregar es la que más errores causa. Un fichero no agregador depende solo de las fuentes indicadas, de modo que cambiar otra clase no lo invalida; es el caso de un fichero generado por cada clase anotada. Un fichero agregador depende de todo el conjunto anotado, porque su contenido resume el conjunto; es el caso de un registro central o un índice. Marcar como no agregador algo que en realidad agrega produce índices desactualizados sin ningún aviso.

flowchart TD
A[Ronda con fuentes iniciales] --> B[process recibe el resolver]
B --> C[Simbolos validos generan ficheros]
B --> D[Simbolos no validados se devuelven]
C --> E[Ficheros generados entran como fuentes]
D --> E
E --> F{Hubo ficheros nuevos}
F -->|Si| B
F -->|No| G[finish y luego onError si procede]

Escribir texto a mano funciona para casos pequeños, pero en cuanto aparecen genéricos, importaciones y nulabilidad conviene usar un constructor de ficheros que gestione las importaciones por ti. La regla es la misma que en cualquier generación de código: concatenar cadenas escala mal, y el primer sitio donde se nota es en los nombres cualificados que colisionan.

Errores y rondas

Un procesador nunca debe comunicar problemas lanzando excepciones. El registro de diagnósticos ofrece cuatro niveles, y el que importa es el de error, porque marca la compilación como fallida y, si le pasas el símbolo como segundo argumento, sitúa el mensaje en el fichero y la línea exactos. Un buen mensaje dice qué regla se ha incumplido y qué hacer, igual que haría el compilador.

El ciclo completo tiene tres momentos. El método principal se ejecuta una vez por ronda mientras se sigan generando ficheros nuevos; el método de finalización se ejecuta una sola vez al terminar bien, y es el sitio natural para emitir ficheros agregados; el método de error se ejecuta si algo falló, y sirve para liberar recursos o dar un diagnóstico final.