Skip to main content

Crate sealmap_rust

Crate sealmap_rust 

Source
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

  1. Layout. Cargo.toml files in the SourceSet define packages; each .rs file 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 after RustOptions::name.
  2. Collect (per file, parallel). Each file is parsed and reduced to plain data: items, use tables, impl blocks and unresolved call flows.
  3. Resolve (whole workspace, sequential). Paths are resolved through local items, use imports (including renames, globs and pub use re-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), and Self::f(..) from the enclosing impl’s self type. Calls in match guards 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.
RustOptions
Language adapter options.

Enums§

ExternalCalls
Which calls to external code are kept in flows.

Functions§

extract
Extract a Codebase from the .rs (and Cargo.toml) files in sources. Never fails: unparsable files are reported in Extraction::diagnostics.
extract_dir
Load root from disk (.rs and Cargo.toml files, skipping target/, hidden directories and the like) and extract it.
load_dir
Load the .rs and Cargo.toml files under root (honouring .gitignore, skipping target/, hidden directories and the like) without extracting them.