atom/
lib.rs

1//! # Atom Crate
2//!
3//! The `atom` crate provides the core functionality for working with the Atom Format,
4//! a key component of the Ekala Project. This format enables the reproducible
5//! packaging of select sources from a larger history, making it ideal for
6//! dependency management and software distribution.
7//!
8//! ## Key Concepts
9//!
10//! **Atoms** are self-contained, reproducible packages that capture a specific
11//! version of source code or configuration. They are designed to be:
12//! - **Cheap to transfer** over networks
13//! - **Trivial to verify** directly from source
14//! - **Completely reproducible** across different environments
15//!
16//! **Lockfiles** capture the exact versions and revisions of all dependencies,
17//! ensuring that builds are deterministic and can be reproduced reliably.
18//!
19//! ## Architecture
20//!
21//! The crate is organized into several key modules:
22//! - [`manifest`] - Atom manifest format and dependency specification
23//! - [`lock`] - Lockfile format for capturing resolved dependencies
24//! - [`id`] - Atom identification and hashing
25//! - [`uri`] - Atom URI parsing and resolution
26//! - [`store`] - Storage backends for atoms (Git, etc.)
27//! - [`publish`] - Publishing atoms to stores
28//!
29//! ## Git Storage Example
30//!
31//! The current implementation uses Git as the primary storage backend. Atoms are
32//! stored as Git refs pointing to orphaned histories:
33//!
34//! ```console
35//! ❯ git ls-remote
36//! From https://github.com/ekala-project/eka
37//! ceebaca6d44c4cda555db3fbf687c0604c4818eb        refs/eka/atoms/ひらがな/0.1.0
38//! a87bff5ae43894a158dadf40938c775cb5b62d4b        refs/eka/meta/ひらがな/0.1.0/manifest
39//! 9f17c8c816bd1de6f8aa9c037d1b529212ab2a02        refs/eka/meta/ひらがな/0.1.0/origin
40//! ```
41//!
42//! - The ref under eka/atoms points to the complete atom contents
43//! - The `manifest` ref points to a minimal tree containing only the manifest
44//! - The `origin` ref points to the original source commit for verification
45//!
46//! ## Basic Usage
47//!
48//! ```rust,no_run
49//! use atom::{Atom, AtomTag, Manifest};
50//! use semver::Version;
51//!
52//! // Create a new atom manifest
53//! let manifest = Manifest::new(
54//!     AtomTag::try_from("my-atom").unwrap(),
55//!     Version::new(1, 0, 0),
56//!     Some("A sample atom".to_string()),
57//! );
58//! ```
59//!
60//! ## Features
61//!
62//! - **Type-safe dependency management** with compile-time validation
63//! - **Multiple storage backends** (Git, with extensibility for others)
64//! - **Cross-platform compatibility** with TOML-based serialization
65//! - **Comprehensive error handling** with detailed error types
66//! - **Efficient caching** for remote operations
67#![deny(missing_docs)]
68
69mod core;
70pub mod id;
71pub mod lock;
72pub mod log;
73pub mod manifest;
74
75pub mod publish;
76pub mod store;
77pub mod uri;
78pub use core::Atom;
79use std::sync::LazyLock;
80
81pub use id::{AtomId, AtomTag, Compute, Origin};
82pub use lock::{Lockfile, ResolutionMode};
83pub use manifest::Manifest;
84pub use manifest::deps::ManifestWriter;
85
86const TOML: &str = "toml";
87const LOCK: &str = "lock";
88const ATOM: &str = "atom";
89
90/// The base32 alphabet used for encoding Atom hashes.
91///
92/// This uses the RFC4648 hex alphabet without padding, which provides a good balance
93/// between readability and compactness for Atom identifiers.
94const BASE32: base32::Alphabet = base32::Alphabet::Rfc4648HexLower { padding: false };
95
96/// The filename used for Atom manifest files.
97pub static MANIFEST_NAME: LazyLock<String> = LazyLock::new(|| format!("{}.{}", ATOM, TOML));
98/// The filename used for Atom lock files.
99pub static LOCK_NAME: LazyLock<String> = LazyLock::new(|| format!("{}.{}", ATOM, LOCK));
100
101pub use publish::ATOM_REFS;
atom/lib.rs

atom/
lib.rs
