git_policy_cli/
hook_dispatch_entries.rs

1//! What:
2//!  The hooks directory of one commit transaction:
3//!  its `plan.json` and one entry per preparation event.
4//! Why:
5//!  Git starts a hook through `core.hooksPath` by the entry's path, so the entry's name is the event
6//!  and the executable it starts is the native wrapper.
7//!  On Windows Git looks for `<event>.exe`, so entries are hard links or copies with that name.
8//!
9//! In TS you'd write (pseudocode):
10//! ```ts
11//! await writeHookShim({ hooksDirectory, plan, nodePath: process.execPath });
12//! ```
13
14/// Plan spelling shared with the reader.
15use super::hook_dispatch_plan::{
16    HookDispatchPlan, PLAN_FILENAME, PREPARATION_HOOK_EVENTS, encode_hook_dispatch_plan,
17};
18/// Private directory creation and exclusive private file writes.
19use super::private_storage::{create_private_directory, write_private_file};
20/// `Path`/`PathBuf` are borrowed/owned filesystem paths.
21use std::path::{Path, PathBuf};
22
23/// What:
24///  Why writing a hooks directory failed, naming the path.
25/// Why:
26///   The caller stops the transaction; a partial hooks directory is never reused.
27///
28/// In TS you'd write (pseudocode):
29/// ```ts
30/// throw new Error(`cannot write ${path}`);
31/// ```
32#[derive(Clone, Debug, Eq, PartialEq)]
33pub struct HookEntryError(pub String);
34
35/// What:
36///  One sentence naming the hook entry that failed.
37/// Why:
38///   The caller prints it as the diagnostic.
39///
40/// In TS you'd write (pseudocode):
41/// ```ts
42/// error.message
43/// ```
44impl std::fmt::Display for HookEntryError {
45    /// Writes the stored sentence.
46    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
47        return write!(formatter, "{}", self.0);
48    }
49}
50
51/// What:
52///  The file name of one preparation event's entry.
53/// Why:
54///   Unix names the entry after the event; Windows adds `.exe`, which Git appends when it looks up a hook.
55///
56/// In TS you'd write (pseudocode):
57/// ```ts
58/// process.platform === 'win32' ? `${event}.exe` : event;
59/// ```
60pub fn hook_entry_name(event: &str) -> String {
61    if cfg!(windows) {
62        return format!("{event}.exe");
63    }
64    return String::from(event);
65}
66
67/// What:
68///  Write one entry that starts `executable` under its event's name.
69/// Why:
70///   Unix symbolic links keep the start name as `argv[0]`;
71///  Windows entries are hard links, or copies where hard links are refused.
72///
73/// In TS you'd write (pseudocode):
74/// ```ts
75/// await writeFile(join(hooksDirectory, event), hookEntryProgram({ nodePath, dispatchUrl, event }));
76/// ```
77fn write_entry(executable: &Path, entry: &Path) -> std::io::Result<()> {
78    #[cfg(unix)]
79    {
80        std::os::unix::fs::symlink(executable, entry)?;
81    }
82    #[cfg(windows)]
83    {
84        if std::fs::hard_link(executable, entry).is_err() {
85            std::fs::copy(executable, entry)?;
86        }
87    }
88    return Ok(());
89}
90
91/// What:
92///  Create a new hooks directory holding the plan and one entry per preparation event.
93/// Why:
94///   The incumbent's `writeHookShim`, with native entries instead of a Node program:
95///  `post-commit` has no entry, so it never runs during preparation.
96///  The directory must not exist, so nothing half-written is reused.
97///
98/// In TS you'd write (pseudocode):
99/// ```ts
100/// await writeHookShim({ hooksDirectory, plan, nodePath });
101/// ```
102pub fn write_hook_dispatch(
103    hooks_directory: &Path,
104    plan: &HookDispatchPlan,
105    executable: &Path,
106) -> Result<(), HookEntryError> {
107    create_private_directory(hooks_directory).map_err(|error| {
108        return HookEntryError(format!(
109            "cannot create the hook directory {}: {error}",
110            hooks_directory.display()
111        ))
112    })?;
113    let plan_path: PathBuf = hooks_directory.join(PLAN_FILENAME);
114    let plan_bytes: String = format!("{}\n", encode_hook_dispatch_plan(plan));
115    write_private_file(plan_path.as_path(), plan_bytes.as_bytes()).map_err(|error| {
116        return HookEntryError(format!(
117            "cannot write the hook plan {}: {error}",
118            plan_path.display()
119        ))
120    })?;
121    for event in PREPARATION_HOOK_EVENTS {
122        let entry: PathBuf = hooks_directory.join(hook_entry_name(event));
123        write_entry(executable, entry.as_path()).map_err(|error| {
124            return HookEntryError(format!(
125                "cannot write the hook entry {}: {error}",
126                entry.display()
127            ))
128        })?;
129    }
130    return Ok(());
131}
132
133#[cfg(test)]
134#[path = "hook_dispatch_entries_tests.rs"]
135mod tests;
git_policy_cli/hook_dispatch_entries.rs

git_policy_cli/
hook_dispatch_entries.rs
