TypeScript Compiler API: Овладяване на AST манипулацията и трансформацията на код

TypeScript Compiler API предоставя мощен интерфейс за анализиране, манипулиране и генериране на TypeScript и JavaScript код. В основата му лежи Абстрактното синтаксисно дърво (AST), структурирано представяне на вашия изходен код. Разбирането на работата с AST отваря възможности за изграждане на усъвършенствани инструменти, като линтъри, форматиращи кодове, статични анализатори и персонализирани генератори на код.

Какво представлява TypeScript Compiler API?

TypeScript Compiler API е набор от TypeScript интерфейси и функции, които разкриват вътрешната работа на компилатора на TypeScript. Той позволява на разработчиците програмно да взаимодействат с процеса на компилация, надхвърляйки простото компилиране на код. Можете да го използвате за:

• Анализ на код: Инспектирайте структурата на кода, идентифицирайте потенциални проблеми и извлечете семантична информация.
• Трансформиране на код: Променете съществуващия код, добавете нови функции или рефакторирайте кода автоматично.
• Генериране на код: Създайте нов код от нулата въз основа на шаблони или друг вход.

Този API е от съществено значение за изграждането на сложни инструменти за разработка, които подобряват качеството на кода, автоматизират повтарящи се задачи и подобряват производителността на разработчиците.

Разбиране на абстрактното синтаксисно дърво (AST)

AST е дървовидно представяне на структурата на вашия код. Всеки възел в дървото представлява синтактична конструкция, като декларация на променлива, извикване на функция или оператор за контрол на потока. TypeScript Compiler API предоставя инструменти за обхождане на AST, инспектиране на неговите възли и модифицирането им.

Разгледайте този прост TypeScript код:

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

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

AST за този код би представлявал декларацията на функцията, оператора за връщане, литерала на шаблона, извикването на console.log и други елементи на кода. Визуализирането на AST може да бъде предизвикателство, но инструменти като AST Explorer (astexplorer.net) могат да помогнат. Тези инструменти ви позволяват да въведете код и да видите съответното AST във формат, удобен за потребителя. Използването на AST Explorer ще ви помогне да разберете какъв вид кодова структура ще манипулирате.

Основни типове AST възли

TypeScript Compiler API дефинира различни типове AST възли, всеки от които представлява различна синтактична конструкция. Ето някои често срещани типове възли:

• SourceFile: Представя цял TypeScript файл.
• FunctionDeclaration: Представя дефиниция на функция.
• VariableDeclaration: Представя декларация на променлива.
• Identifier: Представя идентификатор (например име на променлива, име на функция).
• StringLiteral: Представя стринг литерал.
• CallExpression: Представя извикване на функция.
• ReturnStatement: Представя оператор за връщане.

Всеки тип възел има свойства, които предоставят информация за съответния елемент от кода. Например, възел `FunctionDeclaration` може да има свойства за неговото име, параметри, тип на връщане и тяло.

Първи стъпки с Compiler API

За да започнете да използвате Compiler API, ще трябва да инсталирате TypeScript и да имате основно разбиране на синтаксиса на TypeScript. Ето прост пример, който демонстрира как да прочетете TypeScript файл и да отпечатате неговото 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);

Обяснение:

1. Импортиране на модули: Импортира модула `typescript` и модула `fs` за файлови системни операции.
2. Четене на изходен файл: Прочита съдържанието на TypeScript файл, наречен `example.ts`. Ще трябва да създадете файл `example.ts`, за да работи това.
3. Създаване на SourceFile: Създава обект `SourceFile`, който представлява корена на AST. Функцията `ts.createSourceFile` анализира изходния код и генерира AST.
4. Печат на AST: Дефинира рекурсивна функция `printAST`, която обхожда AST и отпечатва вида на всеки възел.
5. Извикване на printAST: Извиква `printAST` за да започне отпечатването на AST от корена `SourceFile` възел.

За да стартирате този код, запазете го като `.ts` файл (напр. `ast-example.ts`), създайте файл `example.ts` с някакъв TypeScript код и след това компилирайте и стартирайте кода:

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

Това ще отпечата AST на вашия файл `example.ts` в конзолата. Изходът ще покаже йерархията на възлите и техните типове. Например, може да покаже `FunctionDeclaration`, `Identifier`, `Block` и други типове възли.

Обхождане на AST

Compiler API предоставя няколко начина за обхождане на AST. Най-простият е използването на метода `forEachChild`, както е показано в предишния пример. Този метод посещава всеки дъщерен възел на даден възел.

За по-сложни сценарии на обхождане можете да използвате модел `Visitor`. Посетителят е обект, който дефинира методи, които да бъдат извикани за конкретни типове възли. Това ви позволява да персонализирате процеса на обхождане и да извършвате действия въз основа на типа на възела.

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

Обяснение:

1. IdentifierVisitor Клас: Дефинира клас `IdentifierVisitor` с метод `visit`.
2. Метод Visit: Методът `visit` проверява дали текущият възел е `Identifier`. Ако е, отпечатва текста на идентификатора. След това рекурсивно извиква `ts.forEachChild`, за да посети дъщерните възли.
3. Създаване на Visitor: Създава инстанция на `IdentifierVisitor`.
4. Започване на обхождане: Извиква метода `visit` на `SourceFile`, за да започне обхождането.

Този пример демонстрира как да намерите всички идентификатори в AST. Можете да адаптирате този модел, за да намерите други типове възли и да извършите различни действия.

Трансформиране на AST

Истинската сила на Compiler API се крие в способността му да трансформира AST. Можете да промените AST, за да промените структурата и поведението на вашия код. Това е основата за инструменти за рефакториране на код, генератори на код и други усъвършенствани инструменти.

За да трансформирате AST, ще трябва да използвате функцията `ts.transform`. Тази функция приема `SourceFile` и списък с функции `TransformerFactory`. `TransformerFactory` е функция, която приема `TransformationContext` и връща функция `Transformer`. Функция `Transformer` отговаря за посещаването и трансформирането на възли в AST.

Ето прост пример, който демонстрира как да добавите коментар в началото на 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);

Обяснение:

1. TransformerFactory: Дефинира функция `TransformerFactory`, която връща функция `Transformer`.
2. Transformer: Функция `Transformer` проверява дали текущият възел е `SourceFile`. Ако е, той добавя водещ коментар към възела, използвайки `ts.addSyntheticLeadingComment`.
3. ts.transform: Извиква `ts.transform`, за да приложи трансформацията към `SourceFile`.
4. Printer: Създава обект `Printer`, за да генерира код от трансформираното AST.
5. Печат и запис: Отпечатва трансформирания код и го записва в нов файл, наречен `example.transformed.ts`.

Този пример демонстрира проста трансформация, но можете да използвате същия модел, за да извършвате по-сложни трансформации, като например рефакториране на код, добавяне на изявления за регистриране или генериране на документация.

Усъвършенствани техники за трансформация

Ето някои усъвършенствани техники за трансформация, които можете да използвате с Compiler API:

• Създаване на нови възли: Използвайте функциите `ts.createXXX`, за да създадете нови AST възли. Например, `ts.createVariableDeclaration` създава нов възел за декларация на променлива.
• Замяна на възли: Заменете съществуващите възли с нови възли, използвайки функцията `ts.visitEachChild`.
• Добавяне на възли: Добавете нови възли към AST, използвайки функциите `ts.updateXXX`. Например, `ts.updateBlock` актуализира оператор на блок с нови оператори.
• Премахване на възли: Премахнете възли от AST, като върнете `undefined` от функцията за трансформация.

Генериране на код

След трансформиране на AST, ще трябва да генерирате код от него. Compiler API предоставя обект `Printer` за тази цел. `Printer` приема AST и генерира текстово представяне на кода.

Функцията `ts.createPrinter` създава обект `Printer`. Можете да конфигурирате принтера с различни опции, като например символа за нов ред, който да се използва, и дали да се издават коментари.

Методът `printer.printFile` приема `SourceFile` и връща текстово представяне на кода. След това можете да запишете този низ във файл.

Практически приложения на Compiler API

TypeScript Compiler API има многобройни практически приложения в разработката на софтуер. Ето няколко примера:

• Линтъри: Създайте персонализирани линтъри, за да наложите стандарти за кодиране и да идентифицирате потенциални проблеми във вашия код.
• Форматиращи кодове: Създайте форматиращи кодове, за да форматирате автоматично кода си според конкретен стил на ръководство.
• Статични анализатори: Разработете статични анализатори за откриване на грешки, уязвимости в сигурността и тесни места в производителността във вашия код.
• Генератори на код: Генерирайте код от шаблони или друг вход, автоматизирайки повтарящи се задачи и намалявайки шаблоните на код. Например, генериране на API клиенти или схеми на бази данни от файл за описание.
• Инструменти за рефакторинг: Създайте инструменти за рефакторинг, за да преименувате автоматично променливи, да извлечете функции или да преместите код между файлове.
• Автоматизация на интернационализация (i18n): Автоматично извличайте преводими низове от вашия TypeScript код и генерирайте файлове за локализация за различни езици. Например, инструмент може да сканира код за низове, предадени на функция `translate()`, и автоматично да ги добавя към файл с ресурси за превод.

Пример: Създаване на прост линтър

Нека създадем прост линтър, който проверява за неизползвани променливи в 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
);

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

Обяснение:

1. Функция findUnusedVariables: Дефинира функция `findUnusedVariables`, която приема `SourceFile` като вход.
2. usedVariables Set: Създава `Set`, за да съхранява имената на използваните променливи.
3. Функция visit: Дефинира рекурсивна функция `visit`, която обхожда AST и добавя имената на всички идентификатори към набора `usedVariables`.
4. Функция checkVariableDeclaration: Дефинира рекурсивна функция `checkVariableDeclaration`, която проверява дали декларацията на променлива е неизползвана. Ако е, тя добавя името на променливата към масива `unusedVariables`.
5. Връщане на unusedVariables: Връща масив, съдържащ имената на всички неизползвани променливи.
6. Изход: Отпечатва неизползваните променливи в конзолата.

Този пример демонстрира прост линтър. Можете да го разширите, за да проверите за други стандарти за кодиране и да идентифицирате други потенциални проблеми във вашия код. Например, можете да проверите за неизползвани импорти, прекалено сложни функции или потенциални уязвимости в сигурността. Ключът е да разберете как да обходите AST и да идентифицирате конкретните типове възли, които ви интересуват.

Най-добри практики и съображения

• Разбиране на AST: Инвестирайте време в разбирането на структурата на AST. Използвайте инструменти като AST Explorer за визуализиране на AST на вашия код.
• Използвайте типови пазачи: Използвайте типови пазачи (`ts.isXXX`), за да се уверите, че работите с правилните типове възли.
• Обмислете производителността: AST трансформациите могат да бъдат изчислително скъпи. Оптимизирайте кода си, за да минимизирате броя на възлите, които посещавате и трансформирате.
• Обработвайте грешки: Обработвайте грешките внимателно. Compiler API може да генерира изключения, ако се опитате да извършите невалидни операции на AST.
• Тествайте обстойно: Тествайте добре вашите трансформации, за да се уверите, че те дават желаните резултати и не въвеждат нови грешки.
• Използвайте съществуващи библиотеки: Обмислете използването на съществуващи библиотеки, които предоставят абстракции на по-високо ниво над Compiler API. Тези библиотеки могат да опростят общите задачи и да намалят количеството код, който трябва да напишете. Примерите включват `ts-morph` и `typescript-eslint`.

Заключение

TypeScript Compiler API е мощен инструмент за изграждане на усъвършенствани инструменти за разработка. Като разберете как да работите с AST, можете да създавате линтъри, форматиращи кодове, статични анализатори и други инструменти, които подобряват качеството на кода, автоматизират повтарящи се задачи и подобряват производителността на разработчиците. Въпреки че API може да бъде сложен, ползите от овладяването му са значителни. Това изчерпателно ръководство предоставя основа за ефективно проучване и използване на Compiler API във вашите проекти. Не забравяйте да използвате инструменти като AST Explorer, внимателно да обработвате типовете възли и да тествате добре вашите трансформации. С практика и отдаденост можете да отключите пълния потенциал на TypeScript Compiler API и да изградите иновативни решения за пейзажа за разработка на софтуер.

Допълнително проучване:

• Документация на 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/)
• ts-morph library: [https://ts-morph.com/](https://ts-morph.com/)
• typescript-eslint: [https://typescript-eslint.io/](https://typescript-eslint.io/)