Cargo-atlas：为 AI 编码 Agent 构建编译器级精度的 Rust 代码图谱

Cargo-atlas 是一款仍处于 0.1 原型阶段的开源工具，目标是用编译器级别的精度为 Rust 工作区构建调用图，使 Claude Code 等 AI 编码助手在回答「谁调用了这个函数」「哪个类型实现了这个 trait」时，不再依赖简单的名称匹配，而是给出 file:line 级别的准确定位。项目以 MIT 或 Apache-2.0 双协议开源。

解决的问题：名称匹配的歧义

现有的「按函数名匹配」类工具在 Rust 项目中容易出错。例如两个 struct 都有 parse() 方法，仅靠名字无法判断 r.parse() 实际调用的是哪一个。rust-analyzer 可以解析 r 的真实类型，因此能给出确定答案。作者在测试用例（tests/fixtures/spike）中对比了 Cargo-atlas 与 Graphify：

50 个随机调用链接（人工核对代码）：全部正确；
150 个随机调用点：所有指向工作区内函数的调用均被找到；
ripgrep 15.1.0 中，Cargo-atlas 找到 5,948 个函数间调用链接，Graphify 仅找到 2,809 个；
Graphify 中 39% 的「可比链接」指向了 rust-analyzer 实际解析出的不同函数。

复现步骤见 bench/README.md。

核心命令

安装需要先添加 rust-analyzer 和 rust-src 组件（标准库源码缺失会导致 println! 等宏无法展开、std 类型推断失败）。常用子命令包括：

cargo atlas build：将工作区索引到 .atlas/graph.json；
cargo atlas callers <name>：查询谁调用了目标；
cargo atlas callees <name>：查询目标调用了谁；
cargo atlas impls <Trait> / <Type>：查询实现或被实现的 trait；
cargo atlas path <a> <b>：分析两节点间的路径；
cargo atlas explain <name>：输出种类、位置、签名及所有链接；
cargo atlas report：在 .atlas/report.md 生成汇总。

目标项可通过短名（如 parse）、路径（如 JsonReader::parse）或源码位置（如 src/json_reader.rs:10）三种方式指定。短名匹配多个项时会列出候选，例如 cargo atlas callers parse 会同时给出 CsvReader::parse 与 JsonReader::parse 两个定义位置。

实现原理

图谱由三类数据汇合而成：

rust-analyzer 的 scip 输出：枚举工作区内的每个定义和引用，并解析到唯一符号；引用归属其所在函数；
cargo metadata：提供 crate 及其依赖关系；
一次 syn 遍历：解析 impl 头与 #[derive] 列表，将宏派生关联到具体的类型和 trait。

每条链接附带可信度标签：EXACT（由 rust-analyzer 或 Cargo 解析得出）、CANDIDATE（如 dyn Trait 调用存在多个可能目标）、SYNTAX（从源码文本读取但未做类型检查，如 derive 展开）。

已知限制

blanket impl（如 impl<T: Area> Named for T）没有具体类型，无法被链接；
build.rs 与 src/main.rs 中的同名 main 会被 rust-analyzer 视为同一符号，Cargo-atlas 仍为各自建节点，但指向它们的链接会被标记为 CANDIDATE；
过程宏（如 #[tokio::main]、sqlx::query!）仅在成功编译时展开；
仅索引默认 Cargo features；
依赖 rust-analyzer 0.3.3057 验证，scip 接口并非稳定 API。

开发计划方面，MCP 服务器与 Claude Code skills 将在后续版本中加入；CI 在每次推送时运行 fmt、clippy 与测试，端到端测试依赖 rust-analyzer 与 rust-src，可通过 CARGO_ATLAS_SKIP_RA_TESTS=1 跳过。详细设计权衡记录在 DECISIONS.md。