From 6f88a09b098b259f5d4c095b9675dbc17db76d95 Mon Sep 17 00:00:00 2001
From: Markus Scully <markus@mascully.com>
Date: Tue, 12 Aug 2025 15:27:42 +0300
Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=F0=9F=93=9D=F0=9F=92=A9=20vanth:=20Ad?=
 =?UTF-8?q?d=20`nix`=20module=20and=20improve=20documentation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Added new module `nix` containing `NixosModule` and `NixExpression` structs.
- Added documentation comments for the `hash` function regarding type exclusion in output.
- Added documentation for `Network`, `ContentHash`, `Ty`, and `Vanth` trait.
- Added TODO stubs for `Network` implementation and `impl_vanth` macro.
- Removed the `Component` trait and updated `Node` struct to have empty braces.
- Removed unused `Component` import from integration tests.
---
 crates/vanth/src/hashing_serializer.rs |  5 +++-
 crates/vanth/src/lib.rs                | 36 ++++++++++++++++----------
 crates/vanth/src/nix.rs                |  7 +++++
 crates/vanth/tests/integration/main.rs |  2 +-
 4 files changed, 35 insertions(+), 15 deletions(-)
 create mode 100644 crates/vanth/src/nix.rs

diff --git a/crates/vanth/src/hashing_serializer.rs b/crates/vanth/src/hashing_serializer.rs
index 982190e..0a4d1eb 100644
--- a/crates/vanth/src/hashing_serializer.rs
+++ b/crates/vanth/src/hashing_serializer.rs
@@ -11,8 +11,11 @@ use serde::{
     },
 };
 
-use crate::ContentHash;
+use crate::{ContentHash, Ty};
 
+/// Returns the [`ContentHash`] of any type implementing [`Serialize`].
+///
+/// The type name itself is not included in the hash, and so two values with different types may produce the same hash. /// Use a combination of [`Ty`] and [`ContentHash`] to uniquely identify values.
 pub fn hash(value: &impl Serialize) -> ContentHash {
     let mut digest = blake3::Hasher::new();
     let mut serializer = HashingSerializer { digest: &mut digest };
diff --git a/crates/vanth/src/lib.rs b/crates/vanth/src/lib.rs
index 3324fee..ab37350 100644
--- a/crates/vanth/src/lib.rs
+++ b/crates/vanth/src/lib.rs
@@ -1,5 +1,3 @@
-#![doc = include_str!("../../../README.md")]
-
 use std::marker::PhantomData;
 
 use bevy_ecs::{prelude::*, query::QueryData};
@@ -9,6 +7,7 @@ use crate::entity::EntityId;
 
 pub mod entity;
 pub mod hashing_serializer;
+pub mod nix;
 pub mod store;
 
 pub use hashing_serializer::hash;
@@ -20,14 +19,20 @@ pub enum Error {
     Other(String),
 }
 
+
+/// A view of all of the [`Node`]s in a cluster.
+pub struct Network {
+    // TODO
+}
+
 /// A Vanth server.
 pub struct Node {
-    
+    // TODO
 }
 
 impl Node {
     pub fn new() -> Self {
-        Self {  }
+        Self {}
     }
 
     pub fn entity_count(&self) -> usize {
@@ -70,6 +75,8 @@ pub struct Value {
     data: Vec<u8>,
 }
 
+/// A wrapper for the fully-qualified name of a Rust type. This should be univerisally unique for a given type within a
+/// given project.
 #[derive(Clone, Debug, Deserialize, Serialize, Eq, Hash)]
 pub struct Ty {
     pub path: Vec<String>,
@@ -93,10 +100,19 @@ impl<T: AsRef<str>> PartialEq<T> for Ty {
     }
 }
 
+/// All types stored in the Vanth database should implement this trait.
 pub trait Vanth {
+    /// Get the [`Ty`] representing this type.
     fn ty() -> Ty;
 }
 
+macro_rules! impl_vanth {
+    // TODO
+    () => {};
+}
+
+// impl_vanth!(std::string::String)
+
 // TODO: Impl for different tuple sizes
 pub trait VanthTuple {}
 
@@ -112,12 +128,11 @@ pub struct ComponentContents<T: Vanth> {
     _marker: PhantomData<T>,
 }
 
-pub trait Component: Serialize {
-    fn id() -> String;
-}
-
 // use a macro to implement VanthTuiple here.
 
+/// A 32 byte BLAKE3 hash representing the contents of some value.
+///
+/// This can be generated with the [`hash`] function.
 #[derive(Copy, Clone, Debug, Deserialize, Component, Serialize, PartialEq, Eq, Hash)]
 pub struct ContentHash {
     pub hash: [u8; 32],
@@ -167,10 +182,5 @@ pub struct Handle<T> {
     _marker: PhantomData<T>,
 }
 
-
-// fn run_reference_tasks(tasks: Query<(&ReferenceGetTask<>)>) {
-
-// }
-
 /// A world which Vanth entities live in. Lifetimes `'v` of [`Vanth<'v>`] types are tied to the lifetime of the `Root`.
 pub struct Root {}
diff --git a/crates/vanth/src/nix.rs b/crates/vanth/src/nix.rs
new file mode 100644
index 0000000..a17f9d7
--- /dev/null
+++ b/crates/vanth/src/nix.rs
@@ -0,0 +1,7 @@
+pub struct NixosModule {
+    
+}
+
+pub struct NixExpression {
+    
+}
diff --git a/crates/vanth/tests/integration/main.rs b/crates/vanth/tests/integration/main.rs
index 74fc9a6..9204b6f 100644
--- a/crates/vanth/tests/integration/main.rs
+++ b/crates/vanth/tests/integration/main.rs
@@ -1,5 +1,5 @@
 use serde::{Deserialize, Serialize};
-use vanth::{Component, Node, Reference};
+use vanth::{Node, Reference};
 
 mod derive;
 mod fs;