How to Build a Code Graph in TypeScript Using VS Code's Language APIs

function checkout() {
  processPayment();
}

function processPayment() {
  chargeCard();
}

function chargeCard() {
  saveTransaction();
}

function saveTransaction() {
  // 保存事务
}

{
  "main": "./out/extension.js",
  "engines": {
    "vscode": "^1.85.0"
  },
  "activationEvents": [],
  "contributes": {
    "commands": [
      {
        "command": "codeGraphView.open",
        "title": "Code Graph: Open Graph for Active File",
        "icon": "$(type-hierarchy)"
      }
    ],
    "menus": {
      "editor/title": [
        {
          "command": "codeGraphView.open",
          "group": "navigation",
          "when": "resourceLangId == typescript"
        }
      ]
    }
  },
  "dependencies": {
    "elkjs": "^0.9.3"
  }
}

const extensionConfig = {
  entryPoints: ['src/extension.ts'],
  bundle: true,
  outfile: 'out/extension.js',
  external: ['vscode'],
  format: 'cjs',
  platform: 'node',
};

const webviewConfig = {
  entryPoints: ['webview/main.ts'],
  bundle: true,
  outfile: 'out/webview/main.js',
  format: 'iife',
  platform: 'browser',
};

export interface SymbolRow {
  id: string;
  name: string;
  kind: 'function' | 'method';
  line: number;
  character: number;
}

export interface FileNode {
  id: string;
  label: string;
  file: string;
  symbols: SymbolRow[];
}

export interface CallEdge {
  id: string;
  source: string;
  target: string;
}

export interface GraphData {
  rootFileId: string;
  rootSymbolId?: string;
  roots: string[];
  files: FileNode[];
  edges: CallEdge[];
  truncated: boolean;
}

调用者 → 被调用者

checkout → processPayment

// users.ts
function save() {}

// payments.ts
function save() {}

function idOf(
  uri: vscode.Uri,
  pos: vscode.Position
): string {
  return `${uri.toString()}#${pos.line}:${pos.character}`;
}

function itemId(
  item: vscode.CallHierarchyItem
): string {
  return idOf(
    item.uri,
    item.selectionRange.start
  );
}

/*
 * 使用 VS Code 内置的语言服务而非自行解析代码来获取文档中的所有符号。这样我们可以获取文档中的方法、函数和变量
 */
async function getDocumentSymbols(
  uri: vscode.Uri
): Promise<vscode.DocumentSymbol[]> {

  /*
   * `vscode.executeDocumentSymbolProvider` 将分析委托给
   * 为文档语言注册的语言提供者。
   */

  const result =
    await vscode.commands.executeCommand<
      vscode.DocumentSymbol[] | undefined
    >(
      'vscode.executeDocumentSymbolProvider',
      uri
    );

  // 如果未找到符号则返回空列表。
  return result ?? [];
}

// 检查符号是否可以作为可调用节点处理。
const isCallableKind = (
  kind: vscode.SymbolKind,
  includeConstructors: boolean
) =>
  kind === vscode.SymbolKind.Function ||
  kind === vscode.SymbolKind.Method ||
  (
    includeConstructors &&
    kind === vscode.SymbolKind.Constructor
  );

// 递归地从符号树中收集函数、方法和变量
function collectCandidates(
  symbols: vscode.DocumentSymbol[],
  isCallable: (
    kind: vscode.SymbolKind
  ) => boolean,
  out: vscode.DocumentSymbol[] = []
) {
  for (const symbol of symbols) {
    if (
      isCallable(symbol.kind) ||
      symbol.kind === vscode.SymbolKind.Variable
    ) {
      out.push(symbol);
    } else if (
      symbol.children.length
    ) {
      collectCandidates(
        symbol.children,
        isCallable,
        out
      );
    }
  }
  return out;
}

const handler = () => {
  // ...
};

// 查找包含给定位置的最具体符号。
function symbolAt(
  symbols: vscode.DocumentSymbol[],
  position: vscode.Position
) {
  for (const symbol of symbols) {
    if (symbol.range.contains(position)) {
      return (
        symbolAt(
          symbol.children,
          position
        ) ?? symbol
      );
    }
  }
  return undefined;
}

position → CallHierarchyItem

CallHierarchyItem → incoming/outgoing calls

async function prepare(
  uri: vscode.Uri,
  position: vscode.Position
) {
  // VS Code 的语言工具已经知道如何解析源文件中的符号。
  // 因此我们可以使用它来为该位置的符号准备调用层次结构。
  const items =
    await vscode.commands.executeCommand<
      vscode.CallHierarchyItem[] | undefined
    >(
      'vscode.prepareCallHierarchy',
      uri,
      position
    );

  // 该命令返回一个层次结构项数组。在我们的情况下，
  // 我们关注的是光标直接下方的符号，
  // 因此我们使用第一个结果。
  // 可选链操作符也处理了在给定位置无法解析符号的情况。
  return items?.[0];
}

async function callers(
  item: vscode.CallHierarchyItem
) {
  // 向 VS Code 查询所有调用该项的符号。
  const calls =
    await vscode.commands.executeCommand<
      vscode.CallHierarchyIncomingCall[] | undefined
    >(
      'vscode.provideIncomingCalls',
      item
    );

  // 返回调用符号，默认为空列表（当未找到时）。
  return (
    calls ?? []
  ).map(call => call.from);
}

async function callees(
  item: vscode.CallHierarchyItem
) {
  // 向 VS Code 查询所有被该项调用的符号。
  const calls =
    await vscode.commands.executeCommand<
      vscode.CallHierarchyOutgoingCall[] | undefined
    >(
      'vscode.provideOutgoingCalls',
      item
    );

如果我们有：

并询问processPayment的入站调用，语言API会给我们：

然后我们将这些结果规范化为：

因此，相同的图结构可以表示入站和出站遍历。

## 7. 构建符号注册表

随着我们爬取图结构，相同的符号可能会重复出现。例如：

我们应该为C创建一个节点，而不是三个。注册表提供了这种去重功能。

## 8. 使用BFS遍历图

单次调用层次查找只能提供一步关系。有用的代码图需要多步关系。从A()的查找可能告诉我们它调用B()，但不会告诉我们B()接下来调用什么。

为了构建有用的图，我们需要反复追踪这些关系：A → B → C → D。每次查找都会扩展图的层级，这就是为什么我们需要使用BFS等遍历策略来高效探索多步关系。

例如：

如果我们从A开始并请求深度为三（3步），我们希望得到：

广度优先搜索（BFS）是自然的选择，因为图明确围绕跳转深度组织。遍历维护一个前沿：

一个基本实现如下：

mapLimit 辅助函数用于控制并发的语言服务器请求数量：

关键区别在于 BFS 仅涉及本地计算，而解析符号通常需要请求 VS Code 的语言工具执行实际工作。

每次访问符号时，Code Graph View 可能需要查询语言服务以获取其入向或出向调用。这些查询可能涉及解析源文件、解析符号以及与语言服务器通信。随着图的扩展，这些请求的数量也会随之增长。

因此，尽管遍历本身很简单，但顺序执行这些查询会使整个过程显著变慢。mapLimit 通过允许多个独立的语言工具请求并发执行，同时限制并发数量以避免压垮语言服务，从而解决了这个问题。

## 9. 处理循环

实际代码不是树结构，而是图结构。这意味着循环是正常的。

简单的递归遍历可能会无限循环。因此我们需要跟踪已经探索过的内容。但有一个微妙的细节需要注意。一个简单的：

这意味着，如果我们之前以剩余1跳的状态到达某个节点，但之后又以剩余3跳的状态发现它，我们可以再次探索该节点。这比将节点标记为“已访问”更加精确。

## 10. 图的边界控制

图的规模可能增长得非常迅速。一个高度连接的函数可能有数十个调用者，而这些调用者本身也可能各自拥有数十个调用者。因此，图构建器应设置明确的限制。

当图达到限制时，我们不应假装图是完整的。相反：

生成的GraphData可以向UI说明：

这比让意外庞大的代码库导致扩展程序看似冻结要更好。

## 11. 文件过滤

语言服务器可能会返回与我们正在探索的应用程序无关的文件中的关系。这些可能是构建文件或由依赖项安装或语言特定的构建/运行时操作生成的输出。例如，TypeScript项目可能会引入：

Python项目可能会引入：

在将这些路径添加到图之前，我们可以进行过滤。

这使图保持聚焦于用户的 workspace。这也展示了语言智能与应用程序行为之间的一个重要区别。语言服务器告诉我们它能解析什么，而我们的图构建器决定哪些内容应该成为图的一部分。

## 12. 为什么某些边会无声消失

在大型图中，一些明显相互调用的函数可能会最终没有连接，且没有任何错误报告。问题是CallHierarchyItem与语言服务的状态相关。如果该状态过时，查询其调用者或被调用者可能会返回空数组。从图构建器的角度来看，这看起来就像一个没有调用者的函数。

在VS Code实现中，调用层次结构会话仅保留最近请求的有限数量。我们的爬虫同时可能有多个正在进行的查询，因此在图遍历过程中，旧的条目可能会变得不可用。图构建器通过以下三种方式处理这个问题。

### 1. 它存储的是原始数据，而不是实时项。

每个函数都由一个包含其 ID、URI、名称、类型和位置的 NodeRef 表示。一跳结果也会以 NodeRef 的形式进行缓存。这为我们提供了足够的信息，在需要时可以重新构建调用层次结构项。

### 2. 它会跟踪每个已准备项的时效性

每当准备新的调用层次结构项时，全局纪元计数器会递增。每个句柄会记录其对应项创建时的纪元值。如果某个项变得足够老旧，爬虫会从已存储的 NodeRef 中重新生成一个新的项。

### 3. 它会重试可疑的空结果

简化版的 oneHop 看起来像这样：

此处 lookup 是对之前讨论的 vscode.provideIncomingCalls 或 vscode.provideOutgoingCalls 命令的简写。会话时限的具体数值是 VS Code 的实现细节，而非扩展应依赖的内容。因此爬虫不会假设特定的限制始终存在。SESSION_WINDOW 仅为我们提供了一个保守的阈值，用于刷新老旧句柄。

这减少了丢失的边，但无法保证构建完整的图。语言工具仍可能返回不完整的信息或无法解析某些关系。

这个更广泛的经验教训适用于超出调用层次结构的语言服务 API：存储能够从语言服务重新构建对象所需的信息，而不是对象本身。将来自过期状态的空结果视为潜在未知，而非自动视为无。

## 13. 将图连接到 Webview

一旦构建了图，扩展就需要一个显示它的位置。VS Code 的 Webview 非常适合这个用途。

扩展宿主创建面板：

图以可序列化的数据形式发送到 Webview：

Webview 随后可以接收它：

到此为止，问题中语言服务器部分的实现已经完成。

我们已经将：

转换为：

然后进一步转换为：

可视化层现在可以使用这些数据来渲染图。

可以使用 ELK 这样的库来计算图的布局，而不会影响图构建的逻辑。

## 14. 测试图构建器

如果每个测试都需要运行 VS Code 实例和真实语言服务器，这种扩展的测试会变得很困难。更好的方法是将图构建逻辑与 VS Code 本身隔离。爬虫只需要以下几个操作：

我们可以为这些命令创建模拟实现。例如：

模拟可以建模过期调用层次状态等边界情况。重要的是，如果模拟使用特定的会话限制，这应被理解为测试模型，而不是自动视为官方 VS Code API 的保证。

然后我们可以生成一个确定性的图，并将爬虫的输出与简单的参考 BFS 进行比较。

参考实现知道预期的边。生产环境的爬虫会针对模拟语言服务运行。如果两个结果不同，测试就会失败。这种方法让我们可以在不完全依赖编辑器运行时的情况下测试复杂的图逻辑。

## 15. 代码图的局限性

基于语言服务器的调用图很有用，但它并不是程序执行的完整表示。有些关系可能难以或无法通过静态调用层次分析来解析。

例如包括：

- 动态调度

- 反射

- 依赖注入

- 事件发射器

- 回调

- 运行时生成的代码

- 框架特定行为

考虑以下代码：

开发者可能明白这会在事件和 handlePayment 之间创建运行时关系。静态调用图可能不会将这种关系表示为普通函数调用。因此，图的质量在很大程度上取决于语言服务器以及它能解析的关系类型。

这就是为什么应该将图理解为语义近似，而不是完美的运行时模型。还存在语言特定的维度。

图构建器本身可以保持大部分语言无关性，但不同的语言扩展可能为文档符号和调用层次提供不同级别的支持。

## 结论

构建代码图并不需要从头编写编译器或实现解析器。VS Code 通过其语言 API 已经暴露了大量语义信息。

核心流程如下：

最重要的工程决策并不在于绘制图表本身。它们涉及选择有用的图模型、创建稳定的符号标识、正确解释入栈和出栈调用、控制遍历深度和并发性、处理循环，以及将语言服务器状态视为可能变化的实体。

一旦这些基础模块就位，可视化就变成了一个独立的问题。这种分离正是使该架构超越单一 VS Code 扩展的实用性所在。

相同的图模型最终可以用于依赖关系探索、变更影响分析、架构视图、AI 上下文选择，以及导航日益复杂的代码库的其他方式。

我基于此构建了一个可用版本，可通过以下链接访问：https://github.com/otobongfp/code-graph-view 。

我期待看到你们基于图结构为软件工程流程创造出的所有精彩应用。

合作伙伴推荐课程

(opens in a new tab)

ADVERTISEMENT

- Udemy 上的 TypeScript 入门 Daniel Stern 4.2（8,809 人评分） 1小时6分钟 中级 查看课程 (opens in a new tab)
- Udemy 上的 React & TypeScript 扩展开发 Jason Xian 4.6（1,420 人评分） 8小时52分钟 初级 证书 查看课程 (opens in a new tab)
- Coursera 上的 TypeScript 入门 Per Harald Borgen 和 Ania Kubow 4.6（60 人评分） 4周，每周1小时 中级 证书 查看课程 (opens in a new tab)
- Coursera 上的 TypeScript 变量与数据类型 Chaitra Deshpande 4.4（104 人评分） 1小时55分钟 初级 证书 查看课程 (opens in a new tab)

更多 TypeScript 课程请访问 Class Central

→

构建项目

如果你读到了这里，请感谢作者以表达你的支持。说声谢谢

免费学习编程。freeCodeCamp 的开源课程已帮助超过 40,000 人成为开发者。立即开始