TypeScript/TypeScript コンパイラの差分コンパイルの仕組み

注意: これは書きかけのメモです。途中で力尽きてます。

はじめに

code:console

$ hcm 'src/**/*/module.css'

src/a.module.css (generated)

src/b.module.css (generated)

$ vim src/a.module.css

(Edit the file)

$ hcm 'src/**/*/module.css'

src/a.module.css (generated)

また、コード生成時に CSS Module ファイル同士の import の整合性のチェックも行いたい。例えば、存在しない CSS Module の import や、存在しない value の import を警告したい。

code:a.module.css

@import './non-existent.module.css';

// ^^^^^^^^^^^^^^^^^^^^^^^^^

// Cannot find module './non-existent.module.css'.

@value b_1, b_2 from './b.module.css';

// ^^^

// Module './b.module.css' has no exported token b_2'.

code:b.module.css

.b_1 { color: red; }

code:a.module.css

// ...

@value b_1, b_2 from './b.module.css';

// ^^^

// OK!

code:b.module.css

.b_1 { color: red; }

.b_2 { color: red; }

つまり、変更されたファイルだけでなく、そのファイルを import するファイルも再検査する必要がある。以下のように。

code:console

$ hcm 'src/**/*/module.css'

src/a.module.css (checked, generated)

src/b.module.css (checked, generated)

src/c.module.css (checked, generated)

$ vim src/b.module.css

(Edit the file)

$ hcm 'src/**/*/module.css'

src/a.module.css (checked)

src/b.module.css (checked, generated)

知りたいこと

コンパイルキャッシュには何が入ってるのか

ファイルのハッシュ、AST、エラー情報など色々なデータがあるが、どれが含まれているのか

TypeScript プロジェクトのコンパイルがどういうフローで行われるか

パース、型検査、.js/.d.ts の出力、というざっくりとしたフェーズがあるのは想像できるが...実際どうなってるのか

どのフェーズが1ファイル単独で行われて、どのフェーズが複数ファイル横断で行われるのか

パースは1ファイルずつ単独で、型検査は複数ファイル横断でやってるだろうが...他のフェーズはどうか

変更されたファイルを import しているファイルをどう辿るか

モジュールグラフを逆に辿っていくことになるが、それをどうやっているのか

効率よく逆方向に辿るにはデータ構造を工夫する必要があるが、どう工夫しているのか

コンパイルキャッシュによって何がスキップされるのか

パース、型検査などのフェーズのうち、どれがスキップされるのか

逆に、キャッシュがあっても毎回行われるものは何か

エディタ上に型検査のエラーをどう表示しているのか

理想的には、開いているファイルだけ型検査して、そのエラーをエディタに表示したい

ただ型検査は、開いているファイルに加え、それが import している全てのファイルを解析しないと実行できない

開いているファイルと、その関連するファイルを取得して、それだけ型検査する仕組みがあるのだろうが、実際どうやってるのか

エディタ上でファイルを変更した時に、どう型検査を実行してるか

影響するファイルの取得と、その再検査をどうやっているか

コンパイルキャッシュの中身

とりあえず適当なプロジェクトを作ってコンパイルキャッシュを作成してみる。

code:package.json

{

"name": "tsc-incremental-test",

"type": "module",

"devDependencies": {

"typescript": "5.7.3"

}

}

code:tsconfig.json

{

"compilerOptions": {

"target": "ES5",

"module": "NodeNext",

"esModuleInterop": true,

"forceConsistentCasingInFileNames": true,

"strict": true,

"noUncheckedSideEffectImports": true,

"skipLibCheck": true,

"rootDir": "src",

"outDir": "dist",

"incremental": true

}

}

code:src/a.ts

import './non-existent.js';

import { b_1, b_2 } from './b.js';

code:src/b.ts

export const b_1 = 'b_1';

code:console

$ npx tsc

src/a.ts:1:8 - error TS2307: Cannot find module './non-existent.js' or its corresponding type declarations.

1 import './non-existent.js';

~~~~~~~~~~~~~~~~~~~

src/a.ts:2:15 - error TS2305: Module '"./b.js"' has no exported member 'b_2'.

2 import { b_1, b_2 } from './b.js';

~~~

Found 2 errors in the same file, starting at: src/a.ts:1

code:json

{

"fileNames": [

"./node_modules/typescript/lib/lib.d.ts",

"./node_modules/typescript/lib/lib.es5.d.ts",

"./node_modules/typescript/lib/lib.dom.d.ts",

"./node_modules/typescript/lib/lib.webworker.importscripts.d.ts",

"./node_modules/typescript/lib/lib.scripthost.d.ts",

"./node_modules/typescript/lib/lib.decorators.d.ts",

"./node_modules/typescript/lib/lib.decorators.legacy.d.ts",

"./src/b.ts",

"./src/a.ts"

],

"fileInfos": [

{

"version": "a7297ff837fcdf174a9524925966429eb8e5feecc2cc55cc06574e6b092c1eaa",

"impliedFormat": 1

},

{

"version": "e41c290ef7dd7dab3493e6cbe5909e0148edf4a8dad0271be08edec368a0f7b9",

"affectsGlobalScope": true,

"impliedFormat": 1

},

{

"version": "4fd3f3422b2d2a3dfd5cdd0f387b3a8ec45f006c6ea896a4cb41264c2100bb2c",

"affectsGlobalScope": true,

"impliedFormat": 1

},

// ... (more 6 items) ...

],

"options": {

"esModuleInterop": true,

"module": 199,

"noUncheckedSideEffectImports": true,

"outDir": "./dist",

"rootDir": "./src",

"skipLibCheck": true,

"strict": true,

"target": 1

},

"semanticDiagnosticsPerFile": [

[

9,

[

{

"start": 7,

"length": 27,

"messageText": "Cannot find module './non-existent.module.css' or its corresponding type declarations.",

"category": 1,

"code": 2307

},

{

"start": 50,

"length": 3,

"messageText": "Module '\"./b.js\"' has no exported member 'b_2'.",

"category": 1,

"code": 2305

}

]

]

],

"version": "5.7.3"

}

ここから、以下の情報がコンパイルキャッシュに含まれてることがわかる。

fileNames

プロジェクトに含まれる全てのファイルのパス

fileIdsList

ファイルの Id のリストのリスト。詳しくは後述。

fileInfos

プロジェクトに含まれるファイルの詳細

root

このファイルを基点にモジュールグラフが構築されるので、root という名になってるっぽい

プロジェクトのエントリポイント、という見方もできる

options

コンパイルオプション

コンパイルオプションが変わるとコンパイル結果が変わるので、含めてあるのだろう

referencedMap

モジュール同士の依存関係を表したマップ

semanticDiagnosticsPerFile

「semantic diagnostics」と呼ばれる診断情報がファイルごとに格納されてる

補足: TypeScript には「syntactic diagnostics」と「semantic diagnostics」の2種類の診断情報がある

version

コンパイルフロー

code:ts

export const enum Phase {

Parse = "parse",

Program = "program",

Bind = "bind",

Check = "check", // Before we get into checking types (e.g. checkSourceFile)

CheckTypes = "checkTypes",

Emit = "emit",

Session = "session",

}

ここに書いてあるものがコンパイルを構成するフェーズなのだろう。それぞれどういうものか見ていくと、

1. Parse

このフェーズで、AST の構築と、syntactic diagnostics の収集を行う

2. Program

つまり Parse フェーズは Program フェーズに内包されてる

3. Bind

ソースコード内の識別子 (変数名, 関数名, クラス名など) をその宣言と結びつけるフェーズ

4. Check

つまり Bind フェーズは Check フェーズに内包されてる

つまり Checker フェーズは Program フェーズに内包されてる

5. CheckTypes

型検査を行うのは Check と変わらないけど、サブタイプの検査とか、もうちょっと細かい型検査を行うフェーズっぽい

https://gyazo.com/811c52194344da69499177ecdfe659f9

ちゃんと追ってないけど、たぶん Check フェーズに内包されてるのでは

6. Emit

7. Session

今回はあんまり関心ないので無視

この情報をもとにフェーズの関係性を示した図が以下になる。

https://scrapbox.io/files/67a755c1edf5c1aff9994b0d.svg

ちょっと毛色は違うけど、TypeScript チームの解説資料にコンパイラのレイヤを表した図がある。これと比較しながら見ると、より理解が捗るかも。

https://github.com/microsoft/TypeScript-Compiler-Notes/raw/main/intro/imgs/layers-2.png

個々のフェーズやコンパイラを構成するレイヤについてもっと詳しく知りたい場合は、以下の公式の解説を読むと良い。

今回描いた図から分かることは、Parse/Bind フェーズは各ファイル単独で、Check/Emit は複数ファイル横断で実行しているということだ。

差分コンパイルの仕組み

いよいよ差分コンパイルのコードを読んでいく。だいぶまとめるのに力尽きつつあるので早足で...

code:src/compiler/builder.ts

export function createEmitAndSemanticDiagnosticsBuilderProgram(

newProgramOrRootNames: Program | readonly string[] | undefined,

hostOrOptions: BuilderProgramHost | CompilerOptions | undefined,

oldProgramOrHost?: CompilerHost | EmitAndSemanticDiagnosticsBuilderProgram,

configFileParsingDiagnosticsOrOldProgram?: readonly Diagnostic[] | EmitAndSemanticDiagnosticsBuilderProgram,

configFileParsingDiagnostics?: readonly Diagnostic[],

projectReferences?: readonly ProjectReference[],

) {

return createBuilderProgram(

BuilderProgramKind.EmitAndSemanticDiagnosticsBuilderProgram,

getBuilderCreationParameters(

newProgramOrRootNames,

hostOrOptions,

oldProgramOrHost,

configFileParsingDiagnosticsOrOldProgram,

configFileParsingDiagnostics,

projectReferences,

),

);

}

...ここでメモは尽きている。