refactor: make gxhash optional for docs.rs compatibility

- Make gxhash dependency optional with feature flag (enabled by default)
- Add collections abstraction layer to switch between gxhash and std collections
- Update all imports to use new collections module
- Configure docs.rs to build without gxhash to avoid CPU feature requirements
- Maintain performance benefits in normal builds while enabling docs.rs builds

This change allows the project to build successfully on docs.rs which has
restrictions on CPU-specific features, while preserving the performance
advantages of gxhash for regular builds.

Author: mufeedvh

Cargo.toml

@@ -11,8 +11,9 @@ keywords = ["checkpoint", "snapshot", "backup", "time-travel", "versioning"]
 categories = ["filesystem", "data-structures"]
 
 [features]
-default = []
+default = ["gxhash"]
 quick-bench = []
+gxhash = ["dep:gxhash"]
 
 [dependencies]
 # Serialization
@@ -23,7 +24,7 @@ bincode = { version = "2.0", features = ["serde"] }
 # Hashing and Compression
 sha2 = "0.10"
 lz4_flex = "0.11"
-gxhash = "3.5"  # Fast non-cryptographic hash algorithm
+gxhash = { version = "3.5", optional = true }  # Fast non-cryptographic hash algorithm
 
 # File system operations
 walkdir = "2.5"
@@ -100,3 +101,7 @@ required-features = ["rmcp", "schemars"]
 [[bench]]
 name = "titor_bench"
 harness = false
+
+[package.metadata.docs.rs]
+# Build docs without gxhash to avoid CPU feature requirements
+no-default-features = true

src/checkpoint.rs

@@ -49,7 +49,7 @@ use crate::error::Result;
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 use sha2::{Digest, Sha256};
-use gxhash::HashMap;
+use crate::collections::HashMap;
 
 /// Represents a checkpoint in the timeline
 ///
@@ -314,7 +314,7 @@ impl Checkpoint {
     ///
     /// ```rust
     /// # use titor::checkpoint::{Checkpoint, CheckpointMetadataBuilder};
-    /// # use gxhash::{HashMap, HashMapExt};
+    /// # use crate::collections::{HashMap, HashMapExt};
     /// # let checkpoint = Checkpoint::new(Some("parent".to_string()), None, CheckpointMetadataBuilder::new().build(), "".to_string());
     /// # let checkpoints = HashMap::new();
     /// if checkpoint.is_descendant_of("root-id", &checkpoints) {
@@ -355,7 +355,7 @@ impl Checkpoint {
     ///
     /// ```rust
     /// # use titor::checkpoint::{Checkpoint, CheckpointMetadataBuilder};
-    /// # use gxhash::{HashMap, HashMapExt};
+    /// # use crate::collections::{HashMap, HashMapExt};
     /// # let checkpoint = Checkpoint::new(Some("parent".to_string()), None, CheckpointMetadataBuilder::new().build(), "".to_string());
     /// # let checkpoints = HashMap::new();
     /// let chain = checkpoint.get_parent_chain(&checkpoints);
@@ -596,7 +596,7 @@ impl CheckpointMetadataBuilder {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use gxhash::HashMapExt;
+    use crate::collections::HashMapExt;
 
     #[test]
     fn test_checkpoint_creation() {

src/collections.rs

@@ -0,0 +1,73 @@
+//! Collection type aliases that switch between gxhash and std collections
+//! based on feature flags. This allows building on docs.rs without CPU-specific
+//! requirements while maintaining performance in normal builds.
+
+#[cfg(feature = "gxhash")]
+pub use gxhash::{
+    HashMap as GxHashMap, HashMapExt, HashSet as GxHashSet, HashSetExt, GxBuildHasher,
+};
+
+#[cfg(not(feature = "gxhash"))]
+use std::collections::{HashMap as StdHashMap, HashSet as StdHashSet};
+
+/// Type alias for HashMap that uses gxhash when available, std otherwise
+#[cfg(feature = "gxhash")]
+pub type HashMap<K, V> = GxHashMap<K, V>;
+
+/// Type alias for HashMap that uses gxhash when available, std otherwise
+#[cfg(not(feature = "gxhash"))]
+pub type HashMap<K, V> = StdHashMap<K, V>;
+
+/// Type alias for HashSet that uses gxhash when available, std otherwise
+#[cfg(feature = "gxhash")]
+pub type HashSet<T> = GxHashSet<T>;
+
+/// Type alias for HashSet that uses gxhash when available, std otherwise
+#[cfg(not(feature = "gxhash"))]
+pub type HashSet<T> = StdHashSet<T>;
+
+/// Extension trait for creating HashMap instances
+#[cfg(not(feature = "gxhash"))]
+pub trait HashMapExt {
+    /// Creates a new HashMap with default capacity
+    fn new() -> Self;
+    
+    /// Creates a new HashMap with specified capacity
+    fn with_capacity(capacity: usize) -> Self;
+}
+
+#[cfg(not(feature = "gxhash"))]
+impl<K, V> HashMapExt for StdHashMap<K, V> {
+    fn new() -> Self {
+        StdHashMap::new()
+    }
+    
+    fn with_capacity(capacity: usize) -> Self {
+        StdHashMap::with_capacity(capacity)
+    }
+}
+
+/// Extension trait for creating HashSet instances
+#[cfg(not(feature = "gxhash"))]
+pub trait HashSetExt {
+    /// Creates a new HashSet with default capacity
+    fn new() -> Self;
+    
+    /// Creates a new HashSet with specified capacity
+    fn with_capacity(capacity: usize) -> Self;
+}
+
+#[cfg(not(feature = "gxhash"))]
+impl<T> HashSetExt for StdHashSet<T> {
+    fn new() -> Self {
+        StdHashSet::new()
+    }
+    
+    fn with_capacity(capacity: usize) -> Self {
+        StdHashSet::with_capacity(capacity)
+    }
+}
+
+/// Hasher type that uses GxBuildHasher when available, std otherwise
+#[cfg(not(feature = "gxhash"))]
+pub type GxBuildHasher = std::hash::RandomState; 

src/file_tracking.rs

@@ -148,7 +148,7 @@ use std::sync::Arc;
 use parking_lot::Mutex;
 use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
 use std::time::Instant;
-use gxhash::{HashMap, HashSet, HashSetExt};
+use crate::collections::{HashMap, HashSet, HashSetExt};
 use tracing::{debug, trace, warn};
 
 /// File tracker for detecting changes in a directory

src/lib.rs

@@ -202,6 +202,7 @@ pub mod types;
 pub mod verification;
 
 // Internal modules (not part of public API)
+mod collections;
 mod file_tracking;
 mod merkle;
 pub mod storage;

src/merkle.rs

@@ -122,7 +122,7 @@ use crate::error::{Result, TitorError};
 use crate::types::FileEntry;
 use sha2::{Digest, Sha256};
 use std::path::PathBuf;
-use gxhash::{HashMap, HashMapExt};
+use crate::collections::{HashMap, HashMapExt};
 use tracing::trace;
 
 /// A node in the Merkle tree structure

src/storage.rs

@@ -110,7 +110,7 @@ use crate::types::{FileManifest, StorageMetadata, StorageObject, TitorConfig};
 use chrono::Utc;
 use dashmap::DashMap;
 use parking_lot::{Mutex, RwLock};
-use gxhash::GxBuildHasher;
+use crate::collections::GxBuildHasher;
 use sha2::{Digest, Sha256};
 use std::fs;
 

src/timeline.rs

@@ -47,7 +47,7 @@
 use crate::checkpoint::Checkpoint;
 use crate::error::{Result, TitorError};
 use serde::{Deserialize, Serialize};
-use gxhash::{HashMap, HashMapExt, HashSet, HashSetExt};
+use crate::collections::{HashMap, HashMapExt, HashSet, HashSetExt};
 use std::collections::VecDeque;
 use tracing::{debug, trace};
 

src/types.rs

@@ -29,7 +29,7 @@
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 use std::path::PathBuf;
-use gxhash::HashMap;
+use crate::collections::HashMap;
 use std::sync::Arc;
 
 /// Represents a file entry in a checkpoint manifest

src/verification.rs

@@ -65,7 +65,7 @@ use crate::types::FileEntry;
 use crate::utils;
 
 use serde::{Deserialize, Serialize};
-use gxhash::{HashMap, HashMapExt};
+use crate::collections::{HashMap, HashMapExt};
 use std::collections::HashSet;
 use std::time::Instant;
 use tracing::{debug, error, info, warn};