Skip to main content

Crate sealmap_rust

Crate sealmap_rust 

Source
Expand description

§sealmap-rust

A pure-Rust frontend 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, …). 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()).

§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 unique, distinctive method name on an unknown receiver, or a method reached through deref);
  • 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::new("shop::Orders::place")).unwrap();
let calls: Vec<_> = place.flow.as_ref().unwrap().calls().map(|c| c.target.as_str()).collect();
assert_eq!(calls, ["shop::db::Db::exists", "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 frontend’s extraction.
RustOptions
Frontend 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.