cli/bridge/git_util.rs
1// SPDX-License-Identifier: Apache-2.0
2//! Shared utilities and helpers for Git bridge operations.
3
4use ingest::LossyImportEntry;
5use objects::object::{State, Status};
6use sley::ObjectId as GitObjectId;
7
8use super::git_core::GitBridge;
9
10impl<'a> GitBridge<'a> {
11 /// Build a Git commit message from a Heddle state.
12 ///
13 /// Phase B (post-2026-05) onward: this is just the state's intent text,
14 /// verbatim. Heddle metadata (change_id, agent, confidence, status) is
15 /// carried out-of-band via `refs/notes/heddle` so that exported commit
16 /// SHAs match the SHAs of imported commits — a prerequisite for any
17 /// bidirectional sync where heddle and an upstream git host (e.g.
18 /// GitHub) need to agree on which commits already exist.
19 pub(crate) fn build_commit_message(state: &State) -> String {
20 // Status is intentionally not surfaced here — published-vs-draft
21 // belongs in heddle's note, not the commit message body, since
22 // including it would change the commit SHA whenever a user toggles
23 // the status field.
24 let _ = Status::Draft;
25 state
26 .intent
27 .clone()
28 .unwrap_or_else(|| "No intent specified".to_string())
29 }
30
31 /// Build a commit message that includes the W2 footer (R6).
32 ///
33 /// Footer layout (always emitted, last block of the message):
34 ///
35 /// ```text
36 /// <body>
37 ///
38 /// Heddle-State: <hex change-id>
39 /// Heddle-URL: <hosted_url>/state/<id> (omitted when no hosted URL)
40 /// Heddle-Annotations-Omitted: <count>
41 /// ```
42 ///
43 /// The footer is the durable record — every reader on every host gets
44 /// it regardless of remote configuration. Richer per-scope metadata
45 /// rides on the opt-in git note (see [`super::git_notes`]).
46 pub(crate) fn build_commit_message_with_footer(
47 state: &State,
48 hosted_url: Option<&str>,
49 annotations_omitted: u32,
50 ) -> String {
51 let body = Self::build_commit_message(state);
52 Self::build_commit_message_with_footer_with_body(
53 state,
54 &body,
55 hosted_url,
56 annotations_omitted,
57 )
58 }
59
60 pub(crate) fn build_commit_message_with_footer_with_body(
61 state: &State,
62 body: &str,
63 hosted_url: Option<&str>,
64 annotations_omitted: u32,
65 ) -> String {
66 let mut out = body.to_string();
67 if !out.ends_with('\n') {
68 out.push('\n');
69 }
70 out.push('\n');
71 out.push_str(&format!(
72 "Heddle-State: {}\n",
73 state.change_id.to_string_full()
74 ));
75 if let Some(url) = hosted_url
76 && !url.is_empty()
77 {
78 let trimmed = url.trim_end_matches('/');
79 out.push_str(&format!(
80 "Heddle-URL: {trimmed}/state/{}\n",
81 state.change_id.to_string_full()
82 ));
83 }
84 out.push_str(&format!(
85 "Heddle-Annotations-Omitted: {annotations_omitted}\n"
86 ));
87 out
88 }
89}
90
91/// Statistics for export operation.
92///
93/// `commits_total` counts the commits that actually land in the
94/// destination: it is derived from the same branch/tag ref set
95/// (`collect_ref_updates`) that `copy_mirror_to_path` copies, by walking
96/// the commit ancestry of those tips. Counting from the copy path — rather
97/// than a parallel walk over current Heddle refs — guarantees the reported
98/// total equals what's copied, including a stale mirror ref left behind by
99/// a dropped thread (export does not prune mirror refs, so that commit
100/// still travels and is still counted). `states_exported` is the
101/// freshly-minted *subset of that same copied ref set* — both counts are
102/// partitions of one walk, so `states_exported + already == commits_total`
103/// holds by construction and a state minted into the mirror but reachable
104/// from no copied ref (an orphan dropped-thread history) inflates neither.
105/// They diverge whenever the destination is already populated: an overlay
106/// re-export reports `commits_total = N` and `states_exported = 0` — the
107/// signal that surfaces "already in sync" instead of a misleading bare
108/// "exported 0 states" (heddle#289, mirroring the import-side
109/// `commits_imported`/`states_created` split from heddle#147).
110#[derive(Debug, Default)]
111pub struct ExportStats {
112 /// Freshly-minted git commits that land in the destination — the
113 /// subset of the copied ref set's commits minted during this export
114 /// (no preserved git_oid). Stays at 0 when every copied commit was
115 /// already mapped to an existing commit. A minted commit reachable
116 /// from no copied ref is excluded (it never reaches the destination).
117 pub states_exported: usize,
118 /// Unique commits reachable from the branch/tag tips copied to the
119 /// destination, including ones whose commit already existed and any
120 /// carried by a stale mirror ref. Mirrors
121 /// [`ImportStats::commits_imported`].
122 pub commits_total: usize,
123 pub threads_synced: usize,
124 pub markers_synced: usize,
125 /// Branches written to the destination, paired with their tip
126 /// commit so the summary can show tip short-SHAs.
127 pub branches: Vec<ExportedRef>,
128 /// Tags written to the destination, paired with their tip commit.
129 pub tags: Vec<ExportedRef>,
130}
131
132/// A ref written to the export destination, paired with the commit it
133/// points at (so the export summary can render tip short-SHAs).
134#[derive(Debug, Clone)]
135pub struct ExportedRef {
136 pub name: String,
137 pub tip: GitObjectId,
138}
139
140/// Statistics for import operation.
141///
142/// `commits_imported` counts every commit visited by the ancestry walk;
143/// `states_created` counts only the commits whose heddle state did not
144/// yet exist in the store. They diverge whenever a ref is re-imported
145/// (the second `bridge git import --ref X` against the same source
146/// reports `commits_imported = N` and `states_created = 0`) — that
147/// distinction is what surfaces "already in sync" instead of leaving
148/// the operator staring at a misleading `commits_imported: 0`
149/// (heddle#147).
150#[derive(Debug, Default)]
151pub struct ImportStats {
152 /// Total commits walked from the source refs, including ones whose
153 /// heddle state was already present. Mirrors what `bridge git
154 /// ingest` reports so the two verbs read the same way.
155 pub commits_imported: usize,
156 /// New state objects written to the heddle store during this
157 /// import. Stays at 0 when every visited commit already had a
158 /// heddle state — that's the signal the bridge is in sync.
159 pub states_created: usize,
160 pub branches_synced: usize,
161 pub tags_synced: usize,
162 /// Refs (typically annotated tags) that point at a non-commit object —
163 /// most often a blob (e.g. `git/git`'s `refs/tags/junio-gpg-pub`
164 /// pointing at the maintainer's GPG public key blob) or a tree
165 /// (e.g. `git-lfs`'s `refs/tags/core-gpg-keys`).
166 ///
167 /// These are skipped during walk because heddle's marker model
168 /// currently requires the target to be a commit. The full-fidelity
169 /// fix is to extend the marker model with a non-commit-ref variant;
170 /// until then we record them here so callers can surface what was
171 /// skipped.
172 pub skipped_non_commit_refs: usize,
173 /// Git tree entries converted under an explicit lossy import opt-in.
174 pub lossy_entries: Vec<LossyImportEntry>,
175}
176
177#[cfg(test)]
178mod tests {
179 // ── R6 — bridge footer ─────────────────────────────────────────────
180 use objects::object::{Attribution, ChangeId, ContentHash, Principal};
181
182 use super::*;
183
184 fn sample_state() -> State {
185 State::new_snapshot(
186 ContentHash::compute(b"tree"),
187 vec![],
188 Attribution::human(Principal::new("Alice", "alice@example.com")),
189 )
190 .with_intent("ship the auth rewrite")
191 }
192
193 #[test]
194 fn footer_emits_state_id_and_zero_omitted_when_no_url() {
195 let state = sample_state();
196 let msg = GitBridge::build_commit_message_with_footer(&state, None, 0);
197 assert!(msg.contains(&format!(
198 "Heddle-State: {}",
199 state.change_id.to_string_full()
200 )));
201 assert!(msg.contains("Heddle-Annotations-Omitted: 0"));
202 assert!(!msg.contains("Heddle-URL:"));
203 }
204
205 #[test]
206 fn footer_emits_url_when_hosted_configured() {
207 let state = sample_state();
208 let msg =
209 GitBridge::build_commit_message_with_footer(&state, Some("https://heddle.test/"), 3);
210 assert!(msg.contains(&format!(
211 "Heddle-URL: https://heddle.test/state/{}",
212 state.change_id.to_string_full()
213 )));
214 assert!(msg.contains("Heddle-Annotations-Omitted: 3"));
215 }
216
217 // The state_id from `change_id.to_string_full()` is referenced via
218 // `ChangeId` for the bound on `state.change_id` — keep the import.
219 #[test]
220 fn change_id_round_trips_through_footer() {
221 let state = sample_state();
222 let id_str = state.change_id.to_string_full();
223 let _: ChangeId = ChangeId::parse(&id_str).expect("round-trip parse");
224 }
225}