sdivi-rust

Structural Divergence Indexer. Pronounced Stevie. A measurement instrument that tracks how fast the structure of a codebase is changing.

SDIVI captures the structural fingerprint of a repository (dependency graph, community partition, pattern catalog) into deterministic JSON snapshots, then reports four divergence metrics between consecutive snapshots:

Threshold breaches are observations. SDIVI never opines on code quality. It produces numbers, and a CI gate (sdivi check) decides what to do with them.

sdivi-rust is the Rust reimplementation of the Python POC (structural-divergence-indexer). Snapshots are not backward compatible with the Python POC. See Migrating from the Python POC.

Where to start

If you want to… Read this
Install SDIVI and run your first snapshot README on GitHub
Wire sdivi check into a CI gate CLI integration guide
Embed SDIVI from Rust (full pipeline) Library embedding guide
Embed SDIVI from your own AST extractor (consumer-app-style) Library embedding guide
Call SDIVI from TypeScript / WASM Library embedding guide
Read or generate snapshot JSON Snapshot schema reference
Understand reproducibility guarantees Determinism notes
Migrate from the Python POC Migrating from the Python POC

Architecture in one diagram

sdivi-rust ships as a Cargo workspace with a two-layer library shape.

                ── orchestration path (sdivi-pipeline) ──

config + boundaries + repo
       │
       ▼
[ Pipeline::new(&Config) ]
       │
       ▼
parsing → graph → detection → patterns → snapshot/delta
       │
       ▼
sdivi-cli formats text/JSON ──► stdout    (logs/progress ──► stderr)


                ── pure-compute path (sdivi-core / WASM) ──

caller-supplied: graph, patterns, leiden config, thresholds, prior partitions
       │
       ▼
sdivi_core::{ detect_boundaries, compute_coupling_topology,
              compute_pattern_metrics, compute_thresholds_check,
              compute_delta, normalize_and_hash, ... }
       │
       ▼
caller assembles its own report

sdivi-core is WASM-compatible. No I/O, no clock, no tree-sitter. Every function that conceptually needs the wall clock takes a chrono::NaiveDate as input.

Public surface

Crate Use it for Stability
sdivi-core Pure-compute API; WASM target; foreign extractors Stable, #![deny(missing_docs)]
sdivi-pipeline Full FS pipeline from Rust Stable
sdivi-cli The sdivi binary Stable CLI surface
sdivi-config Config loader and types Stable
sdivi-lang-{rust,python,typescript,javascript,go,java} Language adapters Stable
sdivi-graph, sdivi-detection, sdivi-patterns, sdivi-snapshot, sdivi-parsing Inner crates. Use only if you need a single stage. Stable

Adding a pub item is deliberate. Removing or renaming one is a breaking change. SemVer commitment begins at 0.1.0.

API reference (rustdoc) is published to docs.rs on every cargo publish:

Source

Released under Apache 2.0.