API del compilador de TypeScript: Dominando la manipulación del AST y la transformación de código

La API del compilador de TypeScript proporciona una interfaz poderosa para analizar, manipular y generar código TypeScript y JavaScript. En su corazón se encuentra el Árbol de Sintaxis Abstracta (AST), una representación estructurada de su código fuente. Comprender cómo trabajar con el AST desbloquea capacidades para construir herramientas avanzadas, como linters, formateadores de código, analizadores estáticos y generadores de código personalizados.

¿Qué es la API del compilador de TypeScript?

La API del compilador de TypeScript es un conjunto de interfaces y funciones de TypeScript que exponen el funcionamiento interno del compilador de TypeScript. Permite a los desarrolladores interactuar programáticamente con el proceso de compilación, yendo más allá de la simple compilación de código. Puede usarla para:

• Analizar código: Inspeccionar la estructura del código, identificar posibles problemas y extraer información semántica.
• Transformar código: Modificar el código existente, agregar nuevas características o refactorizar el código automáticamente.
• Generar código: Crear nuevo código desde cero basado en plantillas u otra entrada.

Esta API es esencial para construir herramientas de desarrollo sofisticadas que mejoran la calidad del código, automatizan tareas repetitivas y mejoran la productividad del desarrollador.

Comprensión del Árbol de Sintaxis Abstracta (AST)

El AST es una representación en forma de árbol de la estructura de su código. Cada nodo del árbol representa una construcción sintáctica, como una declaración de variable, una llamada a una función o una instrucción de flujo de control. La API del compilador de TypeScript proporciona herramientas para recorrer el AST, inspeccionar sus nodos y modificarlos.

Considere este simple código TypeScript:

function greet(name: string): string {
  return `Hola, ${name}!`;
}

console.log(greet("Mundo"));

El AST para este código representaría la declaración de la función, la instrucción de retorno, el literal de plantilla, la llamada a console.log y otros elementos del código. Visualizar el AST puede ser un desafío, pero herramientas como AST explorer (astexplorer.net) pueden ayudar. Estas herramientas le permiten ingresar código y ver su AST correspondiente en un formato fácil de usar. Usar AST Explorer le ayudará a comprender el tipo de estructura de código que estará manipulando.

Tipos clave de nodos AST

La API del compilador de TypeScript define varios tipos de nodos AST, cada uno de los cuales representa una construcción sintáctica diferente. Aquí hay algunos tipos de nodos comunes:

• SourceFile: Representa un archivo TypeScript completo.
• FunctionDeclaration: Representa la definición de una función.
• VariableDeclaration: Representa una declaración de variable.
• Identifier: Representa un identificador (por ejemplo, nombre de variable, nombre de función).
• StringLiteral: Representa un literal de cadena.
• CallExpression: Representa una llamada a una función.
• ReturnStatement: Representa una instrucción de retorno.

Cada tipo de nodo tiene propiedades que proporcionan información sobre el elemento de código correspondiente. Por ejemplo, un nodo `FunctionDeclaration` podría tener propiedades para su nombre, parámetros, tipo de retorno y cuerpo.

Primeros pasos con la API del compilador

Para comenzar a usar la API del compilador, necesitará instalar TypeScript y tener una comprensión básica de la sintaxis de TypeScript. Aquí hay un ejemplo simple que demuestra cómo leer un archivo TypeScript e imprimir su AST:

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "ejemplo.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015, // Versión de ECMAScript de destino
  true // SetParentNodes: true para retener referencias parentales en el AST
);

function printAST(node: ts.Node, indent = 0) {
  const indentStr = "  ".repeat(indent);
  console.log(`${indentStr}${ts.SyntaxKind[node.kind]}`);

  node.forEachChild(child => printAST(child, indent + 1));
}

printAST(sourceFile);

Explicación:

1. Importar módulos: Importa el módulo `typescript` y el módulo `fs` para las operaciones del sistema de archivos.
2. Leer archivo fuente: Lee el contenido de un archivo TypeScript llamado `ejemplo.ts`. Necesitará crear un archivo `ejemplo.ts` para que esto funcione.
3. Crear SourceFile: Crea un objeto `SourceFile`, que representa la raíz del AST. La función `ts.createSourceFile` analiza el código fuente y genera el AST.
4. Imprimir AST: Define una función recursiva `printAST` que recorre el AST e imprime el tipo de cada nodo.
5. Llamar a printAST: Llama a `printAST` para comenzar a imprimir el AST desde el nodo raíz `SourceFile`.

Para ejecutar este código, guárdelo como un archivo `.ts` (por ejemplo, `ast-ejemplo.ts`), cree un archivo `ejemplo.ts` con algún código TypeScript y luego compile y ejecute el código:

tsc ast-ejemplo.ts
node ast-ejemplo.js

Esto imprimirá el AST de su archivo `ejemplo.ts` en la consola. La salida mostrará la jerarquía de nodos y sus tipos. Por ejemplo, podría mostrar `FunctionDeclaration`, `Identifier`, `Block` y otros tipos de nodos.

Recorrido del AST

La API del compilador proporciona varias formas de recorrer el AST. La más simple es usar el método `forEachChild`, como se muestra en el ejemplo anterior. Este método visita cada nodo hijo de un nodo dado.

Para escenarios de recorrido más complejos, puede usar un patrón `Visitor`. Un visitante es un objeto que define métodos para ser llamados para tipos de nodos específicos. Esto le permite personalizar el proceso de recorrido y realizar acciones basadas en el tipo de nodo.

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "ejemplo.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015,
  true
);

class IdentifierVisitor {
  visit(node: ts.Node) {
    if (ts.isIdentifier(node)) {
      console.log(`Identificador encontrado: ${node.text}`);
    }

    ts.forEachChild(node, n => this.visit(n));
  }
}

const visitor = new IdentifierVisitor();
visitor.visit(sourceFile);

Explicación:

1. Clase IdentifierVisitor: Define una clase `IdentifierVisitor` con un método `visit`.
2. Método Visit: El método `visit` verifica si el nodo actual es un `Identifier`. Si es así, imprime el texto del identificador. Luego, llama recursivamente a `ts.forEachChild` para visitar los nodos secundarios.
3. Crear Visitante: Crea una instancia del `IdentifierVisitor`.
4. Iniciar recorrido: Llama al método `visit` en el `SourceFile` para iniciar el recorrido.

Este ejemplo demuestra cómo encontrar todos los identificadores en el AST. Puede adaptar este patrón para encontrar otros tipos de nodos y realizar diferentes acciones.

Transformación del AST

El verdadero poder de la API del compilador reside en su capacidad para transformar el AST. Puede modificar el AST para cambiar la estructura y el comportamiento de su código. Esta es la base de las herramientas de refactorización de código, los generadores de código y otras herramientas avanzadas.

Para transformar el AST, deberá usar la función `ts.transform`. Esta función toma un `SourceFile` y una lista de funciones `TransformerFactory`. Un `TransformerFactory` es una función que toma un `TransformationContext` y devuelve una función `Transformer`. La función `Transformer` es responsable de visitar y transformar nodos en el AST.

Aquí hay un ejemplo simple que demuestra cómo agregar un comentario al comienzo de un archivo TypeScript:

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "ejemplo.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015,
  true
);

const transformerFactory: ts.TransformerFactory<ts.SourceFile> = context => {
  return transformer => {
    return node => {
      if (ts.isSourceFile(node)) {
        // Crear un comentario inicial
        const comment = ts.addSyntheticLeadingComment(
          node,
          ts.SyntaxKind.MultiLineCommentTrivia,
          " Este archivo se transformó automáticamente ",
          true // hasTrailingNewLine
        );

        return node;
      }

      return node;
    };
  };
};

const { transformed } = ts.transform(sourceFile, [transformerFactory]);

const printer = ts.createPrinter({
  newLine: ts.NewLineKind.LineFeed
});

const result = printer.printFile(transformed[0]);

fs.writeFileSync("ejemplo.transformed.ts", result);

Explicación:

1. TransformerFactory: Define una función `TransformerFactory` que devuelve una función `Transformer`.
2. Transformer: La función `Transformer` verifica si el nodo actual es un `SourceFile`. Si es así, agrega un comentario inicial al nodo usando `ts.addSyntheticLeadingComment`.
3. ts.transform: Llama a `ts.transform` para aplicar la transformación al `SourceFile`.
4. Impresora: Crea un objeto `Printer` para generar código a partir del AST transformado.
5. Imprimir y escribir: Imprime el código transformado y lo escribe en un nuevo archivo llamado `ejemplo.transformed.ts`.

Este ejemplo demuestra una transformación simple, pero puede usar el mismo patrón para realizar transformaciones más complejas, como la refactorización de código, la adición de declaraciones de registro o la generación de documentación.

Técnicas de transformación avanzadas

Aquí hay algunas técnicas de transformación avanzadas que puede usar con la API del compilador:

• Creación de nuevos nodos: Use las funciones `ts.createXXX` para crear nuevos nodos AST. Por ejemplo, `ts.createVariableDeclaration` crea un nuevo nodo de declaración de variable.
• Reemplazo de nodos: Reemplace los nodos existentes con nuevos nodos usando la función `ts.visitEachChild`.
• Agregar nodos: Agregue nuevos nodos al AST usando las funciones `ts.updateXXX`. Por ejemplo, `ts.updateBlock` actualiza una instrucción de bloque con nuevas instrucciones.
• Eliminación de nodos: Elimine nodos del AST devolviendo `undefined` de la función de transformación.

Generación de código

Después de transformar el AST, deberá generar código a partir de él. La API del compilador proporciona un objeto `Printer` para este propósito. El `Printer` toma un AST y genera una representación de cadena del código.

La función `ts.createPrinter` crea un objeto `Printer`. Puede configurar la impresora con varias opciones, como el carácter de nueva línea a usar y si se deben emitir comentarios.

El método `printer.printFile` toma un `SourceFile` y devuelve una representación de cadena del código. Luego puede escribir esta cadena en un archivo.

Aplicaciones prácticas de la API del compilador

La API del compilador de TypeScript tiene numerosas aplicaciones prácticas en el desarrollo de software. Aquí hay algunos ejemplos:

• Linters: Construya linters personalizados para hacer cumplir los estándares de codificación e identificar posibles problemas en su código.
• Formateadores de código: Cree formateadores de código para formatear automáticamente su código de acuerdo con una guía de estilo específica.
• Analizadores estáticos: Desarrolle analizadores estáticos para detectar errores, vulnerabilidades de seguridad y cuellos de botella de rendimiento en su código.
• Generadores de código: Genere código a partir de plantillas u otra entrada, automatizando tareas repetitivas y reduciendo el código repetitivo. Por ejemplo, generar clientes de API o esquemas de bases de datos a partir de un archivo de descripción.
• Herramientas de refactorización: Cree herramientas de refactorización para renombrar variables automáticamente, extraer funciones o mover código entre archivos.
• Automatización de la internacionalización (i18n): Extraiga automáticamente cadenas traducibles de su código TypeScript y genere archivos de localización para diferentes idiomas. Por ejemplo, una herramienta podría escanear el código en busca de cadenas que se pasan a una función `translate()` y agregarlas automáticamente a un archivo de recursos de traducción.

Ejemplo: Construcción de un Linter simple

Creemos un linter simple que compruebe si hay variables no utilizadas en el código TypeScript. Este linter identificará las variables que se declaran pero nunca se usan.

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "ejemplo.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015,
  true
);

function findUnusedVariables(sourceFile: ts.SourceFile) {
  const usedVariables = new Set<string>();

  function visit(node: ts.Node) {
    if (ts.isIdentifier(node)) {
      usedVariables.add(node.text);
    }

    ts.forEachChild(node, visit);
  }

  visit(sourceFile);

  const unusedVariables: string[] = [];

  function checkVariableDeclaration(node: ts.Node) {
    if (ts.isVariableDeclaration(node) && node.name && ts.isIdentifier(node.name)) {
      const variableName = node.name.text;
      if (!usedVariables.has(variableName)) {
        unusedVariables.push(variableName);
      }
    }

    ts.forEachChild(node, checkVariableDeclaration);
  }

  checkVariableDeclaration(sourceFile);

  return unusedVariables;
}

const unusedVariables = findUnusedVariables(sourceFile);

if (unusedVariables.length > 0) {
  console.log("Variables no utilizadas:");
  unusedVariables.forEach(variable => console.log(`- ${variable}`));
} else {
  console.log("No se encontraron variables no utilizadas.");
}

Explicación:

1. Función findUnusedVariables: Define una función `findUnusedVariables` que toma un `SourceFile` como entrada.
2. Conjunto usedVariables: Crea un `Set` para almacenar los nombres de las variables utilizadas.
3. Función visit: Define una función recursiva `visit` que recorre el AST y agrega los nombres de todos los identificadores al conjunto `usedVariables`.
4. Función checkVariableDeclaration: Define una función recursiva `checkVariableDeclaration` que comprueba si una declaración de variable no se utiliza. Si es así, agrega el nombre de la variable a la matriz `unusedVariables`.
5. Retorno unusedVariables: Devuelve una matriz que contiene los nombres de las variables no utilizadas.
6. Salida: Imprime las variables no utilizadas en la consola.

Este ejemplo demuestra un linter simple. Puede extenderlo para verificar otros estándares de codificación e identificar otros problemas potenciales en su código. Por ejemplo, puede verificar importaciones no utilizadas, funciones demasiado complejas o posibles vulnerabilidades de seguridad. La clave es comprender cómo recorrer el AST e identificar los tipos de nodos específicos que le interesan.

Mejores prácticas y consideraciones

• Comprender el AST: Invierta tiempo en comprender la estructura del AST. Use herramientas como AST explorer para visualizar el AST de su código.
• Usar guardas de tipo: Use guardas de tipo (`ts.isXXX`) para asegurarse de que está trabajando con los tipos de nodos correctos.
• Considerar el rendimiento: Las transformaciones AST pueden ser costosas computacionalmente. Optimice su código para minimizar la cantidad de nodos que visita y transforma.
• Manejar errores: Maneje los errores con elegancia. La API del compilador puede generar excepciones si intenta realizar operaciones no válidas en el AST.
• Probar a fondo: Pruebe sus transformaciones a fondo para asegurarse de que producen los resultados deseados y no introducen nuevos errores.
• Usar bibliotecas existentes: Considere usar bibliotecas existentes que proporcionen abstracciones de nivel superior sobre la API del compilador. Estas bibliotecas pueden simplificar las tareas comunes y reducir la cantidad de código que necesita escribir. Los ejemplos incluyen `ts-morph` y `typescript-eslint`.

Conclusión

La API del compilador de TypeScript es una herramienta poderosa para construir herramientas de desarrollo avanzadas. Al comprender cómo trabajar con el AST, puede crear linters, formateadores de código, analizadores estáticos y otras herramientas que mejoran la calidad del código, automatizan tareas repetitivas y mejoran la productividad del desarrollador. Si bien la API puede ser compleja, los beneficios de dominarla son significativos. Esta guía completa proporciona una base para explorar y utilizar la API del compilador de manera efectiva en sus proyectos. Recuerde aprovechar herramientas como AST Explorer, manejar cuidadosamente los tipos de nodos y probar a fondo sus transformaciones. Con práctica y dedicación, puede desbloquear todo el potencial de la API del compilador de TypeScript y construir soluciones innovadoras para el panorama del desarrollo de software.

Exploración adicional:

• Documentación de la API del compilador de TypeScript: [https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API)
• AST Explorer: [https://astexplorer.net/](https://astexplorer.net/)
• biblioteca ts-morph: [https://ts-morph.com/](https://ts-morph.com/)
• typescript-eslint: [https://typescript-eslint.io/](https://typescript-eslint.io/)