Expand description
§sealmap-dense
The compact agent projection of a sealmap_model::Codebase: what an
LLM agent reads instead of the source, or instead of a Mermaid corpus,
when it needs the shape of a codebase. Measured on sealmap’s own tree it
costs well under half the bytes of the source it describes, while carrying
what source leaves implicit: the resolved call graph, with every edge
marked exact, inferred or external.
The projection is a pure function of the model: the same codebase and options give byte-identical text on every run and every machine.
§What it writes
Dense::render produces two texts, normally written to
TEXT_FILE and INDEX_FILE:
# sealmap-dense 1 warehouse: L<a>-<b> source lines; @name short names (see _index.txt); calls ~inferred ?external, ^ expanded above, ↺ cycle, … cut; tree roots: bare = entry point, … = continued, ↺ = cycle-only
# symbols
## src/inventory.rs
pub trait StockStore { fn reserve(&mut self, sku: &str, qty: u32) -> Result<(), StockError>, fn lookup(&self, sku: &str) -> u32 } L3-9 @StockStore
pub struct InventoryLedger { levels: BTreeMap<String, u32>, journal: Vec<String> } : StockStore L17-20 @inventory/InventoryLedger
pub fn reserve(&mut self, sku: &str, qty: u32) -> Result<(), StockError> L33-40 @InventoryLedger.reserve
…
# calls
place
orders/validate(&order)
loop each via all
inventory/validate(&line.sku)
opt !validate(&order)
return Ok(0)
loop for line in &order.lines
InventoryLedger.reserve(&line.sku, line.qty)?
StockStore.available(sku)
opt have<qty
return Err(StockError::Short { sku: sku.into(), wanted:…
InventoryLedger.record(_)
notify(len()).await
?serde_json::to_string(&count)- Skeleton lines, one per symbol, grouped by file and in source order:
visibility, the signature as written (or the kind and name), fields or
variants inline (field visibility is left out), implemented traits after
:, the line spanL<start>-<end>, and the short name after@. - Call trees, each call indented one space under its caller, with
alt/else,opt,loop,par/andand early-exit lines from the flow. Every callable is expanded once: afterwards a call to it ends in^, a call back into a callable still being expanded ends in↺, and a call reached at the depth limit ends in…. So the trees grow with the number of call sites, not the number of paths, and every call site appears exactly once. - Tree headers (unindented lines) say why the tree exists: a bare name
is an entry point, which nothing in the codebase calls;
name …continues a call cut above;name ↺is a callable reached only through a cycle. - Confidence marks prefix a call: nothing for exact,
~for inferred,?for external. A trailing.awaitor?is the call site’s own. Internal callees are named by short name, others by their path. - The index (
_index.txt), one line per symbol ordered by short name:<short> <sym:id> <path>:L<start>-<end>. The short name is the first field and contains no whitespace; the location is the last field (%and whitespace in a path are percent-encoded); thesym:id is everything between.
Short names are unique within an output and derived from the ids alone:
Db.insert for a method, connect for a function, db/ for a module.
Where two symbols would share one, both are qualified, step by step:
the trait-impl block (Db[Store].put), the module path (db/Db.put),
the package (shop:db/Db.put), then a hash of the id.
§Slices
Dense::slice is what a review pack (sealmap_corpus::pack) embeds: the dense text for a set of
symbols plus their callers and callees to a depth, with its own index
section, byte-identical for identical inputs. With a byte budget it
refuses an oversized slice with SliceError::OverBudget, naming the
overflow and the size of each seed alone, rather than truncating.
§Example
use sealmap_model::*;
use sealmap_dense::{Dense, DenseOptions, SliceError, SliceOptions};
let pkg = Package::current("cargo", "shop").unwrap();
let root = SymbolId::package_root(pkg);
let db = root.child(Descriptor::r#type("Db")).unwrap();
let insert = db.child(Descriptor::method("insert")).unwrap();
let place = root.child(Descriptor::method("place")).unwrap();
let file = SourcePath::new("src/lib.rs").unwrap();
let mut cb = Codebase::new("shop");
cb.add_symbol(Symbol::new(db.clone(), "Db", SymbolKind::Struct, file.clone()));
let mut m = Symbol::new(insert.clone(), "insert", SymbolKind::Method, file.clone());
m.signature = Some("pub fn insert(&mut self, id: u64)".into());
m.visibility = Visibility::Public;
m.span = Span::new(4, 5, 6, 6);
cb.add_symbol(m);
let mut f = Symbol::new(place.clone(), "place", SymbolKind::Function, file.clone());
f.signature = Some("fn place(db: &mut Db)".into());
f.span = Span::new(8, 1, 10, 2);
f.flow = Some(Flow::new(vec![Step::Call(Call::new(insert.clone(), "insert(7)", Confidence::Exact))]));
cb.add_symbol(f);
let dense = Dense::new(&cb);
let out = dense.render(&DenseOptions::default());
assert!(out.text.contains("pub fn insert(&mut self, id: u64) L4-6 @Db.insert\n"));
assert!(out.text.ends_with("# calls\nplace\n Db.insert(7)\n"));
assert_eq!(dense.resolve("Db.insert"), Some(&insert));
assert!(out.index.contains("Db.insert sym:cargo shop . Db#insert(). src/lib.rs:L4-6\n"));
// A slice around `insert`, refused when it does not fit.
let slice = dense.slice([&insert], &SliceOptions::new(1)).unwrap();
assert!(slice.contains("# callers\nDb.insert\n place\n"));
let err = dense.slice([&insert], &SliceOptions::new(1).max_bytes(64)).unwrap_err();
assert!(matches!(err, SliceError::OverBudget { budget: 64, .. }));Structs§
- Dense
- A codebase prepared for dense projection: short names and the call graph are computed once, then any number of renders and slices share them.
- Dense
Options - Options for the full projection.
- Dense
Output - The two texts of a full projection.
- Slice
Options - Options for
Dense::slice.
Enums§
- Slice
Error - Why
Dense::slicerefused.
Constants§
- FORMAT_
VERSION - Version of the dense text format, written in its first line.
- INDEX_
FILE - File name for
DenseOutput::indexin a generated directory. - TEXT_
FILE - File name for
DenseOutput::textin a generated directory.
Functions§
- render
- The full projection of
codebasein one call; seeDense::render. - slice
- One slice of
codebasein one call; seeDense::slice. Build aDenseonce instead when taking several slices of the same codebase.