feat(hm-common): add GitSha newtype, validate commit sites

Introduce a validated git object-id type (40/64 hex, lowercase, null-oid
sentinel) with transparent-string serde, and thread it through every
place a commit id is produced or carried:

- git::head_commit() -> Option<GitSha>, parsed from rev-parse.
- exec::SourceMeta.commit: GitSha, converted to String only at the
  harmont-cloud SDK boundary.
- hm run derives the commit as GitSha::zero() when git has none.
- cloud run's --commit parses to GitSha at clap time, rejecting a
  malformed id before submission.

Author: markovejnovic

crates/hm-common/src/git.rs

@@ -1,4 +1,4 @@
-//! Running git.
+//! Git integration: running the `git` CLI and git value types.
 
 use std::path::{Path, PathBuf};
 use std::process::Command;
@@ -7,6 +7,98 @@ use bstr::{BStr, BString, ByteSlice};
 
 use crate::process::{CapturedStreams as _, CommandExt as _};
 
+/// A git object identifier: a full 40-char SHA-1 or 64-char SHA-256 hex
+/// digest, normalized to lowercase.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct GitSha(String);
+
+/// A string that is not a valid [`GitSha`].
+#[derive(Debug, thiserror::Error, PartialEq, Eq)]
+pub enum GitShaError {
+    /// The digest is not 40 (SHA-1) or 64 (SHA-256) hex characters long.
+    #[error("git sha must be 40 or 64 hex chars, got {0}")]
+    BadLength(usize),
+    /// The digest contains a non-hex character.
+    #[error("git sha contains a non-hex character")]
+    NotHex,
+}
+
+impl GitSha {
+    /// The all-zero SHA-1 null oid (`0000…`, 40 chars) git uses to mean
+    /// "no commit".
+    #[must_use]
+    pub fn zero() -> Self {
+        Self("0".repeat(40))
+    }
+
+    /// The digest as a lowercase hex string.
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    /// Whether this is the all-zero null oid git uses to mean "no commit".
+    #[must_use]
+    pub fn is_zero(&self) -> bool {
+        self.0.bytes().all(|b| b == b'0')
+    }
+}
+
+impl std::str::FromStr for GitSha {
+    type Err = GitShaError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        if s.len() != 40 && s.len() != 64 {
+            return Err(GitShaError::BadLength(s.len()));
+        }
+        if !s.bytes().all(|b| b.is_ascii_hexdigit()) {
+            return Err(GitShaError::NotHex);
+        }
+        Ok(Self(s.to_ascii_lowercase()))
+    }
+}
+
+impl TryFrom<&str> for GitSha {
+    type Error = GitShaError;
+
+    fn try_from(s: &str) -> Result<Self, Self::Error> {
+        s.parse()
+    }
+}
+
+impl TryFrom<String> for GitSha {
+    type Error = GitShaError;
+
+    fn try_from(s: String) -> Result<Self, Self::Error> {
+        s.parse()
+    }
+}
+
+impl std::fmt::Display for GitSha {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+impl AsRef<str> for GitSha {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+impl serde::Serialize for GitSha {
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        serializer.serialize_str(&self.0)
+    }
+}
+
+impl<'de> serde::Deserialize<'de> for GitSha {
+    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let s = String::deserialize(deserializer)?;
+        s.parse().map_err(serde::de::Error::custom)
+    }
+}
+
 /// A path that is not a git repository.
 #[derive(Debug, thiserror::Error)]
 #[error("`{path}` is not a git repository")]
@@ -95,11 +187,12 @@ impl<'r, 'g, 'bin> GitBranch<'r, 'g, 'bin> {
         self.name.as_bstr()
     }
 
-    /// The commit the branch points at, as a hex object id. `None` if git fails.
+    /// The commit the branch points at. `None` if git fails or its output is
+    /// not a valid object id.
     #[tracing::instrument(skip(self))]
-    pub fn head_commit(&self) -> Option<BString> {
+    pub fn head_commit(&self) -> Option<GitSha> {
         let name = self.name.to_str().ok()?;
-        self.repo.run(&["rev-parse", name])
+        self.repo.run(&["rev-parse", name])?.to_str().ok()?.parse().ok()
     }
 }
 
@@ -182,6 +275,66 @@ mod tests {
     use super::*;
     use rstest::rstest;
 
+    #[rstest]
+    #[case::sha1_lower(
+        "0123456789abcdef0123456789abcdef01234567",
+        "0123456789abcdef0123456789abcdef01234567"
+    )]
+    #[case::sha1_upper(
+        "0123456789ABCDEF0123456789ABCDEF01234567",
+        "0123456789abcdef0123456789abcdef01234567"
+    )]
+    #[case::sha256(
+        "ABCDEF0123456789abcdef0123456789ABCDEF0123456789abcdef0123456789",
+        "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
+    )]
+    fn parses_and_lowercases(#[case] input: &str, #[case] expected: &str) {
+        let sha: GitSha = input.parse().unwrap();
+        assert_eq!(sha.as_str(), expected);
+    }
+
+    #[rstest]
+    #[case::empty(0)]
+    #[case::short(39)]
+    #[case::between(41)]
+    #[case::over(65)]
+    fn rejects_wrong_length(#[case] len: usize) {
+        assert_eq!("a".repeat(len).parse::<GitSha>(), Err(GitShaError::BadLength(len)));
+    }
+
+    #[rstest]
+    fn rejects_non_hex() {
+        let with_g = format!("{}g", "a".repeat(39));
+        assert_eq!(with_g.parse::<GitSha>(), Err(GitShaError::NotHex));
+    }
+
+    #[rstest]
+    #[case::sha1(40)]
+    #[case::sha256(64)]
+    fn zeros_are_the_null_oid(#[case] len: usize) {
+        let sha: GitSha = "0".repeat(len).parse().unwrap();
+        assert!(sha.is_zero());
+    }
+
+    #[rstest]
+    fn non_zero_is_not_the_null_oid() {
+        let sha: GitSha = "0123456789abcdef0123456789abcdef01234567".parse().unwrap();
+        assert!(!sha.is_zero());
+    }
+
+    #[rstest]
+    fn serde_round_trips_as_a_bare_string() {
+        let sha: GitSha = "0123456789abcdef0123456789abcdef01234567".parse().unwrap();
+        let json = serde_json::to_string(&sha).unwrap();
+        assert_eq!(json, "\"0123456789abcdef0123456789abcdef01234567\"");
+        assert_eq!(serde_json::from_str::<GitSha>(&json).unwrap(), sha);
+    }
+
+    #[rstest]
+    fn deserialize_rejects_an_invalid_digest() {
+        assert!(serde_json::from_str::<GitSha>("\"not-a-sha\"").is_err());
+    }
+
     #[rstest]
     #[case::https("https://github.com/acme/web.git", Some("acme/web"))]
     #[case::https_no_suffix("https://github.com/acme/web", Some("acme/web"))]
@@ -251,7 +404,7 @@ mod tests {
 
         let branch = repo.current_branch().unwrap();
         assert_eq!(branch.name(), "main");
-        assert_eq!(branch.head_commit().unwrap().len(), 40);
+        assert_eq!(branch.head_commit().unwrap().as_str().len(), 40);
 
         let remote = repo.remote("origin").unwrap();
         assert_eq!(remote.name(), "origin");

crates/hm-core/src/exec/cloud/backend.rs

@@ -104,7 +104,7 @@ impl ExecutionBackend for CloudBackend {
                     org: self.org.clone(),
                     pipeline: slug,
                     branch: req.source.branch.clone(),
-                    commit: req.source.commit.clone(),
+                    commit: req.source.commit.to_string(),
                     message: req.source.message.clone(),
                     pipeline_ir: req.plan.ir_json.clone(), // verbatim
                     source_tgz,
@@ -126,7 +126,7 @@ impl ExecutionBackend for CloudBackend {
                     repo_name,
                     source_slug: req.pipeline_slug.clone(),
                     branch: req.source.branch.clone(),
-                    commit: req.source.commit.clone(),
+                    commit: req.source.commit.to_string(),
                     message: req.source.message.clone(),
                     pipeline_ir: req.plan.ir_json.clone(), // verbatim
                     source_tgz,

crates/hm-core/src/exec/request.rs

@@ -4,6 +4,7 @@ use std::collections::BTreeMap;
 use std::path::PathBuf;
 use std::time::Duration;
 
+use hm_common::git::GitSha;
 use hm_pipeline_ir::PipelineGraph;
 use hm_plugin_protocol::events::PlanSummary;
 
@@ -61,7 +62,7 @@ fn summarize(graph: &PipelineGraph) -> PlanSummary {
 #[derive(Debug, Clone)]
 pub struct SourceMeta {
     pub branch: String,
-    pub commit: String,
+    pub commit: GitSha,
     pub message: Option<String>,
     /// `owner/repo` from the worktree's git remote, when one exists. `None` for
     /// a remoteless worktree; the cloud backend requires it to resolve the

crates/hm-core/tests/backend_contract.rs

@@ -8,6 +8,7 @@
 )]
 
 use futures::StreamExt;
+use hm_common::git::GitSha;
 use hm_core::exec::*;
 use hm_plugin_protocol::events::{BuildEvent, BuildRef};
 use hm_plugin_protocol::ir::DurationMs;
@@ -136,7 +137,7 @@ fn fake_request() -> RunRequest {
         env: Default::default(),
         source: SourceMeta {
             branch: "main".into(),
-            commit: "0".repeat(40),
+            commit: GitSha::zero(),
             message: None,
             repo_name: None,
         },

crates/hm/src/commands/cloud/verbs/run.rs

@@ -12,6 +12,7 @@ use std::collections::BTreeMap;
 use anyhow::Result;
 use clap::Parser;
 use harmont_cloud::builds::NewBuild;
+use hm_common::git::GitSha;
 use hm_core::app_ctx::AppCtx;
 
 use crate::commands::cloud::settings;
@@ -24,12 +25,8 @@ pub struct RunArgs {
     #[arg(short, long, default_value = "main")]
     pub branch: String,
     /// Commit SHA to record on the build.
-    #[arg(
-        short,
-        long,
-        default_value = "0000000000000000000000000000000000000000"
-    )]
-    pub commit: String,
+    #[arg(short, long, default_value_t = GitSha::zero())]
+    pub commit: GitSha,
     /// Build message.
     #[arg(short, long)]
     pub message: Option<String>,
@@ -57,7 +54,7 @@ pub(crate) async fn run(env: &BTreeMap<String, String>, args: RunArgs, app: &App
             org: org.clone(),
             pipeline: args.pipeline.clone(),
             branch: args.branch.clone(),
-            commit: args.commit.clone(),
+            commit: args.commit.to_string(),
             message: args.message.clone(),
             pipeline_ir,
             // Full worktree archiving lands in `hm run --cloud`.

crates/hm/src/commands/run/mod.rs

@@ -3,7 +3,7 @@ use std::collections::HashMap;
 use anyhow::{Context, Result};
 
 use bstr::ByteSlice as _;
-use hm_common::git::{GitBranch, GitRemote, GitRepo};
+use hm_common::git::{GitBranch, GitRemote, GitRepo, GitSha};
 use hm_core::app_ctx::AppCtx;
 use hm_core::config::domain::BackendConfig;
 use hm_dsl_engine::{DslEngine, detect};
@@ -178,9 +178,7 @@ pub async fn handle(args: RunArgs, ctx: RunContext<'_>) -> Result<i32> {
         let commit = head
             .as_ref()
             .and_then(GitBranch::head_commit)
-            .map(|c| c.to_str_lossy().into_owned())
-            .filter(|s| !s.is_empty())
-            .unwrap_or_else(|| "0".repeat(40));
+            .unwrap_or_else(GitSha::zero);
         let repo_name = remote
             .as_ref()
             .and_then(GitRemote::gh_repo_name)