sealmap-extract 0.2.0

Language-neutral extraction core for sealmap language adapters: raw flow IR, flow lowering, call aggregation, confidence policy, label rules, sym: id builder, token-stream fingerprints and panic-isolated collection
Documentation
//! # sealmap-extract
//!
//! The language-neutral half of a sealmap language adapter. A language adapter (the syn-based
//! `sealmap-rust`, or a future TypeScript one) parses source and walks
//! function bodies; everything after that is shared and lives here, so two
//! language adapters produce flows, labels, ids and confidences by the same rules:
//!
//! | Module | Owns |
//! |---|---|
//! | [`raw`] | the raw flow IR a parser emits before resolution ([`RawStep`], [`RawCall`], [`Callee`], [`Recv`]) and the helpers that shape it while walking |
//! | [`lower`] | flow normalisation: raw steps plus a call resolver → a model [`Flow`](sealmap_model::Flow) |
//! | [`confidence`] | the confidence lattice, the external-call policy ([`ExternalCalls`]) and call-edge aggregation |
//! | [`labels`] | label rules: compact token spacing, clipping limits, call, condition and deferred-closure labels |
//! | [`fingerprint`] | per-symbol `sig_hash` / `body_hash` over a language-neutral token stream |
//! | [`ids`] | the `sym:` id builder (package, module, item, method and trait-impl ids) |
//! | [`isolate`] | per-file collection on big stacks with a panic guard |
//!
//! It has no parser dependency; a language adapter brings its own.
//!
//! ## Example
//!
//! A language adapter has walked `fn run() { if ready() { go() } }` and resolves
//! every path call to an internal function:
//!
//! ```
//! use sealmap_extract::raw::{Callee, RawCall, RawStep};
//! use sealmap_extract::{ids, lower};
//! use sealmap_model::{CallKind, Confidence, Step, SymbolKind};
//!
//! let call = |name: &str, line| {
//!     RawStep::Call(RawCall::new(Callee::Path(vec![name.into()]), format!("{name}()"), CallKind::Function, line))
//! };
//! let raw = vec![call("ready", 1), RawStep::Branch(vec![("ready()".into(), vec![call("go", 1)])])];
//!
//! let app = ids::module_id(&ids::package("cargo", "app"), &[]);
//! let flow = lower::lower_flow(&raw, &mut |c: &RawCall| {
//!     let Callee::Path(segs) = &c.callee else { return None };
//!     Some(c.to_call(ids::item_id(&app, SymbolKind::Function, &segs[0]), Confidence::Exact))
//! })
//! .unwrap();
//!
//! let targets: Vec<_> = flow.calls().map(|c| c.target.to_string()).collect();
//! assert_eq!(targets, ["sym:cargo app . ready().", "sym:cargo app . go()."]);
//! // A branch with one surviving arm is an optional fragment.
//! assert!(matches!(&flow.steps[1], Step::Optional { label, .. } if label == "ready()"));
//! ```

#![forbid(unsafe_code)]
#![deny(missing_docs)]

pub mod confidence;
pub mod fingerprint;
pub mod ids;
pub mod isolate;
pub mod labels;
pub mod lower;
pub mod raw;

use sealmap_model::{Codebase, SourcePath};

pub use confidence::{ExternalCalls, aggregate_calls};
pub use raw::{Callee, RawCall, RawStep, Recv, Segs};

/// A non-fatal problem found while extracting (currently: files that failed
/// to parse; they still get a module symbol so every file is represented).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Diagnostic {
    /// File the problem is in.
    pub file: SourcePath,
    /// Human-readable message with `line:col` prefix.
    pub message: String,
}

/// Result of a language adapter's extraction.
#[derive(Debug, Clone)]
pub struct Extraction {
    /// The model.
    pub codebase: Codebase,
    /// Non-fatal problems, in file order.
    pub diagnostics: Vec<Diagnostic>,
}

/// Compiles and runs the README examples as doctests.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
struct ReadmeDoctests;