[Node] 淡如止水 TypeScript （二）：开始编译

0. 回顾

上一篇，我们把 VSCode 调试环境准备好了，启动调试后，进到了 lib/tsc 中，
断点停在了第一行。

本文我们开始往下调试了，深入到 tsc 编译的整个过程中。
不过在此之前，我们需先对 VSCode 调试面板有一些了解，调试面板提供了多种调试功能。

（1）F5 - Continue：执行到下一个断点

（2）F10 - Step Over：执行下一行，不跳入函数内部

（3）F11 - Step Into：代码执行到下一步，跳入函数内部

（4）⇧ F11 - Step Out：执行完当前函数，回到调用方

（5）⇧ ⌘ F5 - Restart：重新启动调试

（6）⇧ F5 - Stop：停止调试

熟悉了这些调试功能之后，我们才能在 TypeScript 源码中随意驰骋。

1. lib/tsc require 无法进入断点的问题

上一篇提到，断点停在了 lib/tsc 第一行，
这是调试配置 .vscode/launch.json 中 stopOnEntry 设为 true 的预期表现，

接着 lib/tsc 会 require ../built/local/tsc.js 文件，
然后，VSCode 会根据 ../built/local/tsc.js.map 反查对应的 .ts 源码，跳转到 src/tsc/tsc.ts 中。

ts.executeCommandLine(
  ...
);

所以，我们应在 src/tsc/tsc.ts#L2 打个断点，如下所示，

然而我发现，在 VSCode 按 F5 继续执行，却无法从 lib/tsc 直接跳转到 src/tsc/tsc.ts 中。

我们得按以下步骤操作才行。
（1）lib/tsc Step Over 到 require 那一行

（2）lib/tsc Step Into 跳转到 require 中

（3）代码会跳转到 src/compiler/core.ts#L1，然后再按 F5

（4）这样才能来到 src/tsc/tsc.ts#L2 的断点处

我们看到 ts.sys.args 的值，正是 tsc 待编译的文件 debug/index.ts。

2. 解析 & 写文件

好了，终于可以正常的调试 .ts 源码了，我们 Step Into 进入 ts.executeCommandLine 的具体实现中。
它位于 src/tsc/executeCommandLine.ts#L353，

export function executeCommandLine(
  ...
): void {
  ...
  if (...) {
    ...
  }
  else {
    executeCommandLineWorker(system, cb, commandLine);
  }
}

可见，executeCommandLine 接着会调用 executeCommandLineWorker，src/tsc/executeCommandLine.ts#L170，

function executeCommandLineWorker(
  ...
) {
  ...
  if (configFileName) {
    ...
  }
  else {
    ...
    if (isWatchSet(commandLineOptions)) {
      ...
    }
    else if (isIncrementalCompilation(commandLineOptions)) {
      ...
    }
    else {
      performCompilation(
        sys,
        reportDiagnostic,
        cb,
        { ...commandLine, options: commandLineOptions }
      );
    }
  }
}

然后调用 performCompilation，src/tsc/executeCommandLine.ts#L493，

function performCompilation(
  ...
) {
  ...
  const program = createProgram(programOptions);
  const exitStatus = emitFilesAndReportErrorsAndGetExitStatus(
    ...
  );
  ...
}

这里，performCompilation 会执行两个关键操作，
（1）createProgram 解析源代码
（2）emitFilesAndReportErrorsAndGetExitStatus 将编译结果写文件

本文之后的几篇文章，我们先详细的介绍源码的解析过程，
然后再回过头来介绍 emitFilesAndReportErrorsAndGetExitStatus。

3. 调用 parser 解析单个文件

首先，createProgram 位于 src/compiler/program.ts#L713，这个函数有 2665 行，
有很多辅助函数，它实际是在 src/compiler/program.ts#L988 这里就返回了。

处理待编译的源文件 debug/index.ts，发生在 src/compiler/program.ts#L873，forEach 中，

export function createProgram(...): Program {
  ...
  if (structuralIsReused !== StructureIsReused.Completely) {
    ...

    forEach(rootNames, name => processRootFile(name, /*isDefaultLib*/ false, /*ignoreNoDefaultLib*/ false));

    ...
  }

  ...
  const program: Program = {
    ...
  };

  ...
  return program;

  ...
}

它逐个处理了 TypeScript 待编译的文件，我们当前示例项目中，只有一个文件，
可以看到，rootNames 数组的唯一元素正是 debug/index.ts。

随后，forEach 会调用 processRootFile，src/compiler/program.ts#L2041，

function processRootFile(...) {
  processSourceFile(...);
}

processRootFile 调用 processSourceFile，src/compiler/program.ts#L2231，

function processSourceFile(...): void {
  getSourceFileFromReferenceWorker(
    ...
  );
}

processSourceFile 调用 getSourceFileFromReferenceWorker，src/compiler/program.ts#L2186，

function getSourceFileFromReferenceWorker(
  ...

  if (hasExtension(fileName)) {
    ...

    const sourceFile = getSourceFile(fileName);
    ...
    return sourceFile;
  }
  else {
    ...
  }
}

getSourceFileFromReferenceWorker 调用 getSourceFile，
它是 getSourceFileFromReferenceWorker 传入的一个参数，
具体实现位于 src/compiler/program.ts#L2234，

function processSourceFile(...): void {
  getSourceFileFromReferenceWorker(
    ...
    fileName => findSourceFile(fileName, toPath(fileName), isDefaultLib, ignoreNoDefaultLib, refFile, packageId), // TODO: GH#18217
    ...
  );
}

接着会调用 findSourceFile，src/compiler/program.ts#L2273，

function findSourceFile(...): SourceFile | undefined {
  ...
  const file = host.getSourceFile(
    ...
  );
  ...
  return file;
}

然后调用 host.getSourceFile，src/compiler/program.ts#L78，
先读文件，然后又调用了 createSourceFile，

function getSourceFile(...): SourceFile | undefined {
  ...
  try {
    ...
    text = compilerHost.readFile(fileName);
    ...
  }
  catch (e) {
    ...
  }
  return text !== undefined ? createSourceFile(fileName, text, languageVersion, setParentNodes) : undefined;
}

createSourceFile 位于 src/compiler/parser.ts#L515，我们终于看到 parser 的影子了。

总结

以上我们分析了从命令行 lib/tsc 开始，到调用 parser 解析每个文件的过程，
逻辑上来看，编译过程中，TypeScript 会创建一个 Program 对象，
这个 Program 对象中，会包含多个 SourceFile。

每一个 SourceFile 都是单独读文件，然后进行解析的。
下文我们要深入研究 SourceFile 到底是怎样解析的，这会涉及 Compiler 中的词法和语法分析过程。

下面，用一张图来总结本文涉及到的所有文件和方法，
createProgram 和 createSourceFile 是两个关键环节。

参考

TypeScript v3.7.3