[Node] 随遇而安 TypeScript（一）：查找符号

0. 前言

在《淡如止水 TypeScript》中，我们研究了 TypeScript 源码的一些基本概念，
例如，TypeScript 是如何进行词法分析、语法分析的，如何进行类型检查的，
如何进行代码转换，以及 tsserver 是如何作为独立的进程提供语言服务的。

本系列文章，我们将继续深入探索，
TypeScript 源码量比较大，短时间内通读一遍也不太现实，更无必要，
因此，打算以专题的形式，从问题出发总结成文。

TypeScript 的调试方式，我已经整理到了 github: debug-typescript 中。
上一个系列的文章中已详细介绍过了，本系列文章直接使用它。
TypeScript 源码的版本，我用的是 TypeScipt v3.7.3。

1. 问题

参考 github: debug-typescript 的使用说明，
安装完毕后，它会在 TypeScript 源码目录新建一个 debug/index.ts 文件。
这是我们用来试验 TypeScript 各项功能的源代码文件。

我们修改 debug/index.ts 的内容如下，并用 VSCode 打开这个文件，

function f() {
  x
}

鼠标移动到 x 上，我们会看到 VSCode 会提示诊断信息（Diagnostics），

Cannot find name 'x'. ts(2304)

VSCode 是如何知道 x 是未定义的呢？
这还要从 TypeScript 诊断过程中的 resolveName 说起。

2. 启动调试

Cannot find name 'x'. ts(2304)

我们已经知道 VSCode 是通过与 tsserver 通信，实现 TypeScript 的各项语言支持的，
那么，以上诊断信息，应该是由 TypeScript 源码中反馈回来的。

本来我们需要 debug tsserver 来找到结果，但其实 tsc 命令也会返回错误信息。

$ tsc debug/index.ts
debug/index.ts:2:3 - error TS2304: Cannot find name 'x'.

2   x
    ~


Found 1 error.

tsc 相较于 tsserver 调试起来会简单一些，所以下文我们用 tsc 来进行调试。
因为 x 是代码相关的，肯定是一个占位符，所以我们只搜索 Cannot find name。

接着搜索 Cannot_find_name_0，

位于 src/compiler/checker.ts#L18085，在这里打个断点，
然后按照 github: debug-typescript 介绍的方式，按 F5 进行调试。

再按 Continue，果然来到了断点处。

3. 预加载的 .d.ts 文件

然而，不幸的是，这并不是我们示例代码中 x 变量报错的时间点，

通过检查调用栈 checkExpressionWorker，src/compiler/checker.ts#L17575，
我们发现 node.escapedText 为 Symbol，不是我们的变量 x。

/Users/.../Microsoft/TypeScript/built/local/lib.es5.d.ts

其中，/Users/.../Microsoft/TypeScript 是我本地 TypeScript 源码仓库地址，
我们来看一下这个文件的内容，

它是一个 TypeScript 的声明文件，用于声明 es5 中内置对象的类型，
TypeScript 会预加载很多内置的声明文件。

我们可以从这里 src/compiler/program.ts#L1653 获取 TypeScript 总共预先加载了哪些文件，

program.getSourceFiles().map(({fileName})=>fileName).length
> 114

包括 debug/index.ts 在内，总共有 114 个，除了 built/local/ 目录下的，还有 node_modules/ 中的。

4. 条件断点

为了能定位到 debug/index.ts 中的 x 变量的报错信息，我们需要使用条件断点（Conditional Breakpoint），

在 src/compiler/checker.ts#L27575 行打断点的位置，右键添加条件断点。

然后输入条件，回车，

node.escapedText === 'x'

再把最初 src/compiler/checker.ts#L18085，Cannot_find_name_0 报错位置的断点去掉，按 F5 继续调试。

这是不是我们的 debug/index.ts 文件中的 x 呢？

然后我们再到 src/compiler/checker.ts#L27575 把断点再打上，应该会跑到这里，

5. 跟踪

（1）查找符号

现在我们来分析 TypeScript 是怎么 x 未定义的，这才是问题的关键。
以下我从上到下，列举了调用栈中几个主要的函数，

executeCommandLine                     # 执行 tsc
performCompilation                     # 开始编译
getSemanticDiagnostics                 # 语义分析
checkSourceFile                        # 检查加载的各个文件
checkSourceElement                     # 从 ast 的根元素开始检查
checkIdentifier                        # 检查标识符 x
getResolvedSymbol                      # 从符号表中获取与 x 相关的信息
resolveName                            # 查找 x
getCannotFindNameDiagnosticForName     # 获取 “无法找到名字” 的诊断文案

resolveName，是由 getResolvedSymbol 调用的，src/compiler/checker.ts#L18094，

function getResolvedSymbol(node: Identifier): Symbol {
  const links = getNodeLinks(node);
  if (!links.resolvedSymbol) {
    links.resolvedSymbol = !nodeIsMissing(node) &&
      resolveName(
        node,
        node.escapedText,
        SymbolFlags.Value | SymbolFlags.ExportValue,
        getCannotFindNameDiagnosticForName(node),
        node,
        !isWriteOnlyAccess(node),
                        /*excludeGlobals*/ false,
        Diagnostics.Cannot_find_name_0_Did_you_mean_1) || unknownSymbol;
  }
  return links.resolvedSymbol;
}

可见，不论是否能找到 x，都会先调用 getCannotFindNameDiagnosticForName 获取报错文案。

（2）局部变量

resolveName，src/compiler/checker.ts#L1430，会调用 resolveNameHelper，

function resolveNameHelper(
  ...
): ... {
  ...
  loop: while (location) {
    // Locals of a source file are not in scope (because they get merged into the global symbol table)
    if (location.locals && !isGlobalSourceFile(location)) {
      if (result = lookup(location.locals, name, meaning)) {
        ...
      }
    }
    ...
    switch (location.kind) {
      ...
    }
    ...
    lastLocation = location;
    location = location.parent;
  }
  ...

  if (!result) {
    ...
    if (!excludeGlobals) {
      result = lookup(globals, name, meaning);
    }
  }
  if (!result) {
    ...
  }
  if (!result) {
    ...
  }
  ...
  if (nameNotFoundMessage) {
    ...
  }
  return result;
}

while 循环做的主要事情就是，从 x 节点开始不断的向父节点搜索，
检查祖先节点的 locals 属性，其中保存了这个祖先节点作用域内的词法变量。
location 指的是当前正在查找的节点。

在 src/compiler/checker.ts#L1466 打个断点，

function f(){
  x
}

函数没有形参，因此函数声明创建的词法作用域中没有符号，locals 为空 Map。

如果我们修改一下 debug/index.ts，给 f 加上形参 y，在进行调试，

function f(y){
  x
}

（2）全局变量

局部变量保存在了 FunctionDeclaration 节点的 locals 属性中，
全局变量也是一样，也在祖先节点的 locals 属性中，

只是 TypeScript 中，在不同的源码位置对全局变量进行查找，
位于 src/compiler/checker.ts#L1752，

result = lookup(globals, name, meaning);

为什么要区分开来呢？
这是因为，声明在最外层的全局变量，要与 TypeScript 语言内置的一些变量进行合并，例如 Array，Date 这些。

resolveNameHelper 局部变量 lookup 前的注释进行了说明，

Locals of a source file are not in scope (because they get merged into the global symbol table)

局部变量与全局变量，lookup 调用位置关系如下，

function resolveNameHelper(
  ...
): ... {
  ...
  loop: while (location) {
    // Locals of a source file are not in scope (because they get merged into the global symbol table)
    if (location.locals && !isGlobalSourceFile(location)) {
      if (result = lookup(location.locals, name, meaning)) {
        ...
      }
    }
    ...
    lastLocation = location;
    location = location.parent;
  }
  ...

  if (!result) {
    ...
    if (!excludeGlobals) {
      result = lookup(globals, name, meaning);
    }
  }
  ...
  return result;
}

现在我们在全局变量查找位置 src/compiler/checker.ts#L1752 打个条件断点，按 F5 执行，

name === 'x'

我们看到全局范围内有 1812 个名字，包含函数 f，不包含变量 x。

6. 后记

上文我们研究了 TypeScript 变量是否定义的诊断过程，从报错文案出发，
顺藤摸瓜的跟踪了，局部变量和全局变量的查找过程。

一个意外的发现是，ast 节点中可能包含了 locals 属性，其中保存了相关词法作用域中定义的全部变量。
因此我们就可以静态分析出，源码的作用域层次结构了。

然而，从 program 中直接得到的 ast 中是不包含 locals 信息的，

const ts = require('typescript');

const main = filePath => {
  const rootNames = [filePath];
  const options = {};

  const program = ts.createProgram(rootNames, options);

  // program.getGlobalDiagnostics();
  const sourceFile = program.getSourceFile(filePath);
  const { locals } = sourceFile;


  locals;
};

其中，filePath 是待编译源码的绝对地址，我们传入 debug/index.ts 文件地址，
文件内容如下，

function f(){
  x
}

通过对比 tsc 的执行过程，
我们发现是因为 tsc 在编译的时候执行了 program.getGlobalDiagnostics，src/compiler/watch.ts#L165，
位于语义分析 program.getSemanticDiagnostics 之前。

上述代码，我们把注释解除，在获取 sourceFile 之前先执行，

program.getGlobalDiagnostics();

事实上，不执行 program.getGlobalDiagnostics 的话，
节点的 parent 属性也是没有的，我们无法通过叶子节点，向上追溯到 ast 根节点。

至于 program.getGlobalDiagnostics 是怎样为每个节点添加 parent 属性，
又怎样为部分节点计算出 locals 的，等到必要时遇到阻碍时，再详细探究吧。

参考

github: debug-typescript
TypeScipt v3.7.3
TypeScript Compiler API