0.0.2-alpha.4

crates/knowledge-git-api/src/lib.rs

@@ -1,84 +1,24 @@
 // file: crates/knowledge-git-api/src/lib.rs
-// version: 3
+// version: 4
 
 //! Provider-neutral contracts for Git-backed Knowledge sources.
 //!
 //! This crate deliberately contains no forge API, process runner, filesystem checkout or database
 //! implementation. Concrete Git backends depend on this contract, not the reverse.
 
+mod reference;
+mod repository;
+mod revision;
+mod snapshot;
+
 /// Opaque Git reference requested by a caller, such as a branch, tag or object expression.
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-pub struct GitReference(String);
-
-impl crate::GitReference {
-    /// Create an opaque Git reference without imposing one provider's reference grammar.
-    pub fn new(value: &str) -> crate::GitReference {
-        return crate::GitReference(value.to_owned());
-    }
-
-    /// Return the reference text.
-    pub fn as_str(&self) -> &str {
-        return self.0.as_str();
-    }
-}
-
-/// Resolved authoritative Git revision identity.
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-pub struct GitRevision(String);
-
-impl crate::GitRevision {
-    /// Create a revision identity returned by a concrete Git implementation.
-    pub fn new(value: &str) -> crate::GitRevision {
-        return crate::GitRevision(value.to_owned());
-    }
-
-    /// Return the revision identity as text.
-    pub fn as_str(&self) -> &str {
-        return self.0.as_str();
-    }
-}
-
-/// Read-only local materialization of one authoritative Git revision.
-#[derive(Clone, Debug, Eq, PartialEq)]
-pub struct GitSnapshot {
-    path: std::path::PathBuf,
-    revision: crate::GitRevision,
-}
-
-impl crate::GitSnapshot {
-    /// Build a snapshot contract from a resolved revision and its local read root.
-    pub fn new(revision: crate::GitRevision, path: std::path::PathBuf) -> crate::GitSnapshot {
-        return crate::GitSnapshot { path, revision };
-    }
-
-    /// Return the local root containing the materialized repository content.
-    pub fn path(&self) -> &std::path::Path {
-        return self.path.as_path();
-    }
-
-    /// Return the authoritative revision represented by the snapshot.
-    pub fn revision(&self) -> &crate::GitRevision {
-        return &self.revision;
-    }
-}
-
+pub use self::reference::GitReference;
 /// Provider-neutral operations required from a Git repository backend.
-///
-/// Implementations may use a local Git executable, a Rust Git library or another generic Git
-/// mechanism. Forge-only capabilities do not belong to this trait.
-pub trait GitRepository {
-    /// Implementation-specific recoverable error.
-    type Error;
-
-    /// Refresh the local view of one configured source when the backend requires it.
-    fn refresh(&mut self, source_id: &knowledge_domain_lib::SourceId) -> Result<(), Self::Error>;
-
-    /// Resolve one opaque reference to the authoritative revision used by synchronization.
-    fn resolve_revision(&self, source_id: &knowledge_domain_lib::SourceId, reference: &crate::GitReference) -> Result<crate::GitRevision, Self::Error>;
-
-    /// Prepare or validate a read-only local snapshot for one resolved revision.
-    fn prepare_snapshot(&self, source_id: &knowledge_domain_lib::SourceId, revision: &crate::GitRevision) -> Result<crate::GitSnapshot, Self::Error>;
-}
+pub use self::repository::GitRepository;
+/// Resolved authoritative Git revision identity.
+pub use self::revision::GitRevision;
+/// Read-only local materialization of one authoritative Git revision.
+pub use self::snapshot::GitSnapshot;
 
 #[cfg(test)]
 #[path = "../unit_tests/lib.rs"]

crates/knowledge-git-api/src/reference.rs

@@ -0,0 +1,18 @@
+// file: crates/knowledge-git-api/src/reference.rs
+// version: 1
+
+/// Opaque Git reference requested by a caller, such as a branch, tag or object expression.
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub struct GitReference(String);
+
+impl crate::GitReference {
+    /// Create an opaque Git reference without imposing one provider's reference grammar.
+    pub fn new(value: &str) -> crate::GitReference {
+        return crate::GitReference(value.to_owned());
+    }
+
+    /// Return the reference text.
+    pub fn as_str(&self) -> &str {
+        return self.0.as_str();
+    }
+}

crates/knowledge-git-api/src/repository.rs

@@ -0,0 +1,20 @@
+// file: crates/knowledge-git-api/src/repository.rs
+// version: 1
+
+/// Provider-neutral operations required from a Git repository backend.
+///
+/// Implementations may use a local Git executable, a Rust Git library or another generic Git
+/// mechanism. Forge-only capabilities do not belong to this trait.
+pub trait GitRepository {
+    /// Implementation-specific recoverable error.
+    type Error;
+
+    /// Refresh the local view of one configured source when the backend requires it.
+    fn refresh(&mut self, source_id: &knowledge_domain_lib::SourceId) -> Result<(), Self::Error>;
+
+    /// Resolve one opaque reference to the authoritative revision used by synchronization.
+    fn resolve_revision(&self, source_id: &knowledge_domain_lib::SourceId, reference: &crate::GitReference) -> Result<crate::GitRevision, Self::Error>;
+
+    /// Prepare or validate a read-only local snapshot for one resolved revision.
+    fn prepare_snapshot(&self, source_id: &knowledge_domain_lib::SourceId, revision: &crate::GitRevision) -> Result<crate::GitSnapshot, Self::Error>;
+}

crates/knowledge-git-api/src/revision.rs

@@ -0,0 +1,18 @@
+// file: crates/knowledge-git-api/src/revision.rs
+// version: 1
+
+/// Resolved authoritative Git revision identity.
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub struct GitRevision(String);
+
+impl crate::GitRevision {
+    /// Create a revision identity returned by a concrete Git implementation.
+    pub fn new(value: &str) -> crate::GitRevision {
+        return crate::GitRevision(value.to_owned());
+    }
+
+    /// Return the revision identity as text.
+    pub fn as_str(&self) -> &str {
+        return self.0.as_str();
+    }
+}

crates/knowledge-git-api/src/snapshot.rs

@@ -0,0 +1,26 @@
+// file: crates/knowledge-git-api/src/snapshot.rs
+// version: 1
+
+/// Read-only local materialization of one authoritative Git revision.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct GitSnapshot {
+    path: std::path::PathBuf,
+    revision: crate::GitRevision,
+}
+
+impl crate::GitSnapshot {
+    /// Build a snapshot contract from a resolved revision and its local read root.
+    pub fn new(revision: crate::GitRevision, path: std::path::PathBuf) -> crate::GitSnapshot {
+        return crate::GitSnapshot { path, revision };
+    }
+
+    /// Return the local root containing the materialized repository content.
+    pub fn path(&self) -> &std::path::Path {
+        return self.path.as_path();
+    }
+
+    /// Return the authoritative revision represented by the snapshot.
+    pub fn revision(&self) -> &crate::GitRevision {
+        return &self.revision;
+    }
+}