TypeScript Compiler API: Bemästra AST-manipulation och kodtransformation

TypeScript Compiler API erbjuder ett kraftfullt gränssnitt för att analysera, manipulera och generera TypeScript- och JavaScript-kod. Kärnan i detta är Abstract Syntax Tree (AST), en strukturerad representation av din källkod. Att förstå hur man arbetar med AST låser upp möjligheter för att bygga avancerade verktyg, såsom linters, kodformaterare, statiska analysverktyg och anpassade kodgeneratorer.

Vad är TypeScript Compiler API?

TypeScript Compiler API är en uppsättning TypeScript-gränssnitt och funktioner som exponerar den interna funktionen hos TypeScript-kompilatorn. Det låter utvecklare programmatiskt interagera med kompileringsprocessen, bortom att bara kompilera kod. Du kan använda det för att:

• Analysera kod: Inspektera kodstruktur, identifiera potentiella problem och extrahera semantisk information.
• Transformera kod: Modifiera befintlig kod, lägga till nya funktioner eller refaktorera kod automatiskt.
• Generera kod: Skapa ny kod från grunden baserat på mallar eller annan input.

Detta API är avgörande för att bygga sofistikerade utvecklingsverktyg som förbättrar kodkvaliteten, automatiserar repetitiva uppgifter och ökar utvecklarnas produktivitet.

Förstå Abstract Syntax Tree (AST)

AST är en trädliknande representation av din kods struktur. Varje nod i trädet representerar ett syntaktiskt konstrukt, såsom en variabeldeklaration, ett funktionsanrop eller ett kontrollflödesuttryck. TypeScript Compiler API tillhandahåller verktyg för att traversera AST, inspektera dess noder och modifiera dem.

Betrakta denna enkla TypeScript-kod:

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

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

AST för denna kod skulle representera funktionsdeklarationen, retur-satsen, mall-strängen, console.log-anropet och andra delar av koden. Att visualisera AST kan vara utmanande, men verktyg som AST explorer (astexplorer.net) kan hjälpa. Dessa verktyg låter dig mata in kod och se dess motsvarande AST i ett användarvänligt format. Att använda AST Explorer hjälper dig att förstå vilken typ av kodstruktur du kommer att manipulera.

Viktiga AST-nodtyper

TypeScript Compiler API definierar olika AST-nodtyper, var och en representerar ett annat syntaktiskt konstrukt. Här är några vanliga nodtyper:

• SourceFile: Representerar en hel TypeScript-fil.
• FunctionDeclaration: Representerar en funktionsdefinition.
• VariableDeclaration: Representerar en variabeldeklaration.
• Identifier: Representerar en identifierare (t.ex. variabelnamn, funktionsnamn).
• StringLiteral: Representerar en strängliteral.
• CallExpression: Representerar ett funktionsanrop.
• ReturnStatement: Representerar en retursats.

Varje nodtyp har egenskaper som ger information om motsvarande kodkomponent. Till exempel kan en `FunctionDeclaration`-nod ha egenskaper för sitt namn, parametrar, returtyp och kropp.

Komma igång med Compiler API

För att börja använda Compiler API behöver du installera TypeScript och ha en grundläggande förståelse för TypeScript-syntax. Här är ett enkelt exempel som visar hur man läser en TypeScript-fil och skriver ut dess 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, // Mål-ECMAScript-version
  true // SetParentNodes: true för att behålla föräldreferenser i 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);

Förklaring:

1. Importera moduler: Importerar `typescript`-modulen och `fs`-modulen för filsystemoperationer.
2. Läs källfil: Läser innehållet i en TypeScript-fil med namnet `example.ts`. Du måste skapa en `example.ts`-fil för att detta ska fungera.
3. Skapa SourceFile: Skapar ett `SourceFile`-objekt, som representerar roten till AST. `ts.createSourceFile`-funktionen parsar källkoden och genererar AST.
4. Skriv ut AST: Definierar en rekursiv funktion `printAST` som traverserar AST och skriver ut typen av varje nod.
5. Anropa printAST: Anropar `printAST` för att börja skriva ut AST från rot-noden `SourceFile`.

För att köra denna kod, spara den som en `.ts`-fil (t.ex. `ast-example.ts`), skapa en `example.ts`-fil med lite TypeScript-kod, och kompilera och kör sedan koden:

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

Detta kommer att skriva ut AST för din `example.ts`-fil till konsolen. Utmatningen visar hierarkin av noder och deras typer. Till exempel kan det visa `FunctionDeclaration`, `Identifier`, `Block` och andra nodtyper.

Traversera AST

Compiler API tillhandahåller flera sätt att traversera AST. Det enklaste är att använda `forEachChild`-metoden, som visades i det föregående exemplet. Denna metod besöker varje barnnod till en given nod.

För mer komplexa traverseringsscenarier kan du använda ett `Visitor`-mönster. En visitor är ett objekt som definierar metoder som ska anropas för specifika nodtyper. Detta gör att du kan anpassa traverseringsprocessen och utföra åtgärder baserat på nodtypen.

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);

Förklaring:

1. IdentifierVisitor-klass: Definierar en klass `IdentifierVisitor` med en `visit`-metod.
2. Besök-metod: `visit`-metoden kontrollerar om den aktuella noden är en `Identifier`. Om så är fallet skriver den ut identifierarens text. Den anropar sedan rekursivt `ts.forEachChild` för att besöka barnnoderna.
3. Skapa visitor: Skapar en instans av `IdentifierVisitor`.
4. Starta traversering: Anropar `visit`-metoden på `SourceFile` för att starta traverseringen.

Detta exempel visar hur man hittar alla identifierare i AST. Du kan anpassa detta mönster för att hitta andra nodtyper och utföra olika åtgärder.

Transformera AST

Den verkliga kraften i Compiler API ligger i dess förmåga att transformera AST. Du kan modifiera AST för att ändra strukturen och beteendet hos din kod. Detta är grunden för kodrefaktoreringsverktyg, kodgeneratorer och andra avancerade verktyg.

För att transformera AST behöver du använda funktionen `ts.transform`. Denna funktion tar en `SourceFile` och en lista med `TransformerFactory`-funktioner. En `TransformerFactory` är en funktion som tar ett `TransformationContext` och returnerar en `Transformer`-funktion. `Transformer`-funktionen ansvarar för att besöka och transformera noder i AST.

Här är ett enkelt exempel som visar hur man lägger till en kommentar i början av 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)) {
        // Skapa en ledande kommentar
        const comment = ts.addSyntheticLeadingComment(
          node,
          ts.SyntaxKind.MultiLineCommentTrivia,
          " This file was automatically transformed ",
          true // har slutradstecken
        );

        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);

Förklaring:

1. TransformerFactory: Definierar en `TransformerFactory`-funktion som returnerar en `Transformer`-funktion.
2. Transformer: `Transformer`-funktionen kontrollerar om den aktuella noden är en `SourceFile`. Om så är fallet lägger den till en ledande kommentar till noden med hjälp av `ts.addSyntheticLeadingComment`.
3. ts.transform: Anropar `ts.transform` för att tillämpa transformationen på `SourceFile`.
4. Printer: Skapar ett `Printer`-objekt för att generera kod från den transformerade AST.
5. Skriv ut och spara: Skriver ut den transformerade koden och sparar den i en ny fil med namnet `example.transformed.ts`.

Detta exempel visar en enkel transformation, men du kan använda samma mönster för att utföra mer komplexa transformationer, såsom refaktorering av kod, läggning till loggningssatser eller generering av dokumentation.

Avancerade transformationstekniker

Här är några avancerade transformationstekniker du kan använda med Compiler API:

• Skapa nya noder: Använd `ts.createXXX`-funktionerna för att skapa nya AST-noder. Till exempel skapar `ts.createVariableDeclaration` en ny variabeldeklarationsnod.
• Byta ut noder: Byt ut befintliga noder mot nya noder med hjälp av `ts.visitEachChild`-funktionen.
• Lägga till noder: Lägg till nya noder i AST med hjälp av `ts.updateXXX`-funktionerna. Till exempel uppdaterar `ts.updateBlock` en block-sats med nya satser.
• Ta bort noder: Ta bort noder från AST genom att returnera `undefined` från transformer-funktionen.

Kodgenerering

Efter att ha transformerat AST måste du generera kod från den. Compiler API tillhandahåller ett `Printer`-objekt för detta ändamål. `Printer` tar en AST och genererar en strängrepresentation av koden.

Funktionen `ts.createPrinter` skapar ett `Printer`-objekt. Du kan konfigurera skrivaren med olika alternativ, såsom radbrytningstecknet som ska användas och om kommentarer ska inkluderas.

Metoden `printer.printFile` tar en `SourceFile` och returnerar en strängrepresentation av koden. Du kan sedan skriva denna sträng till en fil.

Praktiska tillämpningar av Compiler API

TypeScript Compiler API har många praktiska tillämpningar inom mjukvaruutveckling. Här är några exempel:

• Linters: Bygg anpassade linters för att upprätthålla kodstandarder och identifiera potentiella problem i din kod.
• Kodformaterare: Skapa kodformaterare för att automatiskt formatera din kod enligt en specifik stilguide.
• Statiska analysverktyg: Utveckla statiska analysverktyg för att upptäcka buggar, säkerhetsbrister och prestandaflaskhalsar i din kod.
• Kodgeneratorer: Generera kod från mallar eller annan input, automatisera repetitiva uppgifter och minska boilerplate-kod. Till exempel kan en generator skapa API-klienter eller databasscheman från en beskrivningsfil.
• Refaktoreringsverktyg: Bygg refaktoreringsverktyg för att automatiskt byta namn på variabler, extrahera funktioner eller flytta kod mellan filer.
• Automatisering av internationalisering (i18n): Extrahera automatiskt översättningsbara strängar från din TypeScript-kod och generera lokaliseringsfiler för olika språk. Till exempel kan ett verktyg skanna kod för strängar som skickas till en `translate()`-funktion och automatiskt lägga till dem i en översättningsresursfil.

Exempel: Bygga en enkel Linter

Låt oss skapa en enkel linter som kontrollerar oanvända variabler i TypeScript-kod. Denna linter kommer att identifiera variabler som deklareras men aldrig används.

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("Oanvända variabler:");
  unusedVariables.forEach(variable => console.log(`- ${variable}`));
} else {
  console.log("Inga oanvända variabler hittades.");
}

Förklaring:

1. findUnusedVariables-funktion: Definierar en funktion `findUnusedVariables` som tar en `SourceFile` som input.
2. usedVariables-mängd: Skapar en `Set` för att lagra namnen på använda variabler.
3. visit-funktion: Definierar en rekursiv funktion `visit` som traverserar AST och lägger till namnen på alla identifierare i `usedVariables`-mängden.
4. checkVariableDeclaration-funktion: Definierar en rekursiv funktion `checkVariableDeclaration` som kontrollerar om en variabeldeklaration är oanvänd. Om så är fallet läggs variabelnamnet till i arrayen `unusedVariables`.
5. Returnera unusedVariables: Returnerar en array som innehåller namnen på eventuella oanvända variabler.
6. Utmatning: Skriver ut de oanvända variablerna till konsolen.

Detta exempel visar en enkel linter. Du kan utöka den för att kontrollera andra kodstandarder och identifiera andra potentiella problem i din kod. Till exempel kan du kontrollera oanvända importer, alltför komplexa funktioner eller potentiella säkerhetsproblem. Nyckeln är att förstå hur man traverserar AST och identifierar de specifika nodtyper du är intresserad av.

Bästa metoder och överväganden

• Förstå AST: Lägg tid på att förstå AST:s struktur. Använd verktyg som AST explorer för att visualisera din kods AST.
• Använd typkontroller: Använd typkontroller (`ts.isXXX`) för att säkerställa att du arbetar med rätt nodtyper.
• Överväg prestanda: AST-transformationer kan vara beräkningsmässigt dyra. Optimera din kod för att minimera antalet noder du besöker och transformerar.
• Hantera fel: Hantera fel på ett smidigt sätt. Compiler API kan kasta undantag om du försöker utföra ogiltiga operationer på AST.
• Testa noggrant: Testa dina transformationer noggrant för att säkerställa att de ger önskade resultat och inte introducerar nya buggar.
• Använd befintliga bibliotek: Överväg att använda befintliga bibliotek som tillhandahåller abstraktioner på högre nivå över Compiler API. Dessa bibliotek kan förenkla vanliga uppgifter och minska mängden kod du behöver skriva. Exempel inkluderar `ts-morph` och `typescript-eslint`.

Slutsats

TypeScript Compiler API är ett kraftfullt verktyg för att bygga avancerade utvecklingsverktyg. Genom att förstå hur man arbetar med AST kan du skapa linters, kodformaterare, statiska analysverktyg och andra verktyg som förbättrar kodkvaliteten, automatiserar repetitiva uppgifter och ökar utvecklarnas produktivitet. Även om API:et kan vara komplext, är fördelarna med att bemästra det betydande. Denna omfattande guide ger en grund för att utforska och effektivt utnyttja Compiler API i dina projekt. Kom ihåg att använda verktyg som AST Explorer, hantera nodtyper noggrant och testa dina transformationer grundligt. Med övning och engagemang kan du låsa upp den fulla potentialen i TypeScript Compiler API och bygga innovativa lösningar för mjukvaruutvecklingslandskapet.

Vidare utforskning:

• 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-biblioteket: [https://ts-morph.com/](https://ts-morph.com/)
• typescript-eslint: [https://typescript-eslint.io/](https://typescript-eslint.io/)