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は、関数宣言、returnステートメント、テンプレートリテラル、console.log呼び出し、およびコードのその他の要素を表します。ASTの視覚化は難しい場合がありますが、ASTエクスプローラー（astexplorer.net）などのツールが役立ちます。これらのツールを使用すると、コードを入力して、対応するASTをユーザーフレンドリーな形式で確認できます。AST Explorerを使用すると、操作するコード構造の種類を理解するのに役立ちます。

主要なASTノードタイプ

TypeScript Compiler APIは、さまざまなASTノードタイプを定義します。各ノードタイプは、異なる構文構造を表します。次に、一般的なノードタイプをいくつか示します。

• SourceFile：TypeScriptファイル全体を表します。
• FunctionDeclaration：関数定義を表します。
• VariableDeclaration：変数宣言を表します。
• Identifier：識別子（変数名、関数名など）を表します。
• StringLiteral：文字列リテラルを表します。
• CallExpression：関数呼び出しを表します。
• ReturnStatement：returnステートメントを表します。

各ノードタイプには、対応するコード要素に関する情報を提供するプロパティがあります。たとえば、`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. ソースファイルの読み取り：`example.ts`という名前のTypeScriptファイルの内容を読み取ります。これを機能させるには、`example.ts`ファイルを作成する必要があります。
3. SourceFileの作成：ASTのルートを表す`SourceFile`オブジェクトを作成します。`ts.createSourceFile`関数は、ソースコードを解析し、ASTを生成します。
4. ASTの出力：ASTをトラバースし、各ノードの種類を出力する再帰関数`printAST`を定義します。
5. printASTの呼び出し：ルート`SourceFile`ノードからASTの出力を開始するために、`printAST`を呼び出します。

このコードを実行するには、`.ts`ファイル（例：`ast-example.ts`）として保存し、TypeScriptコードを含む`example.ts`ファイルを作成してから、コードをコンパイルして実行します。

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

これにより、`example.ts`ファイルのASTがコンソールに出力されます。出力には、ノードの階層とその種類が表示されます。たとえば、`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クラス：`visit`メソッドを持つクラス`IdentifierVisitor`を定義します。
2. Visitメソッド：`visit`メソッドは、現在のノードが`Identifier`であるかどうかを確認します。そうである場合は、識別子のテキストを出力します。次に、`ts.forEachChild`を再帰的に呼び出して、子ノードにアクセスします。
3. ビジターの作成：`IdentifierVisitor`のインスタンスを作成します。
4. トラバースの開始：トラバースを開始するために、`SourceFile`で`visit`メソッドを呼び出します。

この例は、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：`Transformer`関数を返す`TransformerFactory`関数を定義します。
2. Transformer：`Transformer`関数は、現在のノードが`SourceFile`であるかどうかを確認します。そうである場合は、`ts.addSyntheticLeadingComment`を使用してノードに先頭コメントを追加します。
3. ts.transform：`ts.transform`を呼び出して、変換を`SourceFile`に適用します。
4. Printer：変換されたASTからコードを生成する`Printer`オブジェクトを作成します。
5. 出力と書き込み：変換されたコードを出力し、`example.transformed.ts`という名前の新しいファイルに書き込みます。

この例は簡単な変換を示していますが、同じパターンを使用して、コードのリファクタリング、ログステートメントの追加、ドキュメントの生成など、より複雑な変換を実行できます。

高度な変換テクニック

Compiler APIで使用できる高度な変換テクニックを次に示します。

• 新しいノードの作成：`ts.createXXX`関数を使用して、新しいASTノードを作成します。たとえば、`ts.createVariableDeclaration`は新しい変数宣言ノードを作成します。
• ノードの置換：`ts.visitEachChild`関数を使用して、既存のノードを新しいノードに置換します。
• ノードの追加：`ts.updateXXX`関数を使用して、新しいノードをASTに追加します。たとえば、`ts.updateBlock`は、新しいステートメントでブロックステートメントを更新します。
• ノードの削除：トランスフォーマー関数から`undefined`を返すことにより、ASTからノードを削除します。

コード生成

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関数：`SourceFile`を入力として受け取る関数`findUnusedVariables`を定義します。
2. usedVariablesセット：使用されている変数の名前を格納する`Set`を作成します。
3. visit関数：ASTをトラバースし、すべての識別子の名前を`usedVariables`セットに追加する再帰関数`visit`を定義します。
4. checkVariableDeclaration関数：変数宣言が未使用かどうかを確認する再帰関数`checkVariableDeclaration`を定義します。そうである場合は、変数名を`unusedVariables`配列に追加します。
5. unusedVariablesを返す：未使用の変数の名前を含む配列を返します。
6. 出力：未使用の変数をコンソールに出力します。

この例は、簡単なリンターを示しています。これを拡張して、他のコーディング標準をチェックし、コード内の他の潜在的な問題を特定できます。たとえば、未使用のインポート、過度に複雑な関数、または潜在的なセキュリティ脆弱性をチェックできます。重要なのは、ASTをトラバースし、関心のある特定のノードタイプを特定する方法を理解することです。

ベストプラクティスと考慮事項

• ASTを理解する：ASTの構造を理解するために時間を費やしてください。ASTエクスプローラーなどのツールを使用して、コードのASTを視覚化します。
• タイプガードを使用する：タイプガード（`ts.isXXX`）を使用して、正しいノードタイプで作業していることを確認します。
• パフォーマンスを考慮する：AST変換は計算コストが高くなる可能性があります。コードを最適化して、アクセスおよび変換するノードの数を最小限に抑えます。
• エラーを処理する：エラーを適切に処理します。ASTに対して無効な操作を実行しようとすると、Compiler APIは例外をスローする可能性があります。
• 徹底的にテストする：変換を徹底的にテストして、目的の結果が得られ、新しいバグが発生しないようにします。
• 既存のライブラリを使用する：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ライブラリ：[https://ts-morph.com/](https://ts-morph.com/)
• typescript-eslint：[https://typescript-eslint.io/](https://typescript-eslint.io/)