# @flisk/swift-ast 中文文档

规范地址：https://npmcn.com/package/%40flisk/swift-ast/

版本：0\.1\.4
npm 元数据更新时间：2026-01-03T03:42:49.739Z
中文译文更新时间：2026-11-14T23:25:53.839Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40flisk/swift-ast
原文对照：https://npmcn.com/package/%40flisk/swift-ast/?lang=original
项目主页：https://github.com/fliskdata/swift-ast#readme
源码仓库：https://github.com/fliskdata/swift-ast

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：26.6 MB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.17
- 运行依赖：0 个
- 首次发布：2025-09-25T20:06:25.696Z
- 最新版本发布：2026-01-03T03:42:48.960Z
- 近 30 天下载量：13600（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 1 个）

## 中文简介

Swift AST通过WebAssembly(WASI)在节点解析,由SwiftSyntax + SwiftParser提供动力.

## 安装

```sh
npm install @flisk/swift-ast
```

也可以使用：`pnpm add @flisk/swift-ast`、`yarn add @flisk/swift-ast`、`bun add @flisk/swift-ast`

## README

# @flisk/swift-ast (英语)

Swift AST通过WebAssem在JavaScript中解析,由SwiftSyntax + SwiftParser提供动力.

[![NPM version](https://img.shields.io/npm/v/@flisk/swift-ast.svg)](https://www.npmjs.com/package/@flisk/swift-ast) [![Tests](https://github.com/fliskdata/swift-ast/actions/workflows/checks.yml/badge.svg?branch=main)](https://github.com/fliskdata/swift-ast/actions/workflows/checks.yml)

## 导言

这个软件包将 SwiftSyntax + SwiftParser 编译为 WASI 模块,并将一个简单的 JavaScript API 将 Swift 源解析成一个紧凑的 JSON AST. 此外,它还提供了轻量级分析器(由Ruby Prism的ergonomics所启发),用于:

-   提取声明(功能、方法、类、结构、enum、变量)
-   查找和检查函数/方法调用(带有被调用人链和基准标识符)
-   遵循词汇范围内的简单标识引用
-   表面天真类型提示(例如, `let x: Int`(中文(简体) )

它设计用于程序分析管道 [`@flisk/analyze-tracking`](https://github.com/fliskdata/analyze-tracking) 也可以作为CLI 与 `npx`。 。 。 .

## 快速启动( CLI)

不安装运行 :

```bash
npx @flisk/swift-ast /path/to/file.swift
```

此打印解析的 AST JSON 到 studout .

## 安装

```bash
npm i @flisk/swift-ast
```

## 程序化 API

### 解析到 JSON AST

```ts
import { parseSwiftAst } from '@flisk/swift-ast';

const source = `
struct Foo {
  let x: Int
  func bar(_ y: Int) -> Int { x + y }
}
`;

const ast = await parseSwiftAst(source);
console.dir(ast, { depth: null });
```

AST 形状( 简化后):

```json
{
  "root": 0,
  "nodes": [
    { "kind": "SourceFileSyntax", "range": { "start": {"offset":0}, "end": {"offset":123} } },
    { "kind": "StructDeclSyntax", "name": "Foo", "range": { /* ... */ } },
    { "kind": "FunctionDeclSyntax", "name": "bar", "range": { /* ... */ } }
  ],
  "edges": [[0,1],[1,2]]
}
```

基于文件的解析也有方便:

```ts
import { parseSwiftFile } from '@flisk/swift-ast';
const astFromFile = await parseSwiftFile('path/to/file.swift');
```

### AST 分析器

```ts
import { analyzeAst } from '@flisk/swift-ast';

const analysis = analyzeAst(ast, source);

// All declarations by name
console.log([...analysis.byName.keys()]);

// All calls to a function/method named "track"
const calls = analysis.findCallsByName('track');
for (const c of calls) {
  console.log({
    name: c.name,
    receiver: c.receiver,
    base: c.baseIdentifier,
    chain: c.calleeChain,
    args: analysis.getCallArgs(c.id)
  });
}

// Resolve a simple name to its symbol (best-effort)
const symbol = analysis.resolveNameAt('bar', /*offset*/ 0);
console.log(symbol?.kind, symbol?.name);
```

分析器返回类型( 高级) :

```ts
type Analysis = {
  symbols: Map<number, SymbolInfo>;
  calls: CallInfo[];
  refs: RefInfo[];
  byName: Map<string, number[]>;
  findCallsByName(name: string): CallInfo[];
  resolveNameAt(name: string, offset: number): SymbolInfo | undefined;
}
```

注释:

-   仅由语法驱动(没有完整的类型检查器). 名称解析是词汇学和最优的.
-   展出帮助简化跟踪分析:被标记为args,字典提取,包含符号查找,const字符串集合,以及被调用者的文本/链条等公用事业.

## CLI 使用情况

```bash
# Print AST JSON
npx @flisk/swift-ast /path/to/file.swift

# With a local install
swift-ast /path/to/file.swift > ast.json
```

## 食谱

-   **列出所有类/结构名称**

```ts
const decls = [...analysis.symbols.values()].filter(s => s.kind === 'class' || s.kind === 'struct');
console.log(decls.map(d => d.name));
```

-   **查找特定 API 的所有调用符( 如分析)**

```ts
const hits = analysis.findCallsByName('track');
for (const call of hits) {
  // receiver could be an instance, a type, or omitted
  console.log(`${call.receiver ? call.receiver + '.' : ''}${call.name} at ${call.range.start.line}:${call.range.start.column}`);
}
```

-   **获取变量的天真类型信息**

```ts
const vars = [...analysis.symbols.values()].filter(s => s.kind === 'variable');
for (const v of vars) {
  console.log(v.name, '::', v.typeAnnotation ?? '(inferred)');
}
```

## 环境

-   18号节点(使用内置) `node:wasi`) (中文(简体) ).
-   运行时不需要本地Swift工具链; Wasm 二进制船与 npm 包.

## 发展(捐助者)

1.  通过 Swift 安装 [快点](https://www.swift.org/install)
2.  安装 Swift 6.2 : `swiftly install 6.2`
3.  选择 Swift 6.2 : `swiftly use 6.2`
4.  为 WASI 安装 SDK :

```bash
swift sdk install https://download.swift.org/swift-6.2-release/wasm/swift-6.2-RELEASE/swift-6.2-RELEASE_wasm.artifactbundle.tar.gz --checksum fe4e8648309fce86ea522e9e0d1dc48e82df6ba6e5743dbf0c53db8429fb5224
```

5.  运行 `swift sdk list` 并确保 `SWIFT_SDK_ID` 设定为相应的 SDK.
6.  构建 WASM 二进制 : `npm run build`
7.  运行测试 : `npm test`

注:SwiftSyntax版本被绑定在用于构建WASM的Swift工具链上. 如果您在本地重建, 请确保匹配 `swift-syntax` 用于工具链的标签.

## 常见问题

### @flisk/swift-ast 是什么？

Swift AST通过WebAssembly\(WASI\)在节点解析,由SwiftSyntax \+ SwiftParser提供动力\.

### 如何安装 @flisk/swift-ast？

在项目目录运行 npm install @flisk/swift-ast，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 swift-ast，可以用 npx swift-ast 直接运行。

### @flisk/swift-ast 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @flisk/swift-ast 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @flisk/swift-ast 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.17。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @flisk/swift-ast 可以商用吗？

@flisk/swift-ast 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @flisk/swift-ast 的下载量有多少？

根据 npm 官方下载统计，@flisk/swift-ast 在 2026/10/15 – 2026/11/13 这 30 天内被下载 13,600 次，日均约 453 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @flisk/swift-ast 还在维护吗？

最新版本 0\.1\.4 发布于 2026/01/03（10 个月前）；至今共发布 5 个版本，其中过去 12 个月发布了 1 个；首次发布于 2025/09/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。