A CLI tool that parses Rust codebases and generates multi-layered, LLM-friendly index files for efficient codebase comprehension without full-file scanning.

Given a Rust project, rsmap produces four output files:

Plus an annotation system (annotations.toml) that lets you attach LLM-generated descriptions to items and track staleness across rebuilds.

cargo install rsmap

Or build from source:

cargo build --release

# Index the current directory
rsmap generate

# Index a specific project
rsmap generate --path /path/to/project

# Force full rebuild (ignore cache)
rsmap generate --no-cache

# Custom output directory
rsmap generate --output my-index/

Output goes to .codebase-index/ by default (relative to the project path).

Export unannotated items for LLM consumption:

rsmap annotate export --path /path/to/project > to_annotate.toml

This outputs a structured prompt with item signatures that need descriptions. Feed it to an LLM, get back filled-in TOML, then import:

rsmap annotate import annotated.toml

Annotations are merged into annotations.toml and appear inline in Layer 0 and Layer 1 outputs on the next generate.

See the full output in rsmap-index/.

# Crate: rsmap (bin)
Edition: 2021
Version: 0.1.0
External deps: anyhow, blake3, cargo_metadata, chrono, clap, proc-macro2, quote, serde, serde_json, syn, toml, walkdir

## Module Tree
- crate
  - annotations
  - cache
  - layer0
  - layer1
  - layer2
  - layer3
  - metadata
  - model
  - output
  - parse
  - resolve

## Trait Implementations
std :: fmt :: Display <- CrateKind, ItemKind, Visibility

## Module Dependencies
annotations -> cache, model
cache       -> model
layer0      -> annotations, model, output
layer1      -> annotations, model
layer2      -> model
layer3      -> model
metadata    -> model
parse       -> metadata, model
resolve     -> cache, metadata, model, parse

## Key Types (referenced from 3+ modules)
Module          — used in 8 modules
CrateInfo       — used in 7 modules
Item            — used in 5 modules
Path            — used in 5 modules
PathBuf         — used in 4 modules
AnnotationStore — used in 3 modules
Cache           — used in 3 modules
Visibility      — used in 3 modules

Files are hashed with BLAKE3. On subsequent runs, only changed files are re-parsed. All layer files are regenerated (they're cheap to write; parsing is the expensive part).

When an item's source changes between runs:

• Its annotation is marked stale = true
• New items get empty annotations
• Removed items are marked removed = true (not deleted, for reference)

src/
  main.rs           — CLI entry (clap), subcommands
  model.rs          — Data model: CrateInfo, Module, Item, etc.
  parse.rs          — syn-based source parsing, signature extraction
  metadata.rs       — cargo_metadata integration (workspace, deps)
  resolve.rs        — Module tree building, path resolution
  layer0.rs         — Overview generator (crate/module map)
  layer1.rs         — API skeleton generator (all signatures)
  layer2.rs         — Relationship graph generator
  layer3.rs         — JSON index generator (file:line lookup)
  annotations.rs    — Annotation file management + merge
  cache.rs          — File hashing, incremental rebuild
  output.rs         — Markdown/text formatting utilities

• syn — Rust source parsing (full AST)
• cargo_metadata — Workspace/crate structure, external deps
• clap — CLI
• serde / serde_json / toml — Serialization
• walkdir — Source file discovery
• blake3 — Fast file hashing
• anyhow — Error handling

This repo includes a SKILL.md — a prompt that teaches AI agents how to use rsmap, read the layered output, and run the annotation workflow. Paste the contents into your agent's system prompt or custom instructions.

MIT