Expand description
§sealmap-rust
A pure-Rust language adapter that turns Rust source into a
sealmap_model::Codebase: modules, types, traits, functions and
methods, the relations between them, and an ordered call Flow for every
function body (the input for sequence diagrams).
It parses with syn and never runs rustc, cargo or anything else, so
it works on any checkout, including code that does not compile, and needs
no toolchain at runtime.
§How it works
- Layout.
Cargo.tomlfiles in theSourceSetdefine packages; each.rsfile is mapped to a crate and module path by Cargo’s conventions (src/lib.rs,src/a/mod.rs,src/bin/x.rs, …). Each manifest’s dependency tables say which workspace crates a crate can reach. Without any manifest, the whole set is one crate named afterRustOptions::name. - Collect (per file, parallel). Each file is parsed and reduced to
plain data: items,
usetables, impl blocks and unresolved call flows. - Resolve (whole workspace, sequential). Paths are resolved through
local items,
useimports (including renames, globs andpub usere-exports),crate/self/super/Self, and sibling workspace crates. Method calls are resolved from the receiver’s declared or constructed type (self,self.field, typed params,let x = Foo::new(), a struct literal), andSelf::f(..)from the enclosing impl’s self type. Calls inmatchguards are part of their arm.
§Ids
Every definition gets a sym: id in the cargo package named after its
crate (see sealmap_extract::ids for the full table):
sym:cargo shop . db/Db#insert().. Binary, test, example and bench
targets are packages of their own (shop_main, test_it, …), so a
binary and the library never share an id. A crate name that more than
one directory holds (two packages called core, or a tests/it.rs in
two packages) is qualified with the package directory, ./ at the root:
sym:cargo a/core . run().. A path such as core::run then names the
one such crate the caller’s manifest depends on (a path dependency,
directly or through [workspace.dependencies], picks it); when that is
still ambiguous the call is left external.
§Fingerprints
Every symbol carries sig_hash (its contract) and body_hash (its
implementation), computed with sealmap_extract::fingerprint from syn’s
token streams. Comments, doc comments, whitespace, lint attributes and the
rewrites rustfmt makes (trailing commas, braces around a closure or match
arm body, use order) never change them; neither does moving an item
within or between files. Reflowing tokio, VisionClaw and sealmap itself
with an aggressive rustfmt configuration changes no id and no
fingerprint.
§What “resolved” means here
There is no type checker. Every call and relation carries a
Confidence:
exact: resolved through explicit paths, imports or declared types to a symbol defined in the analysed code;inferred: matched by a weaker rule (a distinctive method name on an unknown receiver, when exactly one method of that name lives in a crate the caller can reach; or a method reached through deref). Two reachable candidates are an ambiguity, and no edge is guessed;external: outside the analysed code.
Calls into std/core/alloc, prelude constructors (Some, Ok,
Vec::new via std) and method calls on receivers of unknown type are
dropped by default (ExternalCalls::NonStd), which keeps sequence
diagrams dense: they show your code talking to itself and to its
dependencies.
§Determinism
Output depends only on the source set and options. Files are processed in
path order, items in source order, and parallel parsing (feature
parallel, on by default) collects results in input order, so the model
is identical with or without it.
§Example
use sealmap_model::{SourceSet, Step, SymbolId};
use sealmap_rust::{RustOptions, extract};
let mut src = SourceSet::new();
src.insert("Cargo.toml", "[package]\nname = \"shop\"").unwrap();
src.insert("src/lib.rs", r#"
pub mod db;
use db::Db;
/// Order service.
pub struct Orders { db: Db }
impl Orders {
pub fn place(&self, id: u64) -> Result<(), String> {
if self.db.exists(id) {
return Err("dup".into());
}
self.db.insert(id)?;
Ok(())
}
}
"#).unwrap();
src.insert("src/db.rs", r#"
pub struct Db;
impl Db {
pub fn exists(&self, id: u64) -> bool { false }
pub fn insert(&self, id: u64) -> Result<(), String> { Ok(()) }
}
"#).unwrap();
let out = extract(&src, &RustOptions::default());
let place = out.codebase.symbol(&SymbolId::parse("sym:cargo shop . Orders#place().").unwrap()).unwrap();
let calls: Vec<_> = place.flow.as_ref().unwrap().calls().map(|c| c.target.to_string()).collect();
assert_eq!(calls, ["sym:cargo shop . db/Db#exists().", "sym:cargo shop . db/Db#insert()."]);
assert!(out.diagnostics.is_empty());Structs§
- Diagnostic
- A non-fatal problem found while extracting (currently: files that failed to parse; they still get a module symbol so every file is represented).
- Extraction
- Result of a language adapter’s extraction.
- Rust
Options - Language adapter options.
Enums§
- External
Calls - Which calls to external code are kept in flows.
Functions§
- extract
- Extract a
Codebasefrom the.rs(andCargo.toml) files insources. Never fails: unparsable files are reported inExtraction::diagnostics. - extract_
dir - Load
rootfrom disk (.rsandCargo.tomlfiles, skippingtarget/, hidden directories and the like) andextractit. - load_
dir - Load the
.rsandCargo.tomlfiles underroot(honouring.gitignore, skippingtarget/, hidden directories and the like) without extracting them.