🕡 👩🏽‍✈️ ☑️ ts-migrateの概要-大規模プロジェクトをTypeScriptに変換するためのツール 👩🏽‍🎤 👩🏿‍🏭 🙉

Airbnbは、フロントエンド開発にTypeScript（TS）を公式に使用しています。しかし、TypeScriptを実装し、何千ものJavaScriptファイルの成熟したコードベースを言語に変換するプロセスは1日ではありません。つまり、TSの実装はいくつかの段階で行われました。最初は提案でしたが、しばらくすると多くのチームでこの言語が使用されるようになり、TSの導入はベータ段階に入りました。その結果、TypeScriptはAirbnbの公式フロントエンド開発言語になりました。Airbnb TSの実装プロセスについて詳しくは、こちらをご覧ください。この記事では、大規模なプロジェクトをTypeScriptに変換するプロセスと、Airbnbで開発された特殊なツールts-migrateについて説明します。

移行戦略

大規模なプロジェクトをJavaScriptからTypeScriptに変換することは困難です。それを解決する前に、JSからTSに切り替えるための2つの戦略を検討しました。

▍1。ハイブリッド移行戦略

このアプローチでは、プロジェクトのTypeScriptへのファイルごとの段階的な変換が実行されます。このプロセス中に、ファイルが編集され、入力エラーが修正され、プロジェクト全体がTSに変換されるまでこのように機能します。allowJSパラメーターを使用すると、プロジェクトにTypeScriptファイルとJavaScriptファイルの両方を含めることができます。このおかげで、JSプロジェクトをTSに変換するこのアプローチは非常に実行可能です。

ハイブリッド移行戦略では、開発プロセスを一時停止する必要はありません。ファイルごとに段階的にプロジェクトをTypeScriptに変換できます。しかし、大規模なプロジェクトについて話す場合、このプロセスには長い時間がかかる可能性があります。また、組織全体のプログラマー向けのトレーニングも必要です。プログラマーは、プロジェクトの詳細を紹介する必要があります。

▍2。包括的な移行戦略

このアプローチでは、完全にJavaScriptで記述されたプロジェクト、またはその一部がTypeScriptで記述されたプロジェクトを使用して、それをTypeScriptプロジェクトに完全に変換します。この場合、タイプanyとコメントを使用する必要があります@ts-ignore。これにより、プロジェクトをエラーなしでコンパイルできます。しかし、時間の経過とともに、コードを編集して、より適切なタイプを使用するように進むことができます。

包括的なTypeScript移行戦略には、ハイブリッド戦略に比べていくつかの重要な利点があります。

. , , . , TypeScript, , .
, . , , , . .

上記を考慮すると、すべての点で、パーベイシブ移行はハイブリッド移行よりも優れているように思われます。しかし、成熟したコードベースを包括的な方法でTypeScriptに変換することは、非常に困難な作業です。それを解決するために、コードを変更するスクリプト、いわゆる「codemods」（codemods）に頼ることにしました。プロジェクトをTypeScriptに最初に変換し始めたとき、それを手動で行ったとき、自動化できる反復操作に気づきました。これらの操作ごとにコードmodを作成し、それらを1つの移行パイプラインに結合しました。

経験によれば、プロジェクトをTypeScriptに自動変換した後、エラーが発生しないことを100％確信することはできません。しかし、以下で説明する手順の組み合わせが最良の結果をもたらし、最終的に、エラーのないTypeScriptプロジェクトが得られたことがわかりました。 code modsを使用して、50,000行を超えるコードを含み、1,000を超えるファイルで表されるプロジェクトをTypeScriptに変換することができました。これを行うのに1日かかりました。

次の図に示すパイプラインに基づいて、ts-migrateツールを作成しました。

Ts-migrate codemods

Airbnbのフロントエンドの大部分は、 Reactを使用して記述されています。これが、コードmodの一部がReact固有の概念に関連している理由です。ts-migrateツールは、他のライブラリまたはフレームワークで使用できますが、これには追加の構成とテストが必要になります。

移行プロセスの概要

プロジェクトをJavaScriptからTypeScriptに変換するために従う必要のある基本的な手順を見ていきましょう。これらの手順がどのように実装されているかについて話しましょう。

▍ステップ1

すべてのTypeScriptプロジェクトが最初に作成するのはtsconfig.jsonです。Ts-migrateは、必要に応じて独自に実行できます。このファイルには標準のテンプレートがあります。さらに、すべてのプロジェクトが一貫して構成されていることを確認するための検証システムが導入されています。基本的な構成の例を次に示します。

{
  "extends": "../typescript/tsconfig.base.json",
  "include": [".", "../typescript/types"]
}

▍ステップ2

ファイルtsconfig.jsonが本来あるべき場所に配置されると、ソースファイルの名前が変更されます。つまり、.js /.jsx拡張子は.ts / .tsxに変更されます。このステップは非常に簡単に自動化できます。これにより、多くの手作業を取り除くことができます。

▍ステップ3

次に、コードmodを実行します。それらをプラグインと呼びます。ts-migrateのプラグインは、TypeScript言語サーバーを介して追加情報にアクセスできるコードmodです。プラグインは文字列を入力として受け入れ、変更された文字列を返します。jscodeshiftツールボックス、TypeScript API、文字列処理ツール、またはその他のAST変更ツールを使用して、コード変換を実行できます。

上記の各手順を完了した後、Git履歴に保留中の変更があるかどうかを確認し、それらをプロジェクトに含めます。これにより、移行PRをコミットに分割できるため、何が起こっているのかを理解しやすくなり、ファイル名の変更を追跡するのに役立ちます。

ts-migrateを構成するパッケージの概要

ts-migrateを3つのパッケージに分割します。

これにより、コード変換ロジックをシステムのコアから分離し、さまざまな問題を解決するように設計された多くの構成を作成することができました。これで、移行と再無視という2つの主要な構成ができました。

構成を適用する目的はmigration、プロジェクトをJavaScriptからTypeScriptに変換することです。また、この構成reignoreは、すべてのエラーを無視するだけでプロジェクトをコンパイルできるようにするために使用されます。この構成は、コードベースが大きく、次のようにさまざまなことを行う場合に役立ちます。

TypeScriptバージョンの更新。
コードに大きな変更を加えるか、コードベースをリファクタリングします。
いくつかの一般的に使用されるライブラリの改良されたタイプ。

このアプローチでは、すぐに対処する予定のないコンパイルエラーが生成された場合でも、プロジェクトをTypeScriptに変換できます。これにより、TypeScriptまたはコードで使用されているライブラリの更新も簡単になります。

どちらの構成も、次のts-migrate-server2つの部分からなるサーバーで実行されます。

TSServer：サーバーのこの部分は、VSCodeがエディターと言語サーバー間の通信に使用するものと非常によく似ています。TypeScript言語サーバーの新しいインスタンスは、別のプロセスで開始されます。開発ツールは、言語プロトコルを使用してそれと対話します。
移行ツール：これは、移行プロセスを実行し、このプロセスを調整するコードです。このツールは次のパラメータを取ります。

interface MigrateParams {
  rootDir: string;          //    .
  config: MigrateConfig;    //  ,   
                            // .
  server: TSServer;         //   TSServer.
}

このツールは次のことを行います。

ファイルを解析していますtsconfig.json。
ソースコードを使用して.tsファイルを作成します。
送るこのファイルを診断するために、活字体の言語のサーバに各ファイルを。そこ私たちのコンパイラを与える診断の3つのタイプが、以下のとおりですsemanticDiagnostics、syntacticDiagnosticsとsuggestionDiagnostics。これらのチェックを使用して、ソースコード内の問題領域を見つけます。一意の診断コードとファイル内の行番号に基づいて、考えられる問題のタイプを特定し、必要なコード変更を適用できます。
すべてのプラグインで各ファイルを処理します。プラグインの主導でファイル内のテキストが変更された場合、元のファイルの内容を更新し、ファイルが変更されたことを言語サーバーに通知します。

使用例ts-migrate-serverは、examplesパッケージまたはメインパッケージにあります。またts-migrate-example、基本的なプラグインの例も含まれています。それらは3つの主要なカテゴリに分類されます。

jscodeshiftに基づくプラグイン。
Abstract Syntax Tree（AST）TypeScriptに基づくプラグイン。
テキストベースのプラグイン。

リポジトリには、これらすべての種類の単純なプラグインを作成するプロセスを示すことを目的とした一連の例が含まれています。また、cとの組み合わせでの使用も示していますts-migrate-server。コードを変換する移行パイプラインの例を次に示します。次のコードが入力で受信されます。

function mult(first, second) {
  return first * second;
}

そして彼は次のように述べています。

function tlum(tsrif: number, dnoces: number): number {
  console.log(`args: ${arguments}`);
  return tsrif * dnoces;
}

この例では、ts-migrateは3つの変換を実行しました。

これは、すべての識別子の文字の順序を逆にしますfirst -> tsrif。
関数宣言のタイプに関する情報を追加しました：function tlum(tsrif, dnoces) -> function tlum(tsrif: number, dnoces: number): number。
コードに行を追加しました console.log(‘args:${arguments}’);

汎用プラグイン

実際のプラグインは、別のパッケージts-migrate-pluginsにあります。それらのいくつかを見てみましょう。 jscodeshiftに基づく2つのプラグインがあります：explicitAnyPluginとdeclareMissingClassPropertiesPlugin。jscodeshiftツールボックスができますあなたが変換することのASTを使用して、通常のコードにリキャストパッケージを。この関数toSource()を使用して、ファイルに含まれているソースコードを直接更新できます。ExplicitAnyPlugin

プラグインは、すべてのエラーとそれらのエラーが検出された行に関する情報をTypeScript言語サーバーから取得します。次に、タイプ注釈がこれらの行に追加されます。このアプローチでは、タイプを使用するため、エラーを修正できますsemanticDiagnosticsanyanyコンパイルエラーを取り除くことができます。

処理する前のサンプルコードは次のとおりです。

const fn2 = function(p3, p4) {}
const var1 = [];

プラグインによって処理されるのと同じコードは次のとおりです。

const fn2 = function(p3: any, p4: any) {}
const var1: any = [];

declareMissingClassPropertiesPluginはエラーコードですべての診断メッセージを取る2339（あなたは何を推測することができ、このコードの意味を、それが欠落している識別子を持つクラスの宣言を見つけることができれば、？）そして、注釈付きクラスのボディに追加しますany。プラグインの名前から、ES6クラスにのみ適用可能であると結論付けることができます。

プラグインの次のカテゴリは、ASTTypeScriptに基づいています。ASTを処理することにより、ソースファイルに対して行われる更新の配列を生成できます。これらの更新の説明は次のようになります。

type Insert = { kind: 'insert'; index: number; text: string };
type Replace = { kind: 'replace'; index: number; length: number; text: string };
type Delete = { kind: 'delete'; index: number; length: number };

必要な更新に関する情報を生成した後は、逆の順序でファイルに入力するだけです。この操作を実行した後、新しいプログラムコードを受け取った場合は、それに応じてソースコードファイルを更新します。

次のいくつかのASTベースのプラグインを見てみましょう。これはstripTSIgnorePluginとhoistClassStaticsPluginです。stripTSIgnorePlugin

プラグインは、移行パイプラインで使用される最初のプラグインです。ファイルからすべてのコメントを削除します。@ts-ignore（これらのコメントにより、次の行で発生するエラーを無視するようにコンパイラーに指示できます）。JavaScriptで記述されたプロジェクトをTypeScriptに変換する場合、このプラグインはアクションを実行しません。しかし、一部がJSで、一部がTSで記述されているプロジェクト（いくつかのプロジェクトが同様の状態であった）について話している場合、これは省略できない最初の移行ステップです。コメントが削除された後でのみ@ts-ignore、TypeScriptコンパイラは修正が必要な診断エラーメッセージを生成します。

このプラグインの入力に入るコードは次のとおりです。

const str3 = foo
  ? // @ts-ignore
    // @ts-ignore comment
    bar
  : baz;

出力は次のとおりです。

const str3 = foo
  ? bar
  : baz;

コメント@ts-ignoreを削除した後、hoistClassStaticsPluginプラグインを実行します。すべてのクラス宣言を通過します。プラグインは、識別子または式を上げる可能性を判断し、割り当て操作がすでにクラスレベルに上げられているかどうかを確認します。

高い開発速度を確保し、プロジェクトの以前のバージョンへの強制的なダウングレードを回避するために、各プラグインとts-migrateに一連のユニットテストを提供しました。

React関連のプラグイン

この優れたツールに基づくreactPropsPlugin プラグインは、タイプ情報をPropTypesからTypeScriptタイプ宣言に変換します。このプラグインを使用すると、少なくとも1つのReactコンポーネントを含む.tsxファイルを処理するだけで済みます。このプラグインは、すべてのPropTypes宣言を検索し、ASTおよびのような単純な正規式を使用して、または/ objectOf $ /のようなより複雑な正規式を使用してそれらを解析しようとします。 React-component（関数またはクラスに基づく）が検出されると、新しいタイプを使用してパラメーター（props）を入力するコンポーネントに変換されます。ReactDefaultPropsPlugin プラグイン/number/type Props = {…};

ReactコンポーネントにdefaultPropsパターンを実装する責任があります。デフォルト値が与えられている入力パラメーターを表すために、特別なタイプを使用します。

type Defined<T> = T extends undefined ? never : T;
type WithDefaultProps<P, DP extends Partial<P>> = Omit<P, keyof DP> & {
  [K in Extract<keyof DP, keyof P>]:
    DP[K] extends Defined<P[K]>
      ? Defined<P[K]>
      : Defined<P[K]> | DP[K];
};

デフォルト値が割り当てられている小道具を見つけて、前の手順で作成したコンポーネントの小道具を説明するタイプと組み合わせます。

Reactエコシステムは、状態とコンポーネントのライフサイクルの概念を幅広く利用しています。次のいくつかのプラグインでは、これらの概念に関連する問題に取り組んでいます。したがって、コンポーネントに状態がある場合、reactClassStatePluginプラグインは新しいタイプ（type State = any;）を生成し、reactClassLifecycleMethodsPluginプラグインはコンポーネントのライフサイクルメソッドに対応するタイプの注釈を付けます。これらのプラグインの機能は、プラグインをanyより正確なタイプに置き換える機能を装備するなどして拡張できます。

これらのプラグインは、特に、状態とプロパティのタイプサポートを拡張することで改善できます。しかし、それらの既存の機能は、結局のところ、必要な機能を実装するための良い出発点です。さらに、移行の開始時に、コードベースがフックをサポートしない古いバージョンのReactを使用していたため、ここではReactフックを使用しません。

プロジェクトが正しくコンパイルされていることを確認する

私たちの目標は、プログラムの動作を変更せずに、基本型を備えたTypeScriptプロジェクトをコンパイルすることです。

すべての変換と変更を行った後、コードのフォーマットが不均一になる可能性があります。これにより、リンターを使用した一部のコードチェックでエラーが明らかになる可能性があります。フロントエンドコードベースは、PrettierとESLintに基づくシステムを使用しています。つまり、Prettierは自動コードフォーマットに使用され、ESLintは、推奨される開発アプローチに準拠しているかどうかコードをチェックするのに役立ちます。これにより、適切なプラグインを使用するだけで、以前のアクションから発生したコードフォーマットの問題にすばやく対処できます。- eslintFixPlugin。

移行パイプラインの最後のステップは、すべてのTypeScriptコンパイルの問題が解決されたことを確認することです。潜在的なエラーを見つけて修正するために、tsIgnorePluginプラグインは、コードと行番号のセマンティック診断から情報を取得し@ts-ignore、エラーの説明とともにコメントをコードに追加します。たとえば、次のようになります。

// @ts-ignore ts-migrate(7053) FIXME: No index signature with a parameter of type 'string...
const { field1, field2, field3 } = DATA[prop];
// @ts-ignore ts-migrate(2532) FIXME: Object is possibly 'undefined'.
const field2 = object.some_property;

システムにJSX構文サポートを装備しました。

{*
// @ts-ignore ts-migrate(2339) FIXME: Property 'NORMAL' does not exist on type 'typeof W... */}
<Text weight={WEIGHT.NORMAL}>
  some text
</Text>
<input
  id="input"
  // @ts-ignore ts-migrate(2322) FIXME: Type 'Element' is not assignable to type 'string'.
  name={getName()}
/>

意味のあるエラーメッセージを自由に使用できるため、エラーの修正や、注意すべきコードスニペットの検索が容易になります。関連するコメントをと組み合わせる$TSFixMeことで、コードの品質に関する貴重なデータを収集し、潜在的に問題のあるコードフラグメントを見つけることができます。$TSFixMe作成したタイプエイリアスですany。そして関数の場合、これは$TSFixMeFunction = (…args: any[]) => any;です。タイプの使用は避けることをお勧めしますが、タイプanyを使用すると移行プロセスを簡素化するのに役立ちました。このタイプを使用すると、どのコードフラグメントを改善する必要があるかを正確に知ることができました。

プラグインeslintFixPluginが2回実行されることは注目に値します。初めて使用する前にtsIgnorePluginフォーマットは、コンパイルエラーが発生する場所に関するメッセージに影響を与える可能性があるためです。tsIgnorePluginコードにコメントを追加@ts-ignoreするとフォーマットエラーが発生する可能性があるため、2回目は適用後です。

その他の注意事項

作業中に気付いたいくつかの移行機能に注目してください。おそらく、これらの機能について知っておくと、プロジェクトで作業するときに役立ちます。

TypeScript 3.7 @ts-nocheck, TypeScript- . , .js-, .ts/.tsx-. , .
TypeScript 3.9では、@ ts-expect-errorコメントのサポートが導入されています。コードの行の前にそのようなコメントが付いている場合、TypeScriptは対応するエラーを報告しません。そのような行にエラーがない場合、TypeScriptはコメントの@ts-expect-error必要がないことを通知します。Airbnbコードベースはコメントからコメント@ts-ignoreに移動しました@ts-expect-error。

結果

AirbnbのコードベースのJavaScriptからTypeScriptへの移行はまだ進行中です。まだJavaScriptコードで表されている古いプロジェクトがいくつかあります。$TSFixMeコメントは、コードベースではまだ一般的@ts-ignoreです。

AirbnbのJavaScriptとTypeScript

ただし、ts-migrateを使用すると、プロジェクトをJSからTSに変換するプロセスが大幅に加速され、作業の生産性が大幅に向上したことに注意してください。 ts-migrateを使用すると、プログラマーは各ファイルを手動で処理するのではなく、入力の改善に集中することができました。現在、約600万行のコードを持つフロントエンドモノリポジトリの約86％がTypeScriptに変換されています。今年末までに95％に達すると見込んでいます。

ここのプロジェクトリポジトリのホームページで、ts-migrateをインストールして実行する方法を学ぶことができます。 ts-migrateに問題がある場合、またはこのツールを改善するためのアイデアがある場合は、ぜひご参加ください。それに取り組むために！

大規模なプロジェクトをJavaScriptからTypeScriptに変換したことがありますか？

ts-migrateの概要-大規模プロジェクトをTypeScriptに変換するためのツール