方舟分析器：面向ArkTS语言的静态程序分析框架

什么是 ArkAnalyzer？

ArkAnalyzer 是针对基于 ArkTS 语言开发的鸿蒙原生应用的静态代码分析框架，支持 ArkTS、TypeScript、JavaScript、C/C++ 作为输入，通过将它们转换为统一的三地址码（ArkAnalyzer-IR, ArkIR）中间表示，构建 Scene 数据结构对代码结构进行抽象，并进行 Scene 实现一系列静态分析。

ArkAnalyzer 环境配置

1. 从 Download Visual Studio Code 下载 VS Code 并安装，或安装其他 IDE。
2. 从 Download Node.js 下载 Node.js 并安装（自带 npm）。
3. 安装依赖库：

npm install

4. 【可选】使用 Docker 开发环境（x86_64 Linux）：

# 构建镜像
docker build --platform linux/amd64 -f Dockerfile.dev -t arkanalyzer:dev-amd64 .

# 启动容器（挂载 SDK 和源码；源码修改即时生效）
docker run --platform linux/amd64 -it \
  -v /path/to/command-line-tools:/workspace/command-line-tools \
  -v $(pwd):/workspace/arkanalyzer \
  arkanalyzer:dev-amd64

5. 【可选】生成最新 API 文档，输出目录为 docs/api_docs：

npm run gendoc

ArkAnalyzer 命令行（CLI）

可执行入口为 arkanalyzer（见 package.json 的 bin 字段）。本地使用 CLI 前请先编译，生成 lib/：

npm run build

查看帮助：

npx arkanalyzer --help
npx arkanalyzer cg --help
npx arkanalyzer ir --help

<input> 均指 ArkTS/TypeScript 工程根目录。

cg：调用图构建与可达性分析

用法：arkanalyzer cg <input> [options]

| 选项 | 说明 | 默认值 | |------|------|--------| | -a, --algorithm <name> | 构图算法：cha | rta | rta | | -o, --output <file> | 结果输出文件路径 | stdout | | -f, --format <type> | 输出格式：json | text | dot | csv | json | | -e, --entry <method> | 入口方法，可多次指定；@dummyMain 表示与默认入口一致 | 自动推断 | | -r, --reachable-from <method> | 可达性分析根方法，可多次指定 | — | | --direction <dir> | 可达方向：forward（顺调）| backward（谁调到根） | forward | | --edges <type> | 边类型过滤：call | virtual | interface | all | all | | --ohos-sdk-home <path> | OpenHarmony SDK 根路径；未设置时读取环境变量 OHOS_SDK_HOME | — |

示例：

npx arkanalyzer cg ./myapp -a rta -f json
npx arkanalyzer cg ./myapp -e "@dummyMain" -r MyClass.myMethod --direction backward -f text

ir：导出工程 IR 产物

用法：arkanalyzer ir <input> [options]

| 选项 | 说明 | 默认值 | |------|------|--------| | -o, --output <dir> | 产物输出目录 | out | | -f, --format <type> | json | text | dot | text | | --ohos-sdk-home <path> | 同 cg | — | | --no-infer-types | 跳过 Scene.inferTypes() 以加快执行 | 默认会做类型推断 |

命令会在标准输出打印一行 JSON 摘要（含 input、format、outputDir、fileCount 等）。

示例：

npx arkanalyzer ir ./myapp -f text -o ./out
npx arkanalyzer ir ./myapp -f json -o ./out

更细的参数语义与典型用法可参考仓库内 skills/arkanalyzer/skills/cg.md、skills/arkanalyzer/skills/ir.md。

ArkAnalyzer 文档

1. ArkAnalyzer 快速入门文档，请参考：链接。
2. 完整使用说明请参考：ArkAnalyzer 使用文档
3. ArkAnalyzer API文档，请参考：链接。
4. 程序分析 SIG 说明：简体中文 · English。

支持的使用场景（分语言）

ArkAnalyzer 把所有支持的源语言统一编译成 ArkIR（三地址中间表示），下游分析（CallGraph、Def-Use Chain、数据流分析、ViewTree 等）对所有语言透明可用。各语言成熟度差异主要在 前端解析覆盖度 与 类型推导精度，详见 docs/MultiLanguageSupport.md。

| 语言 | Language 枚举值 | IR 转换 | 类型推导 | 调用图 (CHA / RTA) | Def-Use / 过程内数据流 | ViewTree | 备注 | |------|------------------|---------|---------|--------------------|----------------|----------|------| | ArkTS | ARKTS1_1 | ✅ 完整 | ✅ 完整（含装饰器） | ✅ | ✅ | ✅ | HarmonyOS 主语言；唯一支持 ArkUI 视图树的语言 | | TypeScript | TYPESCRIPT | ✅ 完整 | ✅ 完整 | ✅ | ✅ | — | 通用 TS 工程；含命名空间、泛型、装饰器、type/interface 等全部 TS 4.x 语法 | | JavaScript | JAVASCRIPT | ✅ 基础 | ⚠ 受限（缺类型注解时退化为 UnknownType） | ✅ | ✅ | — | 适合用于动态调用关系勾画；精确分析建议先用 TS 注解 | | C / C++ | CXX | ✅（cppFrontend） | ⚠ 部分 | ✅ | ✅ | — | 依赖 cppAstPath / ccjsonPath；含 VIRTUAL、INLINE、CONSTEXPR、MUTABLE 等修饰符；用于鸿蒙 native 模块 | | ABC（ArkCompiler bytecode） | ABC | ⚠ 实验 | — | — | — | — | 直接读取编译产物，主要用于 IR 验证 |

典型场景：

• HarmonyOS / ArkTS 应用：ArkUI 视图树分析（ViewTree）+ 状态依赖追踪 + @State 副作用检查；多 module 工程通过 Scene.buildScene4HarmonyProject() 自动识别。
• TS / JS 库或服务端项目：CallGraph（CHA / RTA）+ Def-Use Chain + 数据流分析（MFPDataFlowSolver、到达定值或自建数据流问题）。
• TS / ArkTS 与 C/C++ 混合工程：通过 ArkClass.getTs2cxxFuncMap() 把 TS 侧 napi_* 调用与 C/C++ 实现关联，做跨语言可达性分析。

更细粒度的语言能力矩阵与 IR 差异说明请参见 docs/MultiLanguageSupport.md。

UT 日志开关

Vitest 单测默认静默运行，不输出详细 UT 日志。

需要排查问题时可通过环境变量 V=1 开启详细日志（包含控制台输出与 output/ArkAnalyzerUT.log 文件日志）：

V=1 npx vitest run

参与贡献

如在使用过程中遇到问题，可参考 Issue 提交指南 提交Issues 欢迎参与项目共建，提交 PR 请遵循 openharmony-sig 代码仓规范，具体流程请参考：PR 提交流程说明 提交 PR

版本演进

项目版本演进及历史变更记录请参考：CHANGELOG