0.0.1-alpha.3

crates/knowledge-git-api/Cargo.toml

@@ -0,0 +1,15 @@
+# file: crates/knowledge-git-api/Cargo.toml
+# version: 1
+
+[package]
+name = "knowledge-git-api"
+version.workspace = true
+edition.workspace = true
+publish.workspace = true
+repository.workspace = true
+
+[dependencies]
+knowledge-domain-lib.workspace = true
+
+[lints]
+workspace = true

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

@@ -0,0 +1,57 @@
+// file: crates/knowledge-git-api/src/lib.rs
+// version: 1
+
+//! 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.
+
+/// 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();
+    }
+}
+
+/// 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>;
+}
+
+#[cfg(test)]
+mod unit_tests;

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

@@ -0,0 +1,35 @@
+// file: crates/knowledge-git-api/src/unit_tests.rs
+// version: 1
+
+#[derive(Debug, Eq, PartialEq)]
+struct FakeGitError;
+
+struct FakeGitRepository;
+
+impl crate::GitRepository for FakeGitRepository {
+    type Error = FakeGitError;
+
+    fn refresh(&mut self, _source_id: &knowledge_domain_lib::SourceId) -> Result<(), Self::Error> {
+        return Ok(());
+    }
+
+    fn resolve_revision(&self, source_id: &knowledge_domain_lib::SourceId, reference: &crate::GitReference) -> Result<crate::GitRevision, Self::Error> {
+        return Ok(crate::GitRevision::new(&format!("{}:{}", source_id.as_str(), reference.as_str())));
+    }
+}
+
+#[test]
+fn generic_repository_contract_does_not_require_a_forge() {
+    let source_result = knowledge_domain_lib::SourceId::new("local-pgr");
+    assert!(source_result.is_ok());
+    let source_id = match source_result {
+        Ok(value) => value,
+        Err(_) => return,
+    };
+    let reference = crate::GitReference::new("refs/heads/master");
+    let mut repository = FakeGitRepository;
+    assert!(crate::GitRepository::refresh(&mut repository, &source_id).is_ok());
+    let revision_result = crate::GitRepository::resolve_revision(&repository, &source_id, &reference);
+    assert_eq!(revision_result, Ok(crate::GitRevision::new("local-pgr:refs/heads/master")));
+    return;
+}