sdivi_core/
lib.rs

1#![deny(missing_docs)]
2//! # sdivi-core
3//!
4//! Pure-compute facade for the Structural Divergence Indexer (sdivi-rust).
5//!
6//! This crate is the stable, WASM-compatible public surface for embedding the
7//! analysis pipeline in Rust programs, WASM bindings, and language bindings.
8//! It has **no I/O, no clock, no tree-sitter, and no `std::fs`** — callers
9//! supply pre-extracted data via the `*Input` struct family and receive
10//! plain `serde` result types.
11//!
12//! Embedders that need the full FS-orchestrated pipeline (parsing, snapshot
13//! writes, retention) should use `sdivi-pipeline` instead.
14//!
15//! # Quick start
16//!
17//! ```rust
18//! use sdivi_core::ExitCode;
19//!
20//! assert_eq!(ExitCode::Success as i32, 0);
21//! ```
22//!
23//! ## Pure-compute example
24//!
25//! ```rust
26//! use sdivi_core::compute::coupling::compute_coupling_topology;
27//! use sdivi_core::input::DependencyGraphInput;
28//!
29//! let g = DependencyGraphInput { nodes: vec![], edges: vec![] };
30//! let result = compute_coupling_topology(&g).unwrap();
31//! assert_eq!(result.node_count, 0);
32//! ```
33
34/// Pattern category contract — canonical category list and runtime discovery via [`list_categories`].
35pub mod categories;
36
37/// Errors produced by the sdivi-core pure-compute API.
38pub mod error;
39
40/// Exit codes for the `sdivi` binary — public API, adding variants is a breaking change.
41pub mod exit_code;
42
43/// Input structs for the pure-compute API (WASM-safe serde types).
44pub mod input;
45
46/// Pure-compute functions over [`input`] structs.
47pub mod compute;
48
49/// Re-exports of snapshot assembly, delta, trend, and boundary inference from `sdivi-snapshot`.
50pub mod facade;
51
52pub use categories::{list_categories, CategoryCatalog, CategoryInfo, CATEGORIES};
53pub use error::AnalysisError;
54pub use exit_code::ExitCode;
55
56// ── input type re-exports ──────────────────────────────────────────────────
57
58pub use input::{
59    edge_weight_key, split_edge_weight_key, validate_node_id, BoundaryDefInput, BoundarySpecInput,
60    ChangeCouplingConfigInput, CoChangeEventInput, DependencyGraphInput, EdgeInput,
61    LeidenConfigInput, NodeInput, NormalizeNode, PatternInstanceInput, PatternLocationInput,
62    PriorPartition, QualityFunctionInput, ThresholdOverrideInput, ThresholdsInput,
63};
64
65// ── compute function re-exports ────────────────────────────────────────────
66
67pub use compute::boundaries::{
68    compute_boundary_violations, detect_boundaries, BoundaryDetectionResult,
69    BoundaryViolationResult,
70};
71pub use compute::change_coupling::compute_change_coupling;
72pub use compute::coupling::{compute_coupling_topology, CouplingTopologyResult};
73pub use compute::normalize::normalize_and_hash;
74pub use compute::patterns::{compute_pattern_metrics, compute_pattern_metrics_from_catalog};
75pub use compute::thresholds::{
76    compute_thresholds_check, AppliedOverrideInfo, ThresholdBreachInfo, ThresholdCheckResult,
77    THRESHOLD_EPSILON,
78};
79
80// ── facade re-exports (sdivi-snapshot) ──────────────────────────────────────
81
82pub use facade::{assemble_snapshot, compute_delta, compute_trend, infer_boundaries, null_summary};
83
84// ── snapshot types re-exported directly ───────────────────────────────────
85
86pub use sdivi_snapshot::boundary_inference::{
87    BoundaryInferenceResult, BoundaryProposal, PriorPartition as SnapshotPriorPartition,
88};
89pub use sdivi_snapshot::change_coupling::{ChangeCouplingResult, CoChangePair};
90pub use sdivi_snapshot::delta::DivergenceSummary;
91pub use sdivi_snapshot::snapshot::{
92    IntentDivergenceInfo, PatternMetricsResult, Snapshot, SNAPSHOT_VERSION,
93};
94pub use sdivi_snapshot::trend::TrendResult;
95
96// ── fingerprint key re-export ──────────────────────────────────────────────
97
98/// The fixed `blake3` key used for all pattern fingerprints.
99///
100/// Foreign extractors that produce pattern fingerprints must use this same key
101/// to ensure their fingerprints are byte-identical to those produced by the
102/// native Rust pipeline.
103///
104/// See [`normalize_and_hash`] for the canonical tree-aware algorithm.
105pub use sdivi_patterns::FINGERPRINT_KEY;
106
107// ── inner-crate type re-exports (for sdivi-wasm and other embedders) ─────────
108
109/// Graph metrics summary — re-exported from `sdivi-graph` for WASM embedders.
110pub use sdivi_graph::metrics::GraphMetrics;
111
112/// Leiden community detection result — re-exported from `sdivi-detection` for WASM embedders.
113pub use sdivi_detection::partition::LeidenPartition;
114
115/// Pattern fingerprint catalog — re-exported from `sdivi-patterns` for WASM embedders.
116pub use sdivi_patterns::catalog::{PatternCatalog, PatternStats};
117
118/// Pattern fingerprint type — re-exported from `sdivi-patterns` for WASM embedders.
119pub use sdivi_patterns::fingerprint::PatternFingerprint;
120
121/// Input struct for [`classify_hint`] — re-exported from `sdivi-patterns` for WASM embedders.
122///
123/// Contains only the two fields that `classify_hint` inspects: `node_kind` and `text`.
124/// Foreign extractors construct this directly; the native pipeline uses
125/// `sdivi_parsing::feature_record::PatternHint` and M33 will wire the conversion.
126pub use sdivi_patterns::hint_input::PatternHintInput;
127
128/// Callee-text-aware classification — re-exported from `sdivi-patterns::queries`.
129///
130/// Returns a `Vec` of category names (0 or 1 in v0) for a [`PatternHintInput`].
131/// Provides higher precision than [`category_for_node_kind`] by inspecting
132/// `hint.text` against per-language regex tables.
133///
134/// **The native pipeline (`Pipeline::snapshot`) still uses `category_for_node_kind`
135/// in M32** — M33 switches the pipeline. Foreign extractors can adopt `classify_hint`
136/// immediately.
137///
138/// [`category_for_node_kind`]: sdivi_patterns::queries::category_for_node_kind
139pub use sdivi_patterns::queries::classify_hint;
140
141/// Commonly-imported items from sdivi-core.
142pub mod prelude {
143    pub use crate::input::{DependencyGraphInput, PatternInstanceInput, ThresholdsInput};
144    pub use crate::AnalysisError;
145    pub use crate::DivergenceSummary;
146    pub use crate::ExitCode;
147    pub use crate::Snapshot;
148}
sdivi_core/lib.rs

sdivi_core/
lib.rs
