entviz 0.15.1

Visualize high-entropy values as comparable SVG diagrams (entviz, spec v15).
Documentation

entviz-rs

CI Release crates.io docs.rs License

Rust implementation of entviz (spec v15) — visualize high-entropy values as comparable SVG diagrams.

Part of the entviz family

entviz is defined by a language-independent specification, with conformant implementations in Python (reference), Rust, TypeScript/JS + React, Java, and Go — all passing the same shared conformance corpus. See the directory of implementations, browse the spec & docs site, or try it live in the browser.

Status: certified against the v15 conformance corpus ✅

A full, self-contained implementation that passes the shared conformance corpus at Tier A (render model) + Tier B (canonical raster) for every render vector, rejects every error vector, and satisfies every invariant pair (52/52). What's here:

  • src/lib.rs — the deterministic shared core: alphabets, tokenization + 24-bit quant extension, the SHA-512 fingerprint (via sha2), ftok median/quartile selection, the Oklab color rules + weighted-RGB edge selection, and grid selection.
  • src/entropy.rs — the format-specific parsers (hex, UUID, Ethereum w/ EIP-55, ULID, base58 / bech32 / base32 chains, CESR, LEI, snowflake, SWHID / gitoid semantic-prefix fold, IPFS CID, SSH, …) + the disproof-based alphabet detection and large-input (head / fingerprint-middle / tail) tokenization.
  • src/keccak.rs — vendored Keccak-256 for EIP-55 checksum validation.
  • src/pipeline.rs — the SVG renderer: geometry, 24-box surround, fingerprint-edge cells, ellipse overlay, color bar + markers, blank-cell map, quartile marks, labels, borders — emitting the normative data-* profile.
  • src/main.rs — the entviz-conformance CLI (the stdin→stdout contract in the entviz repo's compliance/README.md).

Build + certify

cargo test                                  # unit + corpus render/reject contract
cargo build --release --bin entviz-conformance

# from a checkout of the entviz reference repo (sibling ../entviz):
PYTHONPATH=src:. python -m compliance.runner \
  --impl-cmd '/path/to/entviz-rs/target/release/entviz-conformance'
# -> 52/52 vectors passed

cargo test also runs a corpus-driven smoke test (tests/conformance.rs) that drives every vector through the renderer when ../entviz is checked out; the full Tier-A/Tier-B golden comparison is the Python runner above.

Dependencies are intentionally minimal (sha2, base64, hex, serde_json).

Using it

use entviz::render;
use entviz::characterize::characterize;

let svg = render("550e8400-e29b-41d4-a716-446655440000", 1.0, 12.0, None)?;

let ch = characterize("550e8400-e29b-41d4-a716-446655440000")?;
assert_eq!(ch.scheme.as_deref(), Some("uuid"));
assert_eq!(ch.role, Some("identifier"));
assert_eq!(ch.size_bits, 128);

characterize returns the structured entropy characterization (the same eight fields are also emitted as data-* attributes on the rendered SVG). For embedding entviz across all five languages, see the Developer Integration Guide.

Spec compliance & versioning

The crate version encodes the entviz spec level it is compliant with:

0.<spec-major>.x — e.g. 0.10.x ⇒ compliant with entviz spec v10 (the same convention the Python reference uses, where spec v10 ↔ 0.10.0).

A spec bump (v10 → v11) is a minor release here (0.10.x → 0.11.0); a patch is a crate-only change within a spec version. The canonical spec level is the SPEC_VERSION constant in src/lib.rs.

CI surfaces spec drift: the conformance job checks out the public entviz reference, compares its SPEC_VERSION to this crate's, and runs the Tier-A conformance suite. When the reference spec is ahead of this crate it warns loudly (without blocking unrelated PRs); when the versions match (or this crate is ahead) conformance is a hard gate. scripts/release.py performs the same drift check before tagging.

Releasing

Releases are human-run (agents must not push tags). From a clean, in-sync main:

python scripts/release.py                  # patch bump
python scripts/release.py --minor -m "..." # minor bump (e.g. a spec bump)

It runs the gate (fmt + clippy + test), bumps Cargo.toml + Cargo.lock, commits, pushes, and tags vX.Y.Z. The tag triggers .github/workflows/release.yml, which re-runs the gate, verifies the tag matches Cargo.toml, and cargo publishes to crates.io (needs the CARGO_REGISTRY_TOKEN repo secret).

Branch protection (require PR + CI + 1 review for contributors; maintainers bypass via direct push) is configured by scripts/setup-branch-protection.sh.

License

Apache License 2.0. See also NOTICE.