TypeScript Compiler API: Opis i manipulacja AST oraz transformacja kodu

TypeScript Compiler API zapewnia potężny interfejs do analizowania, manipulowania i generowania kodu TypeScript i JavaScript. W jego sercu znajduje się Abstract Syntax Tree (AST), czyli strukturalna reprezentacja kodu źródłowego. Zrozumienie, jak pracować z AST, odblokowuje możliwości budowania zaawansowanych narzędzi, takich jak linters, formatery kodu, analizatory statyczne i niestandardowe generatory kodu.

Czym jest TypeScript Compiler API?

TypeScript Compiler API to zestaw interfejsów i funkcji TypeScript, które ujawniają wewnętrzne działanie kompilatora TypeScript. Umożliwia programistom programowe interakcje z procesem kompilacji, wykraczając poza zwykłą kompilację kodu. Możesz go użyć, aby:

• Analizować kod: Sprawdzać strukturę kodu, identyfikować potencjalne problemy i wyodrębniać informacje semantyczne.
• Transformować kod: Modyfikować istniejący kod, dodawać nowe funkcje lub refaktoryzować kod automatycznie.
• Generować kod: Tworzyć nowy kod od podstaw na podstawie szablonów lub innych danych wejściowych.

To API jest niezbędne do budowy zaawansowanych narzędzi programistycznych, które poprawiają jakość kodu, automatyzują powtarzalne zadania i zwiększają produktywność programistów.

Zrozumienie Abstract Syntax Tree (AST)

AST to reprezentacja struktury twojego kodu w postaci drzewa. Każdy węzeł w drzewie reprezentuje konstrukcję składniową, taką jak deklaracja zmiennej, wywołanie funkcji lub instrukcja sterowania przepływem. TypeScript Compiler API udostępnia narzędzia do przechodzenia po AST, sprawdzania jego węzłów i modyfikowania ich.

Rozważmy ten prosty kod TypeScript:

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

console.log(greet("Świecie"));

AST dla tego kodu będzie reprezentować deklarację funkcji, instrukcję return, literal szablonu, wywołanie console.log i inne elementy kodu. Wizualizacja AST może być wyzwaniem, ale narzędzia takie jak AST explorer (astexplorer.net) mogą pomóc. Narzędzia te pozwalają na wprowadzenie kodu i zobaczenie jego odpowiadającego AST w przyjaznym dla użytkownika formacie. Korzystanie z AST Explorer pomoże Ci zrozumieć rodzaj struktury kodu, którą będziesz manipulować.

Kluczowe typy węzłów AST

TypeScript Compiler API definiuje różne typy węzłów AST, z których każdy reprezentuje inną konstrukcję składniową. Oto kilka typowych typów węzłów:

• SourceFile: Reprezentuje cały plik TypeScript.
• FunctionDeclaration: Reprezentuje definicję funkcji.
• VariableDeclaration: Reprezentuje deklarację zmiennej.
• Identifier: Reprezentuje identyfikator (np. nazwę zmiennej, nazwę funkcji).
• StringLiteral: Reprezentuje literal ciągu znaków.
• CallExpression: Reprezentuje wywołanie funkcji.
• ReturnStatement: Reprezentuje instrukcję return.

Każdy typ węzła ma właściwości, które dostarczają informacji o odpowiadającym elemencie kodu. Na przykład węzeł `FunctionDeclaration` może mieć właściwości dla swojej nazwy, parametrów, typu zwracanego i treści.

Rozpoczęcie pracy z Compiler API

Aby rozpocząć korzystanie z Compiler API, musisz zainstalować TypeScript i mieć podstawową wiedzę na temat składni TypeScript. Oto prosty przykład, który pokazuje, jak odczytać plik TypeScript i wydrukować jego 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);

Wyjaśnienie:

1. Import modułów: Importuje moduł `typescript` i moduł `fs` do operacji na systemie plików.
2. Odczyt pliku źródłowego: Odczytuje zawartość pliku TypeScript o nazwie `example.ts`. Musisz utworzyć plik `example.ts`, aby to zadziałało.
3. Create SourceFile: Tworzy obiekt `SourceFile`, który reprezentuje korzeń AST. Funkcja `ts.createSourceFile` analizuje kod źródłowy i generuje AST.
4. Print AST: Definiuje rekurencyjną funkcję `printAST`, która przechodzi przez AST i drukuje rodzaj każdego węzła.
5. Call printAST: Wywołuje `printAST`, aby rozpocząć drukowanie AST z korzenia węzła `SourceFile`.

Aby uruchomić ten kod, zapisz go jako plik `.ts` (np. `ast-example.ts`), utwórz plik `example.ts` z kodem TypeScript, a następnie skompiluj i uruchom kod:

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

Spowoduje to wydrukowanie AST pliku `example.ts` w konsoli. Dane wyjściowe pokażą hierarchię węzłów i ich typy. Na przykład może pokazywać `FunctionDeclaration`, `Identifier`, `Block` i inne typy węzłów.

Przechodzenie przez AST

Compiler API oferuje kilka sposobów na przechodzenie przez AST. Najprostszym z nich jest użycie metody `forEachChild`, jak pokazano w poprzednim przykładzie. Ta metoda odwiedza każdy węzeł podrzędny danego węzła.

W przypadku bardziej złożonych scenariuszy przechodzenia można użyć wzorca `Visitor`. Wizytator to obiekt, który definiuje metody, które mają być wywoływane dla określonych typów węzłów. Pozwala to na dostosowanie procesu przechodzenia i wykonywanie działań na podstawie typu węzła.

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(`Znaleziono identyfikator: ${node.text}`);
    }

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

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

Wyjaśnienie:

1. Klasa IdentifierVisitor: Definiuje klasę `IdentifierVisitor` z metodą `visit`.
2. Metoda Visit: Metoda `visit` sprawdza, czy bieżący węzeł jest `Identifier`. Jeśli tak, drukuje tekst identyfikatora. Następnie rekurencyjnie wywołuje `ts.forEachChild`, aby odwiedzić węzły podrzędne.
3. Utwórz wizytatora: Tworzy instancję `IdentifierVisitor`.
4. Rozpocznij przechodzenie: Wywołuje metodę `visit` na `SourceFile`, aby rozpocząć przechodzenie.

Ten przykład pokazuje, jak znaleźć wszystkie identyfikatory w AST. Możesz dostosować ten wzorzec, aby znaleźć inne typy węzłów i wykonywać różne czynności.

Transformowanie AST

Prawdziwa moc Compiler API tkwi w jego zdolności do transformowania AST. Możesz modyfikować AST, aby zmienić strukturę i zachowanie swojego kodu. Jest to podstawa narzędzi do refaktoryzacji kodu, generatorów kodu i innych zaawansowanych narzędzi.

Aby przekształcić AST, musisz użyć funkcji `ts.transform`. Ta funkcja przyjmuje plik `SourceFile` i listę funkcji `TransformerFactory`. `TransformerFactory` to funkcja, która przyjmuje `TransformationContext` i zwraca funkcję `Transformer`. Funkcja `Transformer` jest odpowiedzialna za odwiedzanie i transformowanie węzłów w AST.

Oto prosty przykład, który pokazuje, jak dodać komentarz na początku pliku 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)) {
        // Utwórz komentarz wiodący
        const comment = ts.addSyntheticLeadingComment(
          node,
          ts.SyntaxKind.MultiLineCommentTrivia,
          " Ten plik został automatycznie przekształcony ",
          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);

Wyjaśnienie:

1. TransformerFactory: Definiuje funkcję `TransformerFactory`, która zwraca funkcję `Transformer`.
2. Transformer: Funkcja `Transformer` sprawdza, czy bieżący węzeł jest `SourceFile`. Jeśli tak, dodaje wiodący komentarz do węzła za pomocą `ts.addSyntheticLeadingComment`.
3. ts.transform: Wywołuje `ts.transform`, aby zastosować transformację do `SourceFile`.
4. Drukarka: Tworzy obiekt `Printer` do generowania kodu z przekształconego AST.
5. Drukuj i zapisz: Drukuje przekształcony kod i zapisuje go w nowym pliku o nazwie `example.transformed.ts`.

Ten przykład pokazuje prostą transformację, ale możesz użyć tego samego wzorca do wykonywania bardziej złożonych transformacji, takich jak refaktoryzacja kodu, dodawanie instrukcji rejestrowania lub generowanie dokumentacji.

Zaawansowane techniki transformacji

Oto kilka zaawansowanych technik transformacji, których możesz użyć z Compiler API:

• Tworzenie nowych węzłów: Użyj funkcji `ts.createXXX`, aby utworzyć nowe węzły AST. Na przykład `ts.createVariableDeclaration` tworzy nowy węzeł deklaracji zmiennej.
• Zastępowanie węzłów: Zastąp istniejące węzły nowymi węzłami za pomocą funkcji `ts.visitEachChild`.
• Dodawanie węzłów: Dodaj nowe węzły do AST za pomocą funkcji `ts.updateXXX`. Na przykład `ts.updateBlock` aktualizuje instrukcję bloku nowymi instrukcjami.
• Usuwanie węzłów: Usuń węzły z AST, zwracając `undefined` z funkcji transformer.

Generacja kodu

Po przekształceniu AST musisz wygenerować z niego kod. Compiler API udostępnia w tym celu obiekt `Printer`. `Printer` przyjmuje AST i generuje reprezentację ciągu znaków kodu.

Funkcja `ts.createPrinter` tworzy obiekt `Printer`. Możesz skonfigurować drukarkę za pomocą różnych opcji, takich jak znak nowej linii do użycia i czy emitować komentarze.

Metoda `printer.printFile` przyjmuje plik `SourceFile` i zwraca reprezentację ciągu znaków kodu. Następnie możesz zapisać ten ciąg znaków do pliku.

Praktyczne zastosowania Compiler API

TypeScript Compiler API ma liczne praktyczne zastosowania w tworzeniu oprogramowania. Oto kilka przykładów:

• Linters: Twórz niestandardowe linters, aby wymusić standardy kodowania i zidentyfikować potencjalne problemy w kodzie.
• Formatery kodu: Twórz formatery kodu, aby automatycznie formatować kod zgodnie z określonym stylem.
• Analizatory statyczne: Opracowuj analizatory statyczne do wykrywania błędów, luk w zabezpieczeniach i wąskich gardeł wydajności w kodzie.
• Generatory kodu: Generuj kod z szablonów lub innych danych wejściowych, automatyzując powtarzalne zadania i redukując kod szablonowy. Na przykład generowanie klientów API lub schematów bazy danych z pliku opisu.
• Narzędzia do refaktoryzacji: Twórz narzędzia do refaktoryzacji, aby automatycznie zmieniać nazwy zmiennych, wyodrębniać funkcje lub przenosić kod między plikami.
• Internacjonalizacja (i18n) Automatyzacja: Automatycznie wyodrębniaj ciągi znaków do przetłumaczenia z kodu TypeScript i generuj pliki lokalizacyjne dla różnych języków. Na przykład narzędzie może skanować kod w poszukiwaniu ciągów przekazywanych do funkcji `translate()` i automatycznie dodawać je do pliku zasobów tłumaczeniowych.

Przykład: Budowanie prostego linera

Stwórzmy prosty linter, który sprawdza nieużywane zmienne w kodzie TypeScript. Ten linter zidentyfikuje zmienne, które są zadeklarowane, ale nigdy nie używane.

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("Nieużywane zmienne:");
  unusedVariables.forEach(variable => console.log(`- ${variable}`));
} else {
  console.log("Nie znaleziono nieużywanych zmiennych.");
}

Wyjaśnienie:

1. Funkcja findUnusedVariables: Definiuje funkcję `findUnusedVariables`, która jako dane wejściowe przyjmuje `SourceFile`.
2. Zestaw usedVariables: Tworzy `Set`, aby przechowywać nazwy używanych zmiennych.
3. Funkcja visit: Definiuje rekurencyjną funkcję `visit`, która przechodzi przez AST i dodaje nazwy wszystkich identyfikatorów do zestawu `usedVariables`.
4. Funkcja checkVariableDeclaration: Definiuje rekurencyjną funkcję `checkVariableDeclaration`, która sprawdza, czy deklaracja zmiennej jest nieużywana. Jeśli tak, dodaje nazwę zmiennej do tablicy `unusedVariables`.
5. Zwróć unusedVariables: Zwraca tablicę zawierającą nazwy wszelkich nieużywanych zmiennych.
6. Dane wyjściowe: Drukuje nieużywane zmienne w konsoli.

Ten przykład pokazuje prosty linter. Możesz go rozszerzyć, aby sprawdzać inne standardy kodowania i identyfikować inne potencjalne problemy w kodzie. Na przykład możesz sprawdzać nieużywane importy, zbyt złożone funkcje lub potencjalne luki w zabezpieczeniach. Kluczem jest zrozumienie, jak przechodzić przez AST i identyfikować określone typy węzłów, które Cię interesują.

Najlepsze praktyki i uwagi

• Zrozumienie AST: Poświęć czas na zrozumienie struktury AST. Użyj narzędzi takich jak AST explorer, aby zwizualizować AST swojego kodu.
• Używaj strażników typów: Używaj strażników typów (`ts.isXXX`), aby upewnić się, że pracujesz z prawidłowymi typami węzłów.
• Rozważ wydajność: Transformacje AST mogą być kosztowne obliczeniowo. Zoptymalizuj swój kod, aby zminimalizować liczbę odwiedzanych i transformowanych węzłów.
• Obsługa błędów: Obsługuj błędy w sposób elegancki. Compiler API może zgłaszać wyjątki, jeśli spróbujesz wykonać nieprawidłowe operacje na AST.
• Testuj dokładnie: Testuj swoje transformacje dokładnie, aby upewnić się, że dają pożądane rezultaty i nie wprowadzają nowych błędów.
• Używaj istniejących bibliotek: Rozważ użycie istniejących bibliotek, które zapewniają bardziej zaawansowane abstrakcje nad Compiler API. Biblioteki te mogą uprościć typowe zadania i zmniejszyć ilość kodu, który musisz napisać. Przykłady obejmują `ts-morph` i `typescript-eslint`.

Wniosek

TypeScript Compiler API to potężne narzędzie do budowania zaawansowanych narzędzi programistycznych. Zrozumienie, jak pracować z AST, pozwala na tworzenie linters, formatterów kodu, analizatorów statycznych i innych narzędzi, które poprawiają jakość kodu, automatyzują powtarzalne zadania i zwiększają produktywność programistów. Chociaż API może być złożone, korzyści z jego opanowania są znaczące. Ten kompleksowy przewodnik stanowi podstawę do eksploracji i skutecznego wykorzystania Compiler API w swoich projektach. Pamiętaj, aby wykorzystywać narzędzia takie jak AST Explorer, dokładnie obsługiwać typy węzłów i dokładnie testować swoje transformacje. Dzięki praktyce i zaangażowaniu możesz odblokować pełny potencjał TypeScript Compiler API i budować innowacyjne rozwiązania dla krajobrazu tworzenia oprogramowania.

Dalsza eksploracja:

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