Skip to main content

sealmap_frontend/
lib.rs

1//! # sealmap-frontend
2//!
3//! The language-neutral half of a sealmap frontend. A frontend (the syn-based
4//! `sealmap-rust`, or a future TypeScript one) parses source and walks
5//! function bodies; everything after that is shared and lives here, so two
6//! frontends produce flows, labels, ids and confidences by the same rules:
7//!
8//! | Module | Owns |
9//! |---|---|
10//! | [`raw`] | the raw flow IR a parser emits before resolution ([`RawStep`], [`RawCall`], [`Callee`], [`Recv`]) and the helpers that shape it while walking |
11//! | [`lower`] | flow normalisation: raw steps plus a call resolver → a model [`Flow`](sealmap_model::Flow) |
12//! | [`confidence`] | the confidence lattice, the external-call policy ([`ExternalCalls`]) and call-edge aggregation |
13//! | [`labels`] | label rules: compact token spacing, clipping limits, call, condition and deferred-closure labels |
14//! | [`ids`] | the symbol-id builder (module, item, method and trait-impl ids) |
15//! | [`isolate`] | per-file collection on big stacks with a panic guard |
16//!
17//! It has no parser dependency; a frontend brings its own.
18//!
19//! ## Example
20//!
21//! A frontend has walked `fn run() { if ready() { go() } }` and resolves
22//! every path call to an internal function:
23//!
24//! ```
25//! use sealmap_frontend::raw::{Callee, RawCall, RawStep};
26//! use sealmap_frontend::{ids, lower};
27//! use sealmap_model::{CallKind, Confidence, Step};
28//!
29//! let call = |name: &str, line| {
30//!     RawStep::Call(RawCall::new(Callee::Path(vec![name.into()]), format!("{name}()"), CallKind::Function, line))
31//! };
32//! let raw = vec![call("ready", 1), RawStep::Branch(vec![("ready()".into(), vec![call("go", 1)])])];
33//!
34//! let flow = lower::lower_flow(&raw, &mut |c: &RawCall| {
35//!     let Callee::Path(segs) = &c.callee else { return None };
36//!     Some(c.to_call(ids::item_id("app", &segs[0]), Confidence::Exact))
37//! })
38//! .unwrap();
39//!
40//! let targets: Vec<_> = flow.calls().map(|c| c.target.as_str()).collect();
41//! assert_eq!(targets, ["app::ready", "app::go"]);
42//! // A branch with one surviving arm is an optional fragment.
43//! assert!(matches!(&flow.steps[1], Step::Optional { label, .. } if label == "ready()"));
44//! ```
45
46#![forbid(unsafe_code)]
47#![deny(missing_docs)]
48
49pub mod confidence;
50pub mod ids;
51pub mod isolate;
52pub mod labels;
53pub mod lower;
54pub mod raw;
55
56use sealmap_model::{Codebase, SourcePath};
57
58pub use confidence::{ExternalCalls, aggregate_calls};
59pub use raw::{Callee, RawCall, RawStep, Recv, Segs};
60
61/// A non-fatal problem found while extracting (currently: files that failed
62/// to parse; they still get a module symbol so every file is represented).
63#[derive(Debug, Clone, PartialEq, Eq)]
64pub struct Diagnostic {
65    /// File the problem is in.
66    pub file: SourcePath,
67    /// Human-readable message with `line:col` prefix.
68    pub message: String,
69}
70
71/// Result of a frontend's extraction.
72#[derive(Debug, Clone)]
73pub struct Extraction {
74    /// The model.
75    pub codebase: Codebase,
76    /// Non-fatal problems, in file order.
77    pub diagnostics: Vec<Diagnostic>,
78}
79
80/// Compiles and runs the README examples as doctests.
81#[cfg(doctest)]
82#[doc = include_str!("../README.md")]
83struct ReadmeDoctests;