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;