TypeScript Compiler API: Zvládnutie manipulácie s AST a transformácie kódu

TypeScript Compiler API poskytuje výkonné rozhranie pre analýzu, manipuláciu a generovanie kódu TypeScript a JavaScript. V jeho jadre leží abstraktný syntaktický strom (AST), štruktúrovaná reprezentácia vášho zdrojového kódu. Pochopenie práce s AST otvára možnosti pre vytváranie pokročilých nástrojov, ako sú lintery, formátovače kódu, statické analyzátory a vlastné generátory kódu.

Čo je TypeScript Compiler API?

TypeScript Compiler API je súbor TypeScript rozhraní a funkcií, ktoré odhaľujú vnútorné fungovanie kompilátora TypeScript. Umožňuje vývojárom programovo interagovať s procesom kompilácie, presahujúc jednoduchú kompiláciu kódu. Môžete ho použiť na:

• Analýza kódu: Kontrola štruktúry kódu, identifikácia potenciálnych problémov a extrahovanie sémantických informácií.
• Transformácia kódu: Úprava existujúceho kódu, pridávanie nových funkcií alebo automatická refaktorizácia kódu.
• Generovanie kódu: Vytváranie nového kódu od základu na základe šablón alebo iného vstupu.

Toto API je nevyhnutné pre vytváranie sofistikovaných vývojových nástrojov, ktoré zlepšujú kvalitu kódu, automatizujú opakujúce sa úlohy a zvyšujú produktivitu vývojárov.

Pochopenie abstraktného syntaktického stromu (AST)

AST je stromová reprezentácia štruktúry vášho kódu. Každý uzol v strome predstavuje syntaktickú konštrukciu, ako je deklarácia premennej, volanie funkcie alebo príkaz riadenia toku. TypeScript Compiler API poskytuje nástroje na prechádzanie AST, kontrolu jeho uzlov a ich modifikáciu.

Zvážte tento jednoduchý kód TypeScript:

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

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

AST pre tento kód by reprezentoval deklaráciu funkcie, príkaz return, šablónový literál, volanie console.log a ďalšie prvky kódu. Vizualizácia AST môže byť náročná, ale nástroje ako AST explorer (astexplorer.net) môžu pomôcť. Tieto nástroje vám umožňujú zadať kód a vidieť jeho zodpovedajúci AST v užívateľsky prívetivom formáte. Použitie AST Exploreru vám pomôže pochopiť druh štruktúry kódu, ktorú budete manipulovať.

Kľúčové typy uzlov AST

TypeScript Compiler API definuje rôzne typy uzlov AST, pričom každý predstavuje inú syntaktickú konštrukciu. Tu sú niektoré bežné typy uzlov:

• SourceFile: Reprezentuje celý súbor TypeScript.
• FunctionDeclaration: Reprezentuje definíciu funkcie.
• VariableDeclaration: Reprezentuje deklaráciu premennej.
• Identifier: Reprezentuje identifikátor (napr. názov premennej, názov funkcie).
• StringLiteral: Reprezentuje reťazcový literál.
• CallExpression: Reprezentuje volanie funkcie.
• ReturnStatement: Reprezentuje príkaz return.

Každý typ uzla má vlastnosti, ktoré poskytujú informácie o zodpovedajúcom prvku kódu. Napríklad uzol `FunctionDeclaration` môže mať vlastnosti pre svoj názov, parametre, návratový typ a telo.

Začíname s Compiler API

Ak chcete začať používať Compiler API, budete potrebovať nainštalovať TypeScript a mať základné pochopenie syntaxe TypeScriptu. Tu je jednoduchý príklad, ktorý demonštruje, ako čítať súbor TypeScript a vytlačiť jeho 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);

Vysvetlenie:

1. Import modulov: Importuje modul `typescript` a modul `fs` pre operácie so súborovým systémom.
2. Čítanie zdrojového súboru: Prečíta obsah súboru TypeScript s názvom `example.ts`. Na to, aby to fungovalo, budete musieť vytvoriť súbor `example.ts`.
3. Vytvorenie SourceFile: Vytvorí objekt `SourceFile`, ktorý predstavuje koreň AST. Funkcia `ts.createSourceFile` analyzuje zdrojový kód a generuje AST.
4. Vytlačenie AST: Definuje rekurzívnu funkciu `printAST`, ktorá prechádza AST a vypíše typ každého uzla.
5. Volanie printAST: Zavolá `printAST` na spustenie tlače AST z koreňového uzla `SourceFile`.

Ak chcete spustiť tento kód, uložte ho ako súbor `.ts` (napr. `ast-example.ts`), vytvorte súbor `example.ts` s nejakým kódom TypeScript a potom skompilujte a spustite kód:

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

Toto vypíše AST vášho súboru `example.ts` do konzoly. Výstup zobrazí hierarchiu uzlov a ich typov. Napríklad môže zobraziť `FunctionDeclaration`, `Identifier`, `Block` a iné typy uzlov.

Prechádzanie AST

Compiler API poskytuje niekoľko spôsobov, ako prechádzať AST. Najjednoduchší je použitie metódy `forEachChild`, ako je ukázané v predchádzajúcom príklade. Táto metóda navštívi každý podriadený uzol daného uzla.

Pre zložitejšie scenáre prechádzania môžete použiť vzor `Visitor`. Visitor je objekt, ktorý definuje metódy, ktoré sa majú volať pre konkrétne typy uzlov. To vám umožňuje prispôsobiť proces prechádzania a vykonávať akcie na základe typu uzla.

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

Vysvetlenie:

1. Trieda IdentifierVisitor: Definuje triedu `IdentifierVisitor` s metódou `visit`.
2. Metóda Visit: Metóda `visit` kontroluje, či je aktuálny uzol `Identifier`. Ak áno, vytlačí text identifikátora. Potom rekurzívne volá `ts.forEachChild` na návštevu podriadených uzlov.
3. Vytvorenie Visitora: Vytvorí inštanciu `IdentifierVisitor`.
4. Spustenie prechádzania: Zavolá metódu `visit` na `SourceFile` na spustenie prechádzania.

Tento príklad demonštruje, ako nájsť všetky identifikátory v AST. Tento vzor môžete prispôsobiť na nájdenie iných typov uzlov a vykonávanie rôznych akcií.

Transformácia AST

Skutočná sila Compiler API spočíva v jeho schopnosti transformovať AST. Môžete modifikovať AST, aby ste zmenili štruktúru a správanie vášho kódu. Toto je základ pre nástroje na refaktorizáciu kódu, generátory kódu a ďalšie pokročilé nástroje.

Ak chcete transformovať AST, budete musieť použiť funkciu `ts.transform`. Táto funkcia prijíma `SourceFile` a zoznam funkcií `TransformerFactory`. `TransformerFactory` je funkcia, ktorá prijíma `TransformationContext` a vracia funkciu `Transformer`. Funkcia `Transformer` je zodpovedná za návštevu a transformáciu uzlov v AST.

Tu je jednoduchý príklad, ktorý demonštruje, ako pridať komentár na začiatok súboru TypeScript:

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

Vysvetlenie:

1. TransformerFactory: Definuje funkciu `TransformerFactory`, ktorá vracia funkciu `Transformer`.
2. Transformer: Funkcia `Transformer` kontroluje, či je aktuálny uzol `SourceFile`. Ak áno, pridá úvodný komentár k uzlu pomocou `ts.addSyntheticLeadingComment`.
3. ts.transform: Zavolá `ts.transform` na aplikovanie transformácie na `SourceFile`.
4. Printer: Vytvorí objekt `Printer` na generovanie kódu z transformovaného AST.
5. Tlač a zápis: Vytlačí transformovaný kód a zapíše ho do nového súboru s názvom `example.transformed.ts`.

Tento príklad demonštruje jednoduchú transformáciu, ale rovnaký vzor môžete použiť na vykonávanie zložitejších transformácií, ako je refaktorizácia kódu, pridávanie logovacích príkazov alebo generovanie dokumentácie.

Pokročilé techniky transformácie

• Vytváranie nových uzlov: Použite funkcie `ts.createXXX` na vytvorenie nových uzlov AST. Napríklad `ts.createVariableDeclaration` vytvorí nový uzol deklarácie premennej.
• Nahradenie uzlov: Nahraďte existujúce uzly novými uzlami pomocou funkcie `ts.visitEachChild`.
• Pridávanie uzlov: Pridajte nové uzly do AST pomocou funkcií `ts.updateXXX`. Napríklad `ts.updateBlock` aktualizuje blokový príkaz o nové príkazy.
• Odstraňovanie uzlov: Odstráňte uzly z AST vrátením `undefined` z funkcie transformátora.

Generovanie kódu

Po transformácii AST budete musieť z neho vygenerovať kód. Compiler API na tento účel poskytuje objekt `Printer`. `Printer` prijíma AST a generuje reťazcovú reprezentáciu kódu.

Funkcia `ts.createPrinter` vytvorí objekt `Printer`. Tlačiareň môžete nakonfigurovať rôznymi možnosťami, ako je znak nového riadku, ktorý sa má použiť, a či sa majú emitovať komentáre.

Metóda `printer.printFile` prijíma `SourceFile` a vracia reťazcovú reprezentáciu kódu. Tento reťazec potom môžete zapísať do súboru.

Praktické aplikácie Compiler API

TypeScript Compiler API má množstvo praktických aplikácií vo vývoji softvéru. Tu je niekoľko príkladov:

• Lintery: Vytvárajte vlastné lintery na vynútenie kódovacích štandardov a identifikáciu potenciálnych problémov vo vašom kóde.
• Formátovače kódu: Vytvárajte formátovače kódu na automatické formátovanie kódu podľa špecifického štýlového sprievodcu.
• Statické analyzátory: Vyvíjajte statické analyzátory na detekciu chýb, bezpečnostných zraniteľností a úzkych miest výkonu vo vašom kóde.
• Generátory kódu: Generujte kód zo šablón alebo iného vstupu, automatizujte opakujúce sa úlohy a znižujte množstvo štandardného kódu. Napríklad generovanie klientov API alebo schém databáz zo súboru s popisom.
• Nástroje na refaktorizáciu: Vytvárajte nástroje na refaktorizáciu na automatické premenovávanie premenných, extrahovanie funkcií alebo presúvanie kódu medzi súbormi.
• Automatizácia internacionalizácie (i18n): Automaticky extrahujte preložiteľné reťazce z kódu TypeScript a generujte lokalizačné súbory pre rôzne jazyky. Napríklad nástroj by mohol skenovať kód pre reťazce odovzdané funkcii `translate()` a automaticky ich pridať do súboru prekladových zdrojov.

Príklad: Vytvorenie jednoduchého lintera

Vytvorme jednoduchý linter, ktorý kontroluje nepoužité premenné v kóde TypeScript. Tento linter identifikuje premenné, ktoré sú deklarované, ale nikdy nepoužité.

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.");
}

Vysvetlenie:

1. Funkcia findUnusedVariables: Definuje funkciu `findUnusedVariables`, ktorá prijíma `SourceFile` ako vstup.
2. Množina usedVariables: Vytvorí `Set` na ukladanie názvov použitých premenných.
3. Funkcia visit: Definuje rekurzívnu funkciu `visit`, ktorá prechádza AST a pridáva názvy všetkých identifikátorov do množiny `usedVariables`.
4. Funkcia checkVariableDeclaration: Definuje rekurzívnu funkciu `checkVariableDeclaration`, ktorá kontroluje, či je deklarácia premennej nepoužitá. Ak áno, pridá názov premennej do poľa `unusedVariables`.
5. Vrátenie unusedVariables: Vráti pole obsahujúce názvy všetkých nepoužitých premenných.
6. Výstup: Vytlačí nepoužité premenné do konzoly.

Tento príklad demonštruje jednoduchý linter. Môžete ho rozšíriť na kontrolu ďalších kódovacích štandardov a identifikáciu ďalších potenciálnych problémov vo vašom kóde. Napríklad, mohli by ste kontrolovať nepoužité importy, príliš zložité funkcie alebo potenciálne bezpečnostné zraniteľnosti. Kľúčové je pochopiť, ako prechádzať AST a identifikovať konkrétne typy uzlov, o ktoré máte záujem.

Osvedčené postupy a úvahy

• Pochopte AST: Investujte čas do pochopenia štruktúry AST. Používajte nástroje ako AST explorer na vizualizáciu AST vášho kódu.
• Používajte Type Guardy: Používajte type guardy (`ts.isXXX`), aby ste sa uistili, že pracujete so správnymi typmi uzlov.
• Zvážte výkon: Transformácie AST môžu byť výpočtovo náročné. Optimalizujte svoj kód, aby ste minimalizovali počet uzlov, ktoré navštívite a transformujete.
• Správne spracovanie chýb: Spracujte chyby elegantne. Compiler API môže vyhodiť výnimky, ak sa pokúsite vykonať neplatné operácie na AST.
• Dôkladné testovanie: Dôkladne otestujte svoje transformácie, aby ste sa uistili, že produkujú požadované výsledky a nezavádzajú nové chyby.
• Používajte existujúce knižnice: Zvážte použitie existujúcich knižníc, ktoré poskytujú abstrakcie vyššej úrovne nad Compiler API. Tieto knižnice môžu zjednodušiť bežné úlohy a znížiť množstvo kódu, ktorý musíte napísať. Príklady zahŕňajú `ts-morph` a `typescript-eslint`.

Záver

TypeScript Compiler API je výkonný nástroj na vytváranie pokročilých vývojových nástrojov. Pochopením práce s AST môžete vytvárať lintery, formátovače kódu, statické analyzátory a ďalšie nástroje, ktoré zlepšujú kvalitu kódu, automatizujú opakujúce sa úlohy a zvyšujú produktivitu vývojárov. Hoci API môže byť zložité, výhody jeho zvládnutia sú značné. Tento komplexný sprievodca poskytuje základ pre skúmanie a efektívne využívanie Compiler API vo vašich projektoch. Nezabudnite využívať nástroje ako AST Explorer, starostlivo zaobchádzať s typmi uzlov a dôkladne testovať vaše transformácie. S praxou a odhodlaním môžete odomknúť plný potenciál TypeScript Compiler API a budovať inovatívne riešenia pre oblasť vývoja softvéru.

Ďalšie informácie:

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