TypeScript Compiler API: Ovladavanje manipulacijom AST-a i transformacijom koda

TypeScript Compiler API pruža moćno sučelje za analizu, manipulaciju i generiranje TypeScript i JavaScript koda. U njegovom srcu leži Abstract Syntax Tree (AST), strukturirani prikaz vašeg izvornog koda. Razumijevanje rada s AST-om otključava mogućnosti za izgradnju naprednih alata, poput lintova, formatiranja koda, statičkih analizatora i prilagođenih generatora koda.

Što je TypeScript Compiler API?

TypeScript Compiler API je skup TypeScript sučelja i funkcija koje izlažu unutarnji rad TypeScript kompajlera. Omogućuje razvojnim inženjerima programsko interakciju s procesom kompilacije, prelazeći preko pukog kompiliranja koda. Možete ga koristiti za:

• Analiza koda: Pregledajte strukturu koda, identificirajte potencijalne probleme i izdvojite semantičke informacije.
• Transformacija koda: Izmijenite postojeći kod, dodajte nove značajke ili automatski refaktorirajte kod.
• Generiranje koda: Stvorite novi kod iz temelja na temelju predložaka ili drugih ulaznih podataka.

Ovaj API je neophodan za izgradnju sofisticiranih razvojnih alata koji poboljšavaju kvalitetu koda, automatiziraju ponavljajuće zadatke i povećavaju produktivnost razvojnih inženjera.

Razumijevanje Abstract Syntax Tree (AST)

AST je prikaz strukture vašeg koda poput stabla. Svaki čvor u stablu predstavlja sintaktički konstrukt, poput deklaracije varijable, poziva funkcije ili izjave o kontroli toka. TypeScript Compiler API pruža alate za kretanje AST-om, pregled njegovih čvorova i njihovu izmjenu.

Razmotrite ovaj jednostavan TypeScript kod:

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

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

AST za ovaj kod predstavljao bi deklaraciju funkcije, izjavu povratka, predložak literala, poziv console.log i druge elemente koda. Vizualizacija AST-a može biti izazovna, ali alati poput AST explorera (astexplorer.net) mogu pomoći. Ovi alati omogućuju vam unos koda i pregled njegovog pripadajućeg AST-a u korisnički prilagođenom formatu. Korištenje AST Explorera pomoći će vam da shvatite vrstu strukture koda kojom ćete manipulirati.

Ključne vrste čvorova AST-a

TypeScript Compiler API definira različite vrste čvorova AST-a, od kojih svaka predstavlja drugačiji sintaktički konstrukt. Evo nekoliko uobičajenih vrsta čvorova:

• SourceFile: Predstavlja cijelu TypeScript datoteku.
• FunctionDeclaration: Predstavlja definiciju funkcije.
• VariableDeclaration: Predstavlja deklaraciju varijable.
• Identifier: Predstavlja identifikator (npr. naziv varijable, naziv funkcije).
• StringLiteral: Predstavlja literale niza.
• CallExpression: Predstavlja poziv funkcije.
• ReturnStatement: Predstavlja izjavu povratka.

Svaka vrsta čvora ima svojstva koja pružaju informacije o pripadajućem elementu koda. Na primjer, čvor `FunctionDeclaration` može imati svojstva za svoj naziv, parametre, povratni tip i tijelo.

Početak rada s Compiler API-jem

Za početak korištenja Compiler API-ja, morat ćete instalirati TypeScript i imati osnovno razumijevanje TypeScript sintakse. Evo jednostavnog primjera koji prikazuje kako čitati TypeScript datoteku i ispisati njezin 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, // Ciljna verzija ECMAScripta
  true // SetParentNodes: true za zadržavanje referenci roditelja u AST-u
);

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

Objašnjenje:

1. Uvoz modula: Uvozi modul `typescript` i modul `fs` za operacije na datotečnom sustavu.
2. Čitanje izvorne datoteke: Čita sadržaj TypeScript datoteke nazvane `example.ts`. Morat ćete stvoriti datoteku `example.ts` da bi ovo radilo.
3. Stvaranje SourceFile: Stvara objekt `SourceFile`, koji predstavlja korijen AST-a. Funkcija `ts.createSourceFile` parsira izvorni kod i generira AST.
4. Ispis AST-a: Definira rekurzivnu funkciju `printAST` koja prolazi kroz AST i ispisuje vrstu svakog čvora.
5. Pozivanje printAST: Poziva `printAST` kako bi započela ispis AST-a od korijenskog čvora `SourceFile`.

Za pokretanje ovog koda, spremite ga kao `.ts` datoteku (npr. `ast-example.ts`), stvorite datoteku `example.ts` s nekim TypeScript kodom, a zatim kompilirajte i pokrenite kod:

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

Ovo će ispisati AST vaše `example.ts` datoteke u konzolu. Izlaz će prikazati hijerarhiju čvorova i njihove vrste. Na primjer, može prikazati `FunctionDeclaration`, `Identifier`, `Block` i druge vrste čvorova.

Kretanje kroz AST

Compiler API pruža nekoliko načina za kretanje kroz AST. Najjednostavniji je korištenje metode `forEachChild`, kao što je prikazano u prethodnom primjeru. Ova metoda posjećuje svaki dječji čvor danog čvora.

Za složenije scenarije kretanja, možete koristiti obrasac `Visitor`. Visitor je objekt koji definira metode koje će se pozivati za određene vrste čvorova. Ovo vam omogućuje prilagođavanje procesa kretanja i izvršavanje radnji na temelju vrste čvora.

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(`Pronađen identifikator: ${node.text}`);
    }

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

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

Objašnjenje:

1. Klasa IdentifierVisitor: Definira klasu `IdentifierVisitor` s metodom `visit`.
2. Metoda Visit: Metoda `visit` provjerava je li trenutni čvor `Identifier`. Ako jest, ispisuje tekst identifikatora. Zatim rekurzivno poziva `ts.forEachChild` za posjetu dječjim čvorovima.
3. Stvaranje Visitora: Stvara instancu `IdentifierVisitor`.
4. Pokretanje kretanja: Poziva metodu `visit` na `SourceFile` za početak kretanja.

Ovaj primjer prikazuje kako pronaći sve identifikatore u AST-u. Možete prilagoditi ovaj obrazac za pronalaženje drugih vrsta čvorova i izvršavanje različitih radnji.

Transformacija AST-a

Prava snaga Compiler API-ja leži u njegovoj sposobnosti transformacije AST-a. Možete izmijeniti AST kako biste promijenili strukturu i ponašanje vašeg koda. Ovo je osnova za alate za refaktoriranje koda, generatore koda i druge napredne alate.

Za transformaciju AST-a, morat ćete koristiti funkciju `ts.transform`. Ova funkcija uzima `SourceFile` i popis funkcija `TransformerFactory`. `TransformerFactory` je funkcija koja uzima `TransformationContext` i vraća funkciju `Transformer`. Funkcija `Transformer` je odgovorna za posjećivanje i transformiranje čvorova u AST-u.

Evo jednostavnog primjera koji prikazuje kako dodati komentar na početak TypeScript datoteke:

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)) {
        // Stvaranje komentara ispred
        const comment = ts.addSyntheticLeadingComment(
          node,
          ts.SyntaxKind.MultiLineCommentTrivia,
          " Ovaj je datoteku automatski transformiran ",
          true // ima naknadni novi red
        );

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

Objašnjenje:

1. TransformerFactory: Definira funkciju `TransformerFactory` koja vraća funkciju `Transformer`.
2. Transformer: Funkcija `Transformer` provjerava je li trenutni čvor `SourceFile`. Ako jest, dodaje komentar ispred čvoru pomoću `ts.addSyntheticLeadingComment`.
3. ts.transform: Poziva `ts.transform` za primjenu transformacije na `SourceFile`.
4. Printer: Stvara objekt `Printer` za generiranje koda iz transformiranog AST-a.
5. Ispis i pisanje: Ispisuje transformirani kod i zapisuje ga u novu datoteku nazvanu `example.transformed.ts`.

Ovaj primjer prikazuje jednostavnu transformaciju, ali možete koristiti isti obrazac za izvođenje složenijih transformacija, poput refaktoriranja koda, dodavanja redaka za logiranje ili generiranja dokumentacije.

Napredne tehnike transformacije

Evo nekih naprednih tehnika transformacije koje možete koristiti s Compiler API-jem:

• Stvaranje novih čvorova: Koristite funkcije `ts.createXXX` za stvaranje novih AST čvorova. Na primjer, `ts.createVariableDeclaration` stvara novi čvor deklaracije varijable.
• Zamjena čvorova: Zamijenite postojeće čvorove novim čvorovima pomoću funkcije `ts.visitEachChild`.
• Dodavanje čvorova: Dodajte nove čvorove u AST pomoću funkcija `ts.updateXXX`. Na primjer, `ts.updateBlock` ažurira blok izjave novim izjavama.
• Uklanjanje čvorova: Uklonite čvorove iz AST-a vraćanjem `undefined` iz funkcije transformatora.

Generiranje koda

Nakon transformacije AST-a, morat ćete generirati kod iz njega. Compiler API pruža `Printer` objekt za ovu svrhu. `Printer` uzima AST i generira tekstualni prikaz koda.

Funkcija `ts.createPrinter` stvara `Printer` objekt. `Printer` možete konfigurirati s raznim opcijama, poput znaka za novi red koji će se koristiti i hoće li se emitirati komentari.

Metoda `printer.printFile` uzima `SourceFile` i vraća tekstualni prikaz koda. Taj tekst zatim možete zapisati u datoteku.

Praktične primjene Compiler API-ja

TypeScript Compiler API ima brojne praktične primjene u razvoju softvera. Evo nekoliko primjera:

• Lintovi: Izgradite prilagođene lintove za provođenje standarda kodiranja i identificiranje potencijalnih problema u vašem kodu.
• Formatiranje koda: Stvorite formatere koda za automatsko formatiranje vašeg koda prema određenom stilskom vodiču.
• Statički analizatori: Razvijte statičke analizatore za otkrivanje grešaka, sigurnosnih propusta i uskih grla performansi u vašem kodu.
• Generatori koda: Generirajte kod iz predložaka ili drugih ulaznih podataka, automatizirajući ponavljajuće zadatke i smanjujući ponavljajući kod. Na primjer, generator klijenata API-ja ili shema baza podataka iz datoteke s opisom.
• Alati za refaktoriranje: Izgradite alate za refaktoriranje za automatsko preimenovanje varijabli, izdvajanje funkcija ili premještanje koda između datoteka.
• Automatizacija internacionalizacije (i18n): Automatski ekstrahirajte nizove za prevođenje iz vašeg TypeScript koda i generirajte datoteke lokalizacije za različite jezike. Na primjer, alat bi mogao skenirati kod za nizove proslijeđene `translate()` funkciji i automatski ih dodati u datoteku s resursima za prijevod.

Primjer: Izgradnja jednostavnog lint alata

Stvorimo jednostavan lint alat koji provjerava nekorištene varijable u TypeScript kodu. Ovaj lint alat će identificirati varijable koje su deklarirane, ali nikada korištene.

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("Nekorištene varijable:");
  unusedVariables.forEach(variable => console.log(`- ${variable}`));
} else {
  console.log("Nisu pronađene nekorištene varijable.");
}

Objašnjenje:

1. Funkcija findUnusedVariables: Definira funkciju `findUnusedVariables` koja prima `SourceFile` kao ulaz.
2. Set usedVariables: Stvara `Set` za pohranu naziva korištenih varijabli.
3. Funkcija visit: Definira rekurzivnu funkciju `visit` koja prolazi kroz AST i dodaje nazive svih identifikatora u `usedVariables` set.
4. Funkcija checkVariableDeclaration: Definira rekurzivnu funkciju `checkVariableDeclaration` koja provjerava je li deklaracija varijable nekorištena. Ako jest, dodaje naziv varijable u `unusedVariables` niz.
5. Vraća unusedVariables: Vraća niz koji sadrži nazive bilo kojih nekorištenih varijabli.
6. Ispis: Ispisuje nekorištene varijable u konzolu.

Ovaj primjer prikazuje jednostavan lint alat. Možete ga proširiti za provjeru drugih standarda kodiranja i identificiranje drugih potencijalnih problema u vašem kodu. Na primjer, možete provjeriti nekorištene uvoze, prekomplicirane funkcije ili potencijalne sigurnosne propuste. Ključ je razumjeti kako proći kroz AST i identificirati specifične vrste čvorova koje vas zanimaju.

Najbolje prakse i razmatranja

• Razumijte AST: Odvojite vrijeme za razumijevanje strukture AST-a. Koristite alate poput AST explorera za vizualizaciju AST-a vašeg koda.
• Koristite Type Guards: Koristite Type Guards (`ts.isXXX`) kako biste osigurali da radite sa ispravnim vrstama čvorova.
• Razmotrite performanse: Transformacije AST-a mogu biti izračunski skupe. Optimizirajte svoj kod kako biste minimizirali broj čvorova koje posjećujete i transformirate.
• Rukovajte greškama: Rukovajte greškama na elegantan način. Compiler API može baciti iznimke ako pokušate izvršiti nevažeće operacije na AST-u.
• Testirajte temeljito: Testirajte svoje transformacije temeljito kako biste osigurali da proizvode željene rezultate i ne uvode nove greške.
• Koristite postojeće biblioteke: Razmotrite korištenje postojećih biblioteka koje pružaju apstrakcije višeg nivoa nad Compiler API-jem. Ove biblioteke mogu pojednostaviti uobičajene zadatke i smanjiti količinu koda koju trebate napisati. Primjeri uključuju `ts-morph` i `typescript-eslint`.

Zaključak

TypeScript Compiler API je moćan alat za izgradnju naprednih razvojnih alata. Razumijevanjem rada s AST-om, možete izraditi lintove, formatere koda, statičke analizatore i druge alate koji poboljšavaju kvalitetu koda, automatiziraju ponavljajuće zadatke i povećavaju produktivnost razvojnih inženjera. Iako API može biti složen, prednosti ovladavanja njime su značajne. Ovaj sveobuhvatan vodič pruža temelj za istraživanje i učinkovito korištenje Compiler API-ja u vašim projektima. Zapamtite iskoristiti alate poput AST Explorera, pažljivo rukovati vrstama čvorova i temeljito testirati svoje transformacije. Uz praksu i predanost, možete otključati puni potencijal TypeScript Compiler API-ja i izgraditi inovativna rješenja za krajolik razvoja softvera.

Daljnje istraživanje:

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