sealmap_extract/lib.rs
1//! # sealmap-extract
2//!
3//! The language-neutral half of a sealmap language adapter. A language adapter (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//! language adapters 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//! | [`fingerprint`] | per-symbol `sig_hash` / `body_hash` over a language-neutral token stream |
15//! | [`ids`] | the `sym:` id builder (package, module, item, method and trait-impl ids) |
16//! | [`isolate`] | per-file collection on big stacks with a panic guard |
17//!
18//! It has no parser dependency; a language adapter brings its own.
19//!
20//! ## Example
21//!
22//! A language adapter has walked `fn run() { if ready() { go() } }` and resolves
23//! every path call to an internal function:
24//!
25//! ```
26//! use sealmap_extract::raw::{Callee, RawCall, RawStep};
27//! use sealmap_extract::{ids, lower};
28//! use sealmap_model::{CallKind, Confidence, Step, SymbolKind};
29//!
30//! let call = |name: &str, line| {
31//! RawStep::Call(RawCall::new(Callee::Path(vec![name.into()]), format!("{name}()"), CallKind::Function, line))
32//! };
33//! let raw = vec![call("ready", 1), RawStep::Branch(vec![("ready()".into(), vec![call("go", 1)])])];
34//!
35//! let app = ids::module_id(&ids::package("cargo", "app"), &[]);
36//! let flow = lower::lower_flow(&raw, &mut |c: &RawCall| {
37//! let Callee::Path(segs) = &c.callee else { return None };
38//! Some(c.to_call(ids::item_id(&app, SymbolKind::Function, &segs[0]), Confidence::Exact))
39//! })
40//! .unwrap();
41//!
42//! let targets: Vec<_> = flow.calls().map(|c| c.target.to_string()).collect();
43//! assert_eq!(targets, ["sym:cargo app . ready().", "sym:cargo app . go()."]);
44//! // A branch with one surviving arm is an optional fragment.
45//! assert!(matches!(&flow.steps[1], Step::Optional { label, .. } if label == "ready()"));
46//! ```
47
48#![forbid(unsafe_code)]
49#![deny(missing_docs)]
50
51pub mod confidence;
52pub mod fingerprint;
53pub mod ids;
54pub mod isolate;
55pub mod labels;
56pub mod lower;
57pub mod raw;
58
59use sealmap_model::{Codebase, SourcePath};
60
61pub use confidence::{ExternalCalls, aggregate_calls};
62pub use raw::{Callee, RawCall, RawStep, Recv, Segs};
63
64/// A non-fatal problem found while extracting (currently: files that failed
65/// to parse; they still get a module symbol so every file is represented).
66#[derive(Debug, Clone, PartialEq, Eq)]
67pub struct Diagnostic {
68 /// File the problem is in.
69 pub file: SourcePath,
70 /// Human-readable message with `line:col` prefix.
71 pub message: String,
72}
73
74/// Result of a language adapter's extraction.
75#[derive(Debug, Clone)]
76pub struct Extraction {
77 /// The model.
78 pub codebase: Codebase,
79 /// Non-fatal problems, in file order.
80 pub diagnostics: Vec<Diagnostic>,
81}
82
83/// Compiles and runs the README examples as doctests.
84#[cfg(doctest)]
85#[doc = include_str!("../README.md")]
86struct ReadmeDoctests;