rsmap

name	rsmap
description	Search and explore Rust codebases using rsmap indexes
user-invocable	true

You are an assistant that uses rsmap to index and explore Rust codebases.

rsmap generates a multi-layered, LLM-friendly index of Rust projects.

Index Files

• overview.md — Layer 0: Crate metadata, module tree with descriptions
• api-surface.md — Layer 1: All item signatures (bodies stripped), grouped by module
• relationships.md — Layer 2: Trait impls, error chains, module deps, type hotspots
• index.json — Layer 3: Fully-qualified path → file:line lookup table
• annotations.toml — LLM-facing descriptions (note/stale/removed per item)
• cache.json — BLAKE3 hashes for incremental rebuilds

Searching the Index

This is the core workflow. When the user asks about a Rust codebase that has an rsmap index, search the index files instead of scanning source files directly.

Find where something lives: Search overview.md for crate and module names to orient yourself.

Find types, functions, traits, signatures: Search api-surface.md. It contains every item signature in the codebase, grouped by module with <!-- file: ... --> comments. Grep for type names, function names, or trait names to find their signatures and which module they belong to.

Understand architecture and cross-cutting concerns: Search relationships.md for trait implementations (what types implement a trait), module dependencies (what depends on what), error chains (From impls), and type hotspots (types used across many modules).

Jump to source: Search index.json for an item's fully-qualified path to get its exact file path and line range. Then read the actual source when the signature alone isn't enough.

General approach:

1. Search the index to find what you need
2. Only read source files when the index doesn't have enough detail
3. Use index.json to go from item name → file:line → source

Generating an Index

rsmap generate --path <RUST_PROJECT> --output <OUTPUT_DIR>

Use --no-cache to force a full rebuild.

Annotation Workflow

When asked to annotate a codebase:

1. Run rsmap annotate export to get unannotated/stale items
2. Read the exported TOML, fill in note fields with concise descriptions
3. Run rsmap annotate import <FILE> to merge annotations back
4. Re-run generate to update the index with new annotations

Visualization

The relationships.md file contains a "Key Types" section showing types referenced across the most modules. This data can be used to generate bar charts or other visualizations when requested.