Skip to main content

sealmap_rust/
lib.rs

1//! # sealmap-rust
2//!
3//! A pure-Rust language adapter that turns Rust source into a
4//! [`sealmap_model::Codebase`]: modules, types, traits, functions and
5//! methods, the relations between them, and an ordered call [`Flow`] for every
6//! function body (the input for sequence diagrams).
7//!
8//! It parses with [`syn`] and never runs `rustc`, `cargo` or anything else, so
9//! it works on any checkout, including code that does not compile, and needs
10//! no toolchain at runtime.
11//!
12//! [`Flow`]: sealmap_model::Flow
13//!
14//! ## How it works
15//!
16//! 1. **Layout.** `Cargo.toml` files in the [`SourceSet`] define packages;
17//!    each `.rs` file is mapped to a crate and module path by Cargo's
18//!    conventions (`src/lib.rs`, `src/a/mod.rs`, `src/bin/x.rs`, ...). Each
19//!    manifest's dependency tables say which workspace crates a crate can
20//!    reach. Without any manifest, the whole set is one crate named after
21//!    [`RustOptions::name`].
22//! 2. **Collect (per file, parallel).** Each file is parsed and reduced to
23//!    plain data: items, `use` tables, impl blocks and unresolved call flows.
24//! 3. **Resolve (whole workspace, sequential).** Paths are resolved through
25//!    local items, `use` imports (including renames, globs and `pub use`
26//!    re-exports), `crate`/`self`/`super`/`Self`, and sibling workspace crates.
27//!    Method calls are resolved from the receiver's declared or constructed
28//!    type (`self`, `self.field`, typed params, `let x = Foo::new()`, a
29//!    struct literal), and `Self::f(..)` from the enclosing impl's self type.
30//!    Calls in `match` guards are part of their arm.
31//!
32//! ## Ids
33//!
34//! Every definition gets a `sym:` id in the `cargo` package named after its
35//! crate (see `sealmap_extract::ids` for the full table):
36//! `sym:cargo shop . db/Db#insert().`. Binary, test, example and bench
37//! targets are packages of their own (`shop_main`, `test_it`, ...), so a
38//! binary and the library never share an id. A crate name that more than
39//! one directory holds (two packages called `core`, or a `tests/it.rs` in
40//! two packages) is qualified with the package directory, `./` at the root:
41//! `sym:cargo a/core . run().`. A path such as `core::run` then names the
42//! one such crate the caller's manifest depends on (a `path` dependency,
43//! directly or through `[workspace.dependencies]`, picks it); when that is
44//! still ambiguous the call is left external.
45//!
46//! ## Fingerprints
47//!
48//! Every symbol carries `sig_hash` (its contract) and `body_hash` (its
49//! implementation), computed with `sealmap_extract::fingerprint` from syn's
50//! token streams. Comments, doc comments, whitespace, lint attributes and the
51//! rewrites rustfmt makes (trailing commas, braces around a closure or match
52//! arm body, `use` order) never change them; neither does moving an item
53//! within or between files. Reflowing tokio, VisionClaw and sealmap itself
54//! with an aggressive rustfmt configuration changes no id and no
55//! fingerprint.
56//!
57//! ## What "resolved" means here
58//!
59//! There is no type checker. Every call and relation carries a
60//! [`Confidence`](sealmap_model::Confidence):
61//!
62//! * `exact`: resolved through explicit paths, imports or declared types to a
63//!   symbol defined in the analysed code;
64//! * `inferred`: matched by a weaker rule (a distinctive method name on an
65//!   unknown receiver, when exactly one method of that name lives in a crate
66//!   the caller can reach; or a method reached through deref). Two reachable
67//!   candidates are an ambiguity, and no edge is guessed;
68//! * `external`: outside the analysed code.
69//!
70//! Calls into `std`/`core`/`alloc`, prelude constructors (`Some`, `Ok`,
71//! `Vec::new` via `std`) and method calls on receivers of unknown type are
72//! dropped by default ([`ExternalCalls::NonStd`]), which keeps sequence
73//! diagrams dense: they show *your* code talking to itself and to its
74//! dependencies.
75//!
76//! ## Determinism
77//!
78//! Output depends only on the source set and options. Files are processed in
79//! path order, items in source order, and parallel parsing (feature
80//! `parallel`, on by default) collects results in input order, so the model
81//! is identical with or without it.
82//!
83//! ## Example
84//!
85//! ```
86//! use sealmap_model::{SourceSet, Step, SymbolId};
87//! use sealmap_rust::{RustOptions, extract};
88//!
89//! let mut src = SourceSet::new();
90//! src.insert("Cargo.toml", "[package]\nname = \"shop\"").unwrap();
91//! src.insert("src/lib.rs", r#"
92//!     pub mod db;
93//!     use db::Db;
94//!
95//!     /// Order service.
96//!     pub struct Orders { db: Db }
97//!
98//!     impl Orders {
99//!         pub fn place(&self, id: u64) -> Result<(), String> {
100//!             if self.db.exists(id) {
101//!                 return Err("dup".into());
102//!             }
103//!             self.db.insert(id)?;
104//!             Ok(())
105//!         }
106//!     }
107//! "#).unwrap();
108//! src.insert("src/db.rs", r#"
109//!     pub struct Db;
110//!     impl Db {
111//!         pub fn exists(&self, id: u64) -> bool { false }
112//!         pub fn insert(&self, id: u64) -> Result<(), String> { Ok(()) }
113//!     }
114//! "#).unwrap();
115//!
116//! let out = extract(&src, &RustOptions::default());
117//! let place = out.codebase.symbol(&SymbolId::parse("sym:cargo shop . Orders#place().").unwrap()).unwrap();
118//! let calls: Vec<_> = place.flow.as_ref().unwrap().calls().map(|c| c.target.to_string()).collect();
119//! assert_eq!(calls, ["sym:cargo shop . db/Db#exists().", "sym:cargo shop . db/Db#insert()."]);
120//! assert!(out.diagnostics.is_empty());
121//! ```
122
123#![forbid(unsafe_code)]
124#![deny(missing_docs)]
125
126mod collect;
127mod fingerprint;
128mod layout;
129mod raw;
130mod resolve;
131mod tidy;
132
133use std::path::Path;
134
135use sealmap_extract::isolate::{COLLECT_STACK_BYTES, map_isolated};
136use sealmap_model::{LoadOptions, SourcePath, SourceSet};
137
138pub use sealmap_extract::{Diagnostic, ExternalCalls, Extraction};
139
140/// Language adapter options.
141#[derive(Debug, Clone)]
142pub struct RustOptions {
143    /// Codebase name, also used as the crate name when no `Cargo.toml` is
144    /// present.
145    pub name: String,
146    /// Include `#[cfg(test)]` modules, `#[test]` functions and files under
147    /// `tests/`, `examples/` and `benches/`. Off by default.
148    pub include_tests: bool,
149    /// External call policy.
150    pub external_calls: ExternalCalls,
151}
152
153impl Default for RustOptions {
154    fn default() -> Self {
155        Self { name: "codebase".into(), include_tests: false, external_calls: ExternalCalls::NonStd }
156    }
157}
158
159/// Extract a [`Codebase`](sealmap_model::Codebase) from the `.rs` (and `Cargo.toml`) files in
160/// `sources`. Never fails: unparsable files are reported in
161/// [`Extraction::diagnostics`].
162pub fn extract(sources: &SourceSet, options: &RustOptions) -> Extraction {
163    let plan = layout::plan(sources, &options.name);
164    let jobs: Vec<_> = plan
165        .roles
166        .iter()
167        .filter(|(_, role)| options.include_tests || role.target <= layout::TargetKind::Bin)
168        .filter_map(|(path, role)| sources.get(path).map(|text| (path.clone(), role.clone(), text)))
169        .collect();
170
171    let files = collect_all(&jobs, options);
172
173    let (codebase, diagnostics) = resolve::build(&options.name, files, &plan, options);
174    Extraction { codebase, diagnostics }
175}
176
177type Job<'a> = (SourcePath, layout::FileRole, &'a str);
178
179/// Pass 1 over every file, isolated per file (big stacks, panic guard; see
180/// [`sealmap_extract::isolate`]). A panic while collecting one file degrades
181/// that file to a diagnostic instead of aborting the run.
182fn collect_all(jobs: &[Job<'_>], options: &RustOptions) -> Vec<raw::RawFile> {
183    map_isolated(
184        jobs,
185        COLLECT_STACK_BYTES,
186        |(p, r, t)| collect::collect_file(p, r, t, options),
187        |(p, r, t), why| collect::failed_file(p, r, t, format!("1:1: internal error while collecting: {why}")),
188    )
189}
190
191/// Load the `.rs` and `Cargo.toml` files under `root` (honouring
192/// `.gitignore`, skipping `target/`, hidden directories and the like) without
193/// extracting them.
194pub fn load_dir(root: &Path) -> std::io::Result<SourceSet> {
195    let load = LoadOptions { extensions: vec!["rs".into(), "toml".into()], ..LoadOptions::default() };
196    let mut sources = SourceSet::load_dir(root, &load)?;
197    sources.retain(|p| p.extension() == Some("rs") || p.file_name() == "Cargo.toml");
198    Ok(sources)
199}
200
201/// Load `root` from disk (`.rs` and `Cargo.toml` files, skipping `target/`,
202/// hidden directories and the like) and [`extract`] it.
203///
204/// [`RustOptions::name`] defaults to the directory name when left as
205/// `"codebase"`.
206pub fn extract_dir(root: &Path, options: &RustOptions) -> std::io::Result<(SourceSet, Extraction)> {
207    let sources = load_dir(root)?;
208    let mut options = options.clone();
209    if options.name == "codebase" {
210        if let Some(n) = root.canonicalize().ok().and_then(|p| p.file_name().map(|s| s.to_string_lossy().into_owned()))
211        {
212            options.name = n;
213        }
214    }
215    let extraction = extract(&sources, &options);
216    Ok((sources, extraction))
217}
218
219/// Compiles and runs the README examples as doctests.
220#[cfg(doctest)]
221#[doc = include_str!("../README.md")]
222struct ReadmeDoctests;