Skip to main content

Crate sealmap_dense

Crate sealmap_dense 

Source
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 span L<start>-<end>, and the short name after @.
  • Call trees, each call indented one space under its caller, with alt/else, opt, loop, par/and and 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 .await or ? 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); the sym: 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.
DenseOptions
Options for the full projection.
DenseOutput
The two texts of a full projection.
SliceOptions
Options for Dense::slice.

Enums§

SliceError
Why Dense::slice refused.

Constants§

FORMAT_VERSION
Version of the dense text format, written in its first line.
INDEX_FILE
File name for DenseOutput::index in a generated directory.
TEXT_FILE
File name for DenseOutput::text in a generated directory.

Functions§

render
The full projection of codebase in one call; see Dense::render.
slice
One slice of codebase in one call; see Dense::slice. Build a Dense once instead when taking several slices of the same codebase.