Розкриття інновацій: Розробка власних інструментів за допомогою TypeScript Compiler API

У постійно мінливому ландшафті розробки програмного забезпечення ефективність та точність є першочерговими. Зі зростанням масштабів та складності проєктів, потреба в індивідуальних рішеннях для оптимізації робочих процесів, дотримання стандартів кодування та автоматизації рутинних завдань стає все більш критичною. Хоча сам TypeScript є потужною мовою для створення надійних та масштабованих застосунків, його справжній потенціал для розробки власних інструментів розкривається завдяки його складному TypeScript Compiler API.

Цей допис у блозі глибоко зануриться в можливості TypeScript Compiler API, надаючи розробникам по всьому світу інструменти для створення індивідуальних рішень, які можуть революціонізувати їхні процеси розробки. Ми розглянемо, що таке API, чому вам варто розглянути його використання, а також надамо практичні поради та приклади, щоб допомогти вам розпочати свій шлях у розробці власних інструментів.

Що таке TypeScript Compiler API?

По своїй суті, TypeScript Compiler API – це програмний інтерфейс, який дозволяє взаємодіяти з самим компілятором TypeScript. Уявіть це як спосіб використання тієї ж інтелектуальної системи, яку TypeScript використовує для розуміння, аналізу та перетворення вашого коду, але для ваших власних, індивідуальних цілей.

Компілятор працює шляхом розбору вашого TypeScript-коду в Абстрактне Синтаксичне Дерево (AST). AST – це деревоподібне представлення структури вашого коду, де кожен вузол представляє конструкцію у вашому коді, таку як оголошення функції, присвоєння змінної або вираз. Compiler API надає інструменти для:

• Розбір коду TypeScript: Перетворення вихідних файлів в AST.
• Обхід та аналіз AST: Навігація структурою коду для ідентифікації конкретних шаблонів, синтаксису або семантичної інформації.
• Перетворення AST: Зміна, додавання або видалення вузлів в AST для переписування коду або генерації нового коду.
• Перевірка типів коду: Розуміння типів та взаємозв'язків між різними частинами вашої кодової бази.
• Генерація коду: Створення JavaScript, файлів оголошень (.d.ts) або інших форматів виводу з AST.

Цей потужний набір можливостей формує основу багатьох існуючих інструментів TypeScript, включаючи сам компілятор TypeScript, лінтери, такі як TSLint (який зараз здебільшого замінено на ESLint з підтримкою TypeScript), та функції IDE, такі як автодоповнення коду, рефакторинг та підсвічування помилок.

Навіщо розробляти власні інструменти за допомогою TypeScript Compiler API?

Для команд розробників по всьому світу впровадження власних інструментів, створених за допомогою Compiler API, може призвести до значних переваг:

1. Покращена якість та послідовність коду

Різні регіони та команди можуть мати різні інтерпретації найкращих практик. Власні інструменти можуть забезпечувати дотримання конкретних стандартів кодування, шаблонів та архітектурних рекомендацій, які є вирішальними для особливих потреб вашої організації. Це призводить до більш підтримуваних, читабельних та надійних кодових баз у різноманітних проєктах.

2. Підвищена продуктивність розробників

Повторювані завдання, такі як генерація шаблонного коду, міграція кодових баз або застосування складних перетворень, можуть бути автоматизовані. Це дозволяє розробникам зосередитися на основній логіці та інноваціях, а не на рутинній, схильній до помилок ручній роботі.

3. Індивідуальний статичний аналіз

Хоча загальні лінтери виявляють багато поширених проблем, вони можуть не враховувати унікальні складності або доменні вимоги вашої програми. Власні інструменти статичного аналізу можуть ідентифікувати та позначати потенційні помилки, вузькі місця у продуктивності або вразливості безпеки, які є специфічними для архітектури та бізнес-логіки вашого проєкту.

4. Розширена генерація коду

API дозволяє генерувати складні структури коду на основі певних критеріїв. Це безцінно для створення типобезпечних API, моделей даних або компонентів користувацького інтерфейсу з декларативних визначень, що зменшує ручну реалізацію та потенційні помилки.

5. Оптимізований рефакторинг та міграції

Великомасштабні зусилля з рефакторингу або міграції між різними версіями бібліотек чи фреймворків можуть бути надзвичайно складними. Власні інструменти можуть автоматизувати багато з цих змін, забезпечуючи послідовність та мінімізуючи ризик введення регресій.

6. Глибша інтеграція з IDE

Крім стандартних функцій, API дозволяє створювати вузькоспеціалізовані плагіни для IDE, які пропонують контекстно-орієнтовану допомогу, індивідуальні швидкі виправлення та інтелектуальні підказки коду, адаптовані до конкретної предметної області вашого проєкту.

Початок роботи: Основні концепції

Щоб розпочати розробку за допомогою TypeScript Compiler API, вам знадобиться глибоке розуміння кількох ключових концепцій:

1. Програма TypeScript

Програма (Program) представляє колекцію вихідних файлів та опцій компілятора, які компілюються разом. Це центральний об'єкт, з яким ви будете взаємодіяти для доступу до семантичної інформації про весь ваш проєкт.

Ви можете створити Програму таким чином:

            
import * as ts from 'typescript';

const fileNames: string[] = ['src/index.ts', 'src/utils.ts'];
const compilerOptions: ts.CompilerOptions = {
  target: ts.ScriptTarget.ESNext,
  module: ts.ModuleKind.CommonJS,
};

const program = ts.createProgram(fileNames, compilerOptions);

            

              
                Copy
              
            
          

2. Вихідні файли та перевірка типів

З Програми ви можете отримати доступ до окремих об'єктів SourceFile, які представляють розібране AST кожного файлу TypeScript. TypeChecker – це ключовий компонент, який надає інформацію для семантичного аналізу, таку як виведення типів, розв'язання символів та перевірка сумісності типів.

            
const checker = program.getTypeChecker();

program.getSourceFiles().forEach(sourceFile => {
  if (!sourceFile.isDeclarationFile) {
    // Process this source file
    ts.forEachChild(sourceFile, node => {
      // Analyze each node
    });
  }
});

            

              
                Copy
              
            
          

3. Обхід Абстрактного Синтаксичного Дерева (AST)

Отримавши SourceFile, ви будете навігувати його AST. Найпоширеніший спосіб зробити це – використовувати ts.forEachChild(), який рекурсивно відвідує всіх прямих нащадків заданого вузла. Для більш складних сценаріїв ви можете реалізувати власні шаблони відвідувачів або використовувати бібліотеки, що спрощують обхід AST.

Розуміння різних SyntaxKind-ів є важливим для ідентифікації конкретних структур коду. Наприклад:

• ts.SyntaxKind.FunctionDeclaration: Представляє оголошення функції.
• ts.SyntaxKind.Identifier: Представляє ім'я змінної, ім'я функції тощо.
• ts.SyntaxKind.PropertyAccessExpression: Представляє доступ до властивості (наприклад, obj.prop).

4. Семантичний аналіз за допомогою перевірки типів

TypeChecker – це місце, де відбувається справжня магія семантичного розуміння. Ви можете використовувати його для:

• Отримати символ, пов'язаний з вузлом (наприклад, функція, що викликається).
• Визначити тип виразу.
• Перевірити сумісність типів.
• Розв'язати посилання на символи.

            
// Example: Finding all function declarations

function findFunctionDeclarations(sourceFile: ts.SourceFile) {
  const functions: ts.FunctionDeclaration[] = [];

  function visit(node: ts.Node) {
    if (ts.isFunctionDeclaration(node)) {
      functions.push(node);
    }
    ts.forEachChild(node, visit);
  }

  visit(sourceFile);
  return functions;
}

            

              
                Copy
              
            
          

5. Перетворення коду

Compiler API також дозволяє перетворювати AST. Це робиться за допомогою функції ts.transform(), яка приймає ваше AST та набір відвідувачів (visitors), що визначають, як перетворювати вузли. Потім ви можете згенерувати перетворене AST назад у код.

            
import *s ts from 'typescript';

const sourceCode = 'function greet() { console.log("Hello"); }';
const sourceFile = ts.createSourceFile('temp.ts', sourceCode, ts.ScriptTarget.ESNext, true);

const visitor: ts.Visitor = (node) => {
  if (ts.isIdentifier(node) && node.text === 'console') {
    // Replace 'console' with 'customLogger'
    return ts.factory.createIdentifier('customLogger');
  }
  return ts.visitEachChild(node, visitor, ts.nullTransformationContext);
};

const transformationResult = ts.transform(sourceFile, [
  (context) => {
    const visitor = (node: ts.Node): ts.Node => {
      if (ts.isIdentifier(node) && node.text === 'console') {
        return ts.factory.createIdentifier('customLogger');
      }
      return ts.visitEachChild(node, visitor, context);
    };
    return visitor;
  }
]);

const printer = ts.createPrinter();
const transformedCode = printer.printFile(transformationResult.transformed[0]);
console.log(transformedCode);
// Output: function greet() { customLogger.log("Hello"); }

            

              
                Copy
              
            
          

Практичні застосування та варіанти використання

Давайте розглянемо кілька реальних сценаріїв, де TypeScript Compiler API проявляє себе найкраще:

1. Забезпечення дотримання правил іменування

Команди можуть розробляти інструменти для забезпечення послідовних правил іменування змінних, функцій, класів та модулів. Це особливо корисно у великих, розподілених командах для підтримки єдиної кодової бази.

Приклад: Інструмент, який позначає будь-яке ім'я компонента, що не відповідає конвенції PascalCase при експорті з модуля React.

            
// Imagine this is part of a linter rule

function checkComponentName(node: ts.ExportDeclaration, checker: ts.TypeChecker) {
  if (ts.isClassDeclaration(node.exportClause) || ts.isFunctionDeclaration(node.exportClause)) {
    const name = node.exportClause.name;
    if (name && !/^[A-Z]/.test(name.text)) {
      // Report error: Component name must start with an uppercase letter
      console.error(`Invalid component name: ${name.text}`);
    }
  }
}

            

              
                Copy
              
            
          

2. Автоматизована генерація коду для API та моделей даних

Якщо у вас є чітка схема API або визначення структури даних (наприклад, у OpenAPI, схемі GraphQL або навіть добре визначений набір інтерфейсів TypeScript), ви можете написати інструменти для генерації типобезпечних клієнтів, заглушок сервера або логіки валідації даних.

Приклад: Генерація набору інтерфейсів TypeScript зі специфікації OpenAPI для забезпечення узгодженості між контрактами фронтенду та бекенду.

Це складне завдання, що включає розбір специфікації OpenAPI (часто JSON або YAML) і подальше використання Compiler API для програмного створення ts.InterfaceDeclaration, ts.TypeAliasDeclaration та інших вузлів AST.

3. Спрощення управління залежностями

Інструменти можуть аналізувати оператори імпорту для виявлення невикористаних залежностей, пропонувати псевдоніми шляхів модуля або навіть допомагати автоматизувати оновлення, розуміючи граф імпорту.

Приклад: Скрипт, який сканує на наявність невикористаних імпортів і пропонує видалити їх автоматично.

            
// Simplified example of finding unused imports

function findUnusedImports(sourceFile: ts.SourceFile, program: ts.Program) {
  const checker = program.getTypeChecker();
  const imports: Array<{ node: ts.ImportDeclaration, isUsed: boolean }> = [];

  ts.forEachChild(sourceFile, node => {
    if (ts.isImportDeclaration(node)) {
      imports.push({ node: node, isUsed: false });
    }
  });

  ts.forEachChild(sourceFile, (node) => {
    if (ts.isIdentifier(node)) {
      const symbol = checker.getSymbolAtLocation(node);
      if (symbol) {
        // Check if this identifier is part of an imported module
        // This requires more sophisticated symbol resolution logic
      }
    }
  });

  // Logic to mark imports as used or unused based on symbol resolution
  return imports.filter(imp => !imp.isUsed).map(imp => imp.node);
}

            

              
                Copy
              
            
          

4. Виявлення та міграція застарілих API

Оскільки бібліотеки розвиваються, вони часто оголошують старі API застарілими. Власні інструменти можуть систематично сканувати вашу кодову базу на використання цих застарілих API та автоматично замінювати їх сучасними еквівалентами, забезпечуючи актуальність ваших проєктів.

Приклад: Заміна всіх екземплярів застарілого виклику функції на новий, з можливим коригуванням аргументів.

            
// Example: Replacing a deprecated function

const visitor: ts.Visitor = (node) => {
  if (
    ts.isCallExpression(node) &&
    ts.isIdentifier(node.expression) &&
    node.expression.text === 'oldDeprecatedFunction'
  ) {
    // Construct a new CallExpression for the new function
    const newCall = ts.factory.updateCallExpression(
      node,
      ts.factory.createIdentifier('newModernFunction'),
      node.typeArguments,
      [...node.arguments, ts.factory.createLiteral('migration-tag')] // Adding a new argument
    );
    return newCall;
  }
  return ts.visitEachChild(node, visitor, ts.nullTransformationContext);
};

            

              
                Copy
              
            
          

5. Покращення аудитів безпеки

Можна створювати власні інструменти для виявлення поширених антипатернів безпеки, таких як небезпечне пряме використання API, схильних до атак ін'єкцій, або неналежна санітаризація вхідних даних користувача.

Приклад: Інструмент, який позначає пряме використання eval() або інших потенційно небезпечних функцій без належних перевірок санітаризації.

6. Транспіляція доменних мов (DSL)

Для організацій, які розробляють власні внутрішні DSL, TypeScript Compiler API можна використовувати для транспіляції цих DSL у виконуваний TypeScript або JavaScript, що дозволяє їм використовувати екосистему TypeScript.

Створення першого власного інструменту

Давайте окреслимо кроки для створення базового власного інструменту.

Крок 1: Налаштуйте своє середовище

Вам знадобляться Node.js та npm (або Yarn). Встановіть пакет TypeScript:

            
npm install -g typescript
# Or for a local project
npm install --save-dev typescript

            

              
                Copy
              
            
          

Ви також захочете мати файл TypeScript для експериментів. Наприклад, створіть example.ts:

            
function sayHello(name: string): void {
  const message = `Hello, ${name}!`;
  console.log(message);
}

sayHello('World');

            

              
                Copy
              
            
          

Крок 2: Напишіть свій скрипт

Створіть новий файл TypeScript для свого інструменту, наприклад, analyze.ts.

            
import * as ts from 'typescript';

const fileName = 'example.ts'; // The file you want to analyze
const compilerOptions: ts.CompilerOptions = {
  target: ts.ScriptTarget.ESNext,
  module: ts.ModuleKind.CommonJS,
};

// 1. Create a Program
const program = ts.createProgram([fileName], compilerOptions);

// 2. Get the SourceFile for your target file
const sourceFile = program.getSourceFile(fileName);

if (!sourceFile) {
  console.error(`Could not find source file: ${fileName}`);
  process.exit(1);
}

// 3. Traverse the AST to find specific nodes
console.log(`Analyzing file: ${sourceFile.fileName}\n`);

ts.forEachChild(sourceFile, (node) => {
  // Check for function declarations
  if (ts.isFunctionDeclaration(node) && node.name) {
    console.log(`Found function: ${node.name.text}`);

    // Check parameters
    if (node.parameters.length > 0) {
      console.log(`  Parameters: ${node.parameters.map(p => p.name.getText()).join(', ')}`);
    }

    // Check return type annotation
    if (node.type) {
      console.log(`  Return type: ${node.type.getText()}`);
    } else {
      console.warn(`  Function ${node.name.text} has no explicit return type annotation.`);
    }
  }

  // Check for console.log statements
  if (
    ts.isCallExpression(node) &&
    ts.isPropertyAccessExpression(node.expression) &&
    node.expression.name.text === 'log' &&
    ts.isIdentifier(node.expression.expression) &&
    node.expression.expression.text === 'console'
  ) {
    console.log(`  Found console.log statement.`);
  }
});

            

              
                Copy
              
            
          

Крок 3: Скомпілюйте та запустіть свій інструмент

Скомпілюйте свій аналітичний скрипт:

            
tsc analyze.ts

            

              
                Copy
              
            
          

Запустіть скомпільований JavaScript-файл:

            
node analyze.js

            

              
                Copy
              
            
          

Ви маєте побачити вивід, подібний до цього:

            
Analyzing file: example.ts

Found function: sayHello
  Parameters: name
  Return type: void
  Found console.log statement.

            

              
                Copy
              
            
          

Розширені техніки та міркування

1. Відвідувачі та Трансформери

Для більш складних перетворень вам знадобиться реалізувати надійні шаблони відвідувачів. Функція ts.transform() у поєднанні з власними функціями-відвідувачами є стандартним способом переписування AST. Не забувайте керувати створенням нових вузлів за допомогою модуля ts.factory, який надає фабричні функції для створення вузлів AST.

2. Діагностика та звітність

Для лінтерів та інструментів якості коду створення точних повідомлень про помилки та діагностики є вирішальним. Compiler API надає структури для створення об'єктів ts.Diagnostic, які можна використовувати для повідомлення про проблеми з шляхами до файлів, номерами рядків та рівнем серйозності.

3. Інтеграція з системами збірки

Власні інструменти можуть бути інтегровані в існуючі конвеєри збірки (наприклад, Webpack, Rollup, Vite) за допомогою плагінів. Це гарантує, що ваші власні перевірки та перетворення застосовуються автоматично під час процесу збірки.

4. Використання бібліотеки `ts-morph`

Пряма робота з TypeScript Compiler API може бути багатослівною. Бібліотеки, такі як ts-morph, надають більш ергономічний та високорівневий API для маніпулювання кодом TypeScript. Вони спрощують поширені завдання, такі як додавання методів до класів, доступ до властивостей та створення нових файлів.

Приклад з `ts-morph` (настійно рекомендується для складних операцій):

            
import { Project } from 'ts-morph';

const project = new Project();
project.addSourceFileAtPath('example.ts');

const sourceFile = project.getSourceFileOrThrow('example.ts');

// Add a new parameter to the sayHello function
sourceFile.getFunctionOrThrow('sayHello').addParameter({ name: 'greeting', type: 'string' });

// Add a new console.log statement
sourceFile.addStatements('console.log(\'Migration complete!\');');

// Save the changes back to the file
project.saveSync();

console.log('File modified successfully!');

            

              
                Copy
              
            
          

5. Міркування щодо продуктивності

При роботі з великими кодовими базами продуктивність ваших власних інструментів є важливою. Ефективний обхід AST, уникнення надлишкових операцій та використання механізмів кешування компілятора є ключовими. Профілювання ваших інструментів може допомогти виявити вузькі місця.

Глобальні міркування щодо розробки

При створенні інструментів для глобальної аудиторії важливі кілька факторів:

• Локалізація: Повідомлення про помилки та звіти повинні легко локалізуватися.
• Інтернаціоналізація: Переконайтеся, що ваші інструменти можуть обробляти різні набори символів та мовні нюанси в коментарях коду або рядкових літералах, якщо ваш аналіз поширюється на них.
• Часові пояси та затримки: Для інструментів, що інтегруються з CI/CD конвеєрами, враховуйте вплив різних часових поясів на час збірки та звітність.
• Культурні нюанси: Хоча це менш безпосередньо стосується аналізу коду, пам'ятайте про те, як правила іменування або стилі коду можуть бути обумовлені регіональними уподобаннями, та розробляйте свої інструменти гнучкими.
• Документація: Чітка, всебічна документація англійською мовою є важливою, і розгляньте можливість надання перекладів, якщо дозволяють ресурси.

Висновок

TypeScript Compiler API – це потужний, хоча іноді складний, набір інструментів, що пропонує величезний потенціал для створення власних рішень в екосистемі TypeScript. Розуміючи його основні концепції — Програми, SourceFiles, AST та TypeChecker — розробники можуть створювати інструменти, які підвищують якість коду, збільшують продуктивність та автоматизують складні завдання.

Незалежно від того, чи прагнете ви впровадити унікальні стандарти кодування, генерувати складні структури коду або спростити великомасштабний рефакторинг, Compiler API надає основу. Для багатьох бібліотеки, такі як ts-morph, можуть значно спростити процес розробки. Впровадження розробки власних інструментів за допомогою TypeScript Compiler API є стратегічною інвестицією, яка може принести значні прибутки, стимулюючи інновації та ефективність у ваших глобальних командах розробки.

Почніть з малого, експериментуйте з базовим обходом та аналізом AST, і поступово створюйте більш складні інструменти. Шлях освоєння TypeScript Compiler API є винагороджуючим, що веде до більш надійних, підтримуваних та ефективних практик розробки програмного забезпечення.