TypeScript Compiler API: Mestring af AST-manipulation og kodetransformation

TypeScript Compiler API'et giver en kraftfuld grænseflade til analyse, manipulation og generering af TypeScript- og JavaScript-kode. Kernen er Abstract Syntax Tree (AST), en struktureret repræsentation af din kildekode. Forståelse af, hvordan man arbejder med AST'en, åbner op for muligheder for at bygge avancerede værktøjer, såsom linters, kodeformattere, statiske analysatorer og brugerdefinerede kodegeneratorer.

Hvad er TypeScript Compiler API?

TypeScript Compiler API'et er et sæt TypeScript-grænseflader og -funktioner, der eksponerer det indre af TypeScript-compileren. Det giver udviklere mulighed for at interagere programmatisk med kompileringsprocessen og gå ud over blot at kompilere kode. Du kan bruge det til at:

• Analysere kode: Inspicere kodestruktur, identificere potentielle problemer og udtrække semantisk information.
• Transformere kode: Modificere eksisterende kode, tilføje nye funktioner eller refaktorere kode automatisk.
• Generere kode: Oprette ny kode fra bunden baseret på skabeloner eller anden input.

Dette API er essentielt for at bygge sofistikerede udviklingsværktøjer, der forbedrer kodekvaliteten, automatiserer gentagne opgaver og forbedrer udviklerproduktiviteten.

Forståelse af Abstract Syntax Tree (AST)

AST'en er en trælignende repræsentation af din kodes struktur. Hver node i træet repræsenterer en syntaktisk konstruktion, såsom en variabeldeklaration, et funktionskald eller en kontrol flow statement. TypeScript Compiler API'et leverer værktøjer til at gennemløbe AST'en, inspicere dens noder og modificere dem.

Overvej denne simple TypeScript-kode:

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

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

AST'en for denne kode ville repræsentere funktionsdeklarationen, return statement, template literal, console.log kald og andre elementer af koden. Visualisering af AST'en kan være udfordrende, men værktøjer som AST explorer (astexplorer.net) kan hjælpe. Disse værktøjer giver dig mulighed for at indtaste kode og se dens tilsvarende AST i et brugervenligt format. Brug af AST Explorer vil hjælpe dig med at forstå den type kodestruktur, du vil manipulere.

Nøgle AST Node Typer

TypeScript Compiler API'et definerer forskellige AST node typer, der hver især repræsenterer en forskellig syntaktisk konstruktion. Her er nogle almindelige nodetyper:

• SourceFile: Repræsenterer en hel TypeScript-fil.
• FunctionDeclaration: Repræsenterer en funktionsdefinition.
• VariableDeclaration: Repræsenterer en variabeldeklaration.
• Identifier: Repræsenterer en identifikator (f.eks. variabelnavn, funktionsnavn).
• StringLiteral: Repræsenterer en strengliteral.
• CallExpression: Repræsenterer et funktionskald.
• ReturnStatement: Repræsenterer en return statement.

Hver nodetype har egenskaber, der giver information om det tilsvarende kodeelement. For eksempel kan en `FunctionDeclaration` node have egenskaber for dens navn, parametre, returtype og krop.

Kom godt i gang med Compiler API'et

For at begynde at bruge Compiler API'et skal du installere TypeScript og have en grundlæggende forståelse af TypeScript-syntaks. Her er et simpelt eksempel, der demonstrerer, hvordan man læser en TypeScript-fil og udskriver dens AST:

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

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

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015, // Target ECMAScript version
  true // SetParentNodes: true to retain parent references in the 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);

Forklaring:

1. Importer moduler: Importerer `typescript`-modulet og `fs`-modulet til filsystemoperationer.
2. Læs kildefil: Læser indholdet af en TypeScript-fil ved navn `example.ts`. Du skal oprette en `example.ts`-fil for at dette kan fungere.
3. Opret SourceFile: Opretter et `SourceFile`-objekt, der repræsenterer roden af AST'en. Funktionen `ts.createSourceFile` parser kildekoden og genererer AST'en.
4. Udskriv AST: Definerer en rekursiv funktion `printAST`, der gennemløber AST'en og udskriver typen af hver node.
5. Kald printAST: Kalder `printAST` for at starte udskrivningen af AST'en fra roden `SourceFile`-noden.

For at køre denne kode skal du gemme den som en `.ts`-fil (f.eks. `ast-example.ts`), oprette en `example.ts`-fil med noget TypeScript-kode og derefter kompilere og køre koden:

tsc ast-example.ts
node ast-example.js

Dette vil udskrive AST'en for din `example.ts`-fil til konsollen. Outputtet vil vise hierarkiet af noder og deres typer. For eksempel kan det vise `FunctionDeclaration`, `Identifier`, `Block` og andre nodetyper.

Gennemgang af AST'en

Compiler API'et giver flere måder at gennemløbe AST'en på. Den enkleste er at bruge metoden `forEachChild`, som vist i det forrige eksempel. Denne metode besøger hver underordnet node af en given node.

For mere komplekse gennemgangsscenarier kan du bruge et `Visitor`-mønster. En visitor er et objekt, der definerer metoder, der skal kaldes for specifikke nodetyper. Dette giver dig mulighed for at tilpasse gennemgangsprocessen og udføre handlinger baseret på nodetypen.

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

const fileName = "example.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(`Found identifier: ${node.text}`);
    }

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

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

Forklaring:

1. IdentifierVisitor Klasse: Definerer en klasse `IdentifierVisitor` med en `visit`-metode.
2. Visit Metode: Metoden `visit` kontrollerer, om den aktuelle node er en `Identifier`. Hvis det er tilfældet, udskriver den identifikatoren tekst. Den kalder derefter rekursivt `ts.forEachChild` for at besøge de underordnede noder.
3. Opret Visitor: Opretter en instans af `IdentifierVisitor`.
4. Start gennemgang: Kalder metoden `visit` på `SourceFile` for at starte gennemgangen.

Dette eksempel demonstrerer, hvordan man finder alle identifikatorer i AST'en. Du kan tilpasse dette mønster til at finde andre nodetyper og udføre forskellige handlinger.

Transformering af AST'en

Den virkelige kraft i Compiler API'et ligger i dets evne til at transformere AST'en. Du kan modificere AST'en for at ændre strukturen og adfærden af din kode. Dette er grundlaget for koderefaktoriseringsværktøjer, kodegeneratorer og andre avancerede værktøjer.

For at transformere AST'en skal du bruge funktionen `ts.transform`. Denne funktion tager en `SourceFile` og en liste over `TransformerFactory`-funktioner. En `TransformerFactory` er en funktion, der tager en `TransformationContext` og returnerer en `Transformer`-funktion. `Transformer`-funktionen er ansvarlig for at besøge og transformere noder i AST'en.

Her er et simpelt eksempel, der demonstrerer, hvordan man tilføjer en kommentar i begyndelsen af en TypeScript-fil:

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

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

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

const transformerFactory: ts.TransformerFactory = context => {
  return transformer => {
    return node => {
      if (ts.isSourceFile(node)) {
        // Create a leading comment
        const comment = ts.addSyntheticLeadingComment(
          node,
          ts.SyntaxKind.MultiLineCommentTrivia,
          " This file was automatically transformed ",
          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("example.transformed.ts", result);

Forklaring:

1. TransformerFactory: Definerer en `TransformerFactory`-funktion, der returnerer en `Transformer`-funktion.
2. Transformer: `Transformer`-funktionen kontrollerer, om den aktuelle node er en `SourceFile`. Hvis det er tilfældet, tilføjer den en indledende kommentar til noden ved hjælp af `ts.addSyntheticLeadingComment`.
3. ts.transform: Kalder `ts.transform` for at anvende transformationen på `SourceFile`.
4. Printer: Opretter et `Printer`-objekt for at generere kode fra den transformerede AST.
5. Udskriv og skriv: Udskriver den transformerede kode og skriver den til en ny fil ved navn `example.transformed.ts`.

Dette eksempel demonstrerer en simpel transformation, men du kan bruge det samme mønster til at udføre mere komplekse transformationer, såsom refaktorering af kode, tilføjelse af logningsudtalelser eller generering af dokumentation.

Avancerede transformationsteknikker

Her er nogle avancerede transformationsteknikker, du kan bruge med Compiler API'et:

• Oprettelse af nye noder: Brug funktionerne `ts.createXXX` til at oprette nye AST-noder. For eksempel opretter `ts.createVariableDeclaration` en ny variabeldeklarationsnode.
• Udskiftning af noder: Udskift eksisterende noder med nye noder ved hjælp af funktionen `ts.visitEachChild`.
• Tilføjelse af noder: Tilføj nye noder til AST'en ved hjælp af funktionerne `ts.updateXXX`. For eksempel opdaterer `ts.updateBlock` en blokudtalelse med nye udtalelser.
• Fjernelse af noder: Fjern noder fra AST'en ved at returnere `undefined` fra transformerfunktionen.

Kodegenerering

Efter at have transformeret AST'en skal du generere kode fra den. Compiler API'et leverer et `Printer`-objekt til dette formål. `Printer`en tager en AST og genererer en strengrepræsentation af koden.

Funktionen `ts.createPrinter` opretter et `Printer`-objekt. Du kan konfigurere printeren med forskellige indstillinger, såsom det linjeskifttegn, der skal bruges, og om kommentarer skal udsendes.

Metoden `printer.printFile` tager en `SourceFile` og returnerer en strengrepræsentation af koden. Du kan derefter skrive denne streng til en fil.

Praktiske anvendelser af Compiler API'et

TypeScript Compiler API'et har adskillige praktiske anvendelser i softwareudvikling. Her er et par eksempler:

• Linters: Byg brugerdefinerede linters til at håndhæve kodningsstandarder og identificere potentielle problemer i din kode.
• Kodeformattere: Opret kodeformattere til automatisk at formatere din kode i henhold til en bestemt stilguide.
• Statiske analysatorer: Udvikl statiske analysatorer til at opdage fejl, sikkerhedssårbarheder og flaskehalse i ydeevnen i din kode.
• Kodegeneratorer: Generer kode fra skabeloner eller anden input, automatiser gentagne opgaver og reducer boilerplate-kode. For eksempel generering af API-klienter eller databaseskemaer fra en beskrivelsesfil.
• Refaktoriseringsværktøjer: Byg refaktoriseringsværktøjer til automatisk at omdøbe variabler, udtrække funktioner eller flytte kode mellem filer.
• Internationalisering (i18n) automatisering: Udtræk automatisk oversættelige strenge fra din TypeScript-kode og generer lokaliseringsfiler til forskellige sprog. For eksempel kunne et værktøj scanne kode for strenge, der er sendt til en `translate()`-funktion, og automatisk føje dem til en oversættelsesressourcefil.

Eksempel: Opbygning af en simpel Linter

Lad os oprette en simpel linter, der kontrollerer for ubrugte variabler i TypeScript-kode. Denne linter vil identificere variabler, der er erklæret, men aldrig brugt.

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

const fileName = "example.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();

  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("Unused variables:");
  unusedVariables.forEach(variable => console.log(`- ${variable}`));
} else {
  console.log("No unused variables found.");
}

Forklaring:

1. findUnusedVariables Funktion: Definerer en funktion `findUnusedVariables`, der tager en `SourceFile` som input.
2. usedVariables Sæt: Opretter et `Sæt` til at gemme navnene på brugte variabler.
3. visit Funktion: Definerer en rekursiv funktion `visit`, der gennemløber AST'en og føjer navnene på alle identifikatorer til `usedVariables`-sættet.
4. checkVariableDeclaration Funktion: Definerer en rekursiv funktion `checkVariableDeclaration`, der kontrollerer, om en variabeldeklaration er ubrugt. Hvis det er tilfældet, føjer den variabelnavnet til `unusedVariables`-arrayet.
5. Returner unusedVariables: Returnerer et array, der indeholder navnene på eventuelle ubrugte variabler.
6. Output: Udskriver de ubrugte variabler til konsollen.

Dette eksempel demonstrerer en simpel linter. Du kan udvide den til at kontrollere for andre kodningsstandarder og identificere andre potentielle problemer i din kode. For eksempel kan du kontrollere for ubrugte importer, alt for komplekse funktioner eller potentielle sikkerhedssårbarheder. Nøglen er at forstå, hvordan man gennemløber AST'en og identificerer de specifikke nodetyper, du er interesseret i.

Best Practices og overvejelser

• Forstå AST'en: Invester tid i at forstå strukturen af AST'en. Brug værktøjer som AST explorer til at visualisere AST'en af din kode.
• Brug typebeskyttelser: Brug typebeskyttelser (`ts.isXXX`) for at sikre, at du arbejder med de korrekte nodetyper.
• Overvej ydeevne: AST-transformationer kan være beregningsmæssigt dyre. Optimer din kode for at minimere antallet af noder, du besøger og transformerer.
• Håndter fejl: Håndter fejl på en elegant måde. Compiler API'et kan udløse undtagelser, hvis du forsøger at udføre ugyldige handlinger på AST'en.
• Test grundigt: Test dine transformationer grundigt for at sikre, at de producerer de ønskede resultater og ikke introducerer nye fejl.
• Brug eksisterende biblioteker: Overvej at bruge eksisterende biblioteker, der giver abstraktioner på højere niveau over Compiler API'et. Disse biblioteker kan forenkle almindelige opgaver og reducere mængden af kode, du skal skrive. Eksempler inkluderer `ts-morph` og `typescript-eslint`.

Konklusion

TypeScript Compiler API'et er et kraftfuldt værktøj til at bygge avancerede udviklingsværktøjer. Ved at forstå, hvordan man arbejder med AST'en, kan du oprette linters, kodeformattere, statiske analysatorer og andre værktøjer, der forbedrer kodekvaliteten, automatiserer gentagne opgaver og forbedrer udviklerproduktiviteten. Selvom API'et kan være komplekst, er fordelene ved at mestre det betydelige. Denne omfattende guide giver et grundlag for at udforske og udnytte Compiler API'et effektivt i dine projekter. Husk at udnytte værktøjer som AST Explorer, håndtere nodetyper omhyggeligt og teste dine transformationer grundigt. Med øvelse og dedikation kan du låse det fulde potentiale i TypeScript Compiler API'et op og bygge innovative løsninger til softwareudviklingslandskabet.

Yderligere udforskning:

• TypeScript Compiler API Dokumentation: [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/)
• ts-morph bibliotek: [https://ts-morph.com/](https://ts-morph.com/)
• typescript-eslint: [https://typescript-eslint.io/](https://typescript-eslint.io/)