1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
//! # 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.
//!
//! [`Flow`]: sealmap_model::Flow
//!
//! ## 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`](sealmap_model::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());
//! ```
use Path;
use ;
use ;
pub use ;
/// Language adapter options.
/// Extract a [`Codebase`](sealmap_model::Codebase) from the `.rs` (and `Cargo.toml`) files in
/// `sources`. Never fails: unparsable files are reported in
/// [`Extraction::diagnostics`].
type Job<'a> = ;
/// Pass 1 over every file, isolated per file (big stacks, panic guard; see
/// [`sealmap_extract::isolate`]). A panic while collecting one file degrades
/// that file to a diagnostic instead of aborting the run.
/// Load the `.rs` and `Cargo.toml` files under `root` (honouring
/// `.gitignore`, skipping `target/`, hidden directories and the like) without
/// extracting them.
/// Load `root` from disk (`.rs` and `Cargo.toml` files, skipping `target/`,
/// hidden directories and the like) and [`extract`] it.
///
/// [`RustOptions::name`] defaults to the directory name when left as
/// `"codebase"`.
/// Compiles and runs the README examples as doctests.
;