cargo-atlas: Compiler-Accurate Code Maps for AI Assistants in Rust

Overview

cargo-atlas is a new open-source tool designed to provide AI coding assistants with compiler-accurate code maps for Rust workspaces. Unlike traditional search-and-replace methods that guess based on function names, this utility leverages the resolution power of rust-analyzer to map out exact relationships between code elements. The primary goal is to enable advanced AI agents, such as Claude Code, to answer complex queries like "who calls this?" or "what implements this trait?" with precise file:line citations rather than unverified greps.

The project, currently at version 0.1, addresses a significant gap in the current landscape of AI-assisted development. While language models can generate plausible-sounding code, they often lack the deep structural understanding required to navigate large Rust codebases where type inference and trait implementations create ambiguity. By building a graph of function dependencies that is validated by the compiler itself, cargo-atlas aims to reduce hallucination and improve the reliability of automated code analysis.

"Ask 'who calls this?' or 'what implements this trait?' and get exact answers with file:line, instead of an assistant grepping through files."

Technical Architecture and Accuracy

The core differentiator of cargo-atlas is its reliance on type information rather than simple string matching. In Rust, two different structs can both define a method named parse(). A name-based tool cannot determine which specific function a call site refers to without knowing the type of the variable being called on. cargo-atlas integrates with the SCIP (Scalable Code Intelligence Protocol) output from rust-analyzer, which provides exact symbol resolution for every definition and reference in the workspace.

This approach yields significantly higher accuracy than existing solutions. Benchmarks on the ripgrep 15.1.0 codebase illustrate the difference:

• 50 random call links verified by manual code inspection were all correct.
• 150 random call sites taken from source text were successfully resolved to their target workspace functions.
• The tool identified 5,948 function-to-function call links, compared to 2,809 found by a competitor tool called Graphify.
• Approximately 39% of Graphify's comparable links pointed to the wrong function, highlighting the risk of name-based guessing.

The system consolidates three data sources into a single graph. rust-analyzer SCIP lists definitions and references, resolving them to exact symbols with full span data. Cargo metadata provides the crate dependency structure. A separate pass using the syn crate parses source text to find impl headers and #[derive] attributes. Each link in the resulting graph carries a confidence label, such as EXACT for compiler-resolved links or CANDIDATE for dynamic trait calls where the runtime implementation is not statically known.

User Workflow and Command Interface

Developers interact with the tool through a suite of CLI commands that generate and query the code map. The primary workflow begins with indexing the workspace using cargo atlas build, which produces a graph.json file stored in the .atlas directory. This process requires the installation of specific Rust components:

1. rustup component add rust-analyzer rust-src
2. cargo install --path .

The rust-src component is critical; without standard library source code, rust-analyzer cannot expand macros like println! or infer standard types, leading to missing links in the graph. Once the index is built, users can query specific relationships:

• cargo atlas callers JsonReader::parse: Identifies all functions that call the specified method.
• cargo atlas callees run: Lists all functions called by the specified target.
• cargo atlas impls Loader: Displays types that implement a specific trait, or traits implemented by a specific type.
• cargo atlas explain run: Provides a detailed breakdown including kind, location, signature, and all links.

The output is structured to be machine-readable yet human-usable. For example, when querying the callees of run, the tool distinguishes between exact calls to concrete functions and candidates for trait objects. If a function accepts a &dyn Loader, the tool lists the specific trait method as an EXACT link and the potential implementing structs as CANDIDATE links. This nuance allows AI agents to understand the boundaries of static certainty.

Limitations and Future Development

Despite its high accuracy, the tool operates within specific constraints inherent to Rust's type system and the current state of compiler infrastructure. Blanket implementations, such as impl<T: Area> Named for T, do not link to concrete types because the type variable T is not resolved to a specific struct. Similarly, shared symbols can create ambiguity; rust-analyzer may assign the same symbol to different items, such as main in both build.rs and src/main.rs. Links involving these shared symbols are marked as CANDIDATE to reflect this uncertainty.

The tool also relies on the stability of the rust-analyzer scip interface, which is currently experimental. It has been tested with version 0.3.3057. Proc macros that expand code only upon successful compilation will result in missing data if the macro fails to build. Additionally, only default Cargo features are indexed, meaning feature-gated code paths are not included in the map.

Looking ahead, the development team plans to release an MCP (Model Context Protocol) server and dedicated skills for Claude Code. This will allow AI agents to query the code map directly during agentic workflows, moving from a prototype stage to a production-ready integration. The project is licensed under MIT OR Apache-2.0 and includes a decision log in DECISIONS.md to document architectural choices. As AI coding assistants become more prevalent, tools that ground their responses in compiler-verified facts like cargo-atlas are likely to become essential for maintaining code integrity in complex Rust ecosystems.