monochromatic-git-policy-cli 0.5.31

//! What:
//!  The service's handler for a `review` work item: read the landed commit, ask the decision gateway, and append the
//!  entry to the repository's live shadow log, every step ending on no progress and none on the clock.
//! Why:
//!  This replaces the repository's post-commit hook that ran `mise run shadow-review` (`doc/runbook/standards-review-gate.md`).
//!  The review shares the service's work thread with pushes and upkeep, so every step ends by itself: the gateway call on the
//!  idle timeouts of its transport, the Git reads under the watch of `child_watch.rs`; the local write of the entry has no
//!  judge (pick 9 of `doc/planning/cli-git-shipped-limits-audit.md`, the coordinator's under the owner's delegation and open to
//!  the owner's veto; it replaces the 20 second budget around the whole run). A review that fails leaves its item in
//!  `failed` as a plain record and the log shows the gateway's failure as an entry; nothing is ever left claimed.
//!
//! In TS you'd write (pseudocode):
//! ```ts
//! const outcome = await reviewLanded(names, sha, subject, read, options);
//! ```

use crate::standards_review_input::has_shadow_log;
use crate::standards_review_run::{Contained, ReviewOptions, ReviewOutcome, options_from_environment, review_landed, run_contained};
use crate::standards_review_source::{read_landed_commit, read_message, read_names};
use crate::standards_review_text::commit_subject;
use crate::service_review_key::{KEY_VARIABLES, ReviewKey};
use crate::service_work::Verdict;
use crate::transaction_git::GitContext;
use crate::work_item::WorkItem;
use std::path::{Path, PathBuf};
use std::time::Duration;

/// How long the gateway call may stay silent before it is ended.
///  Citation: none, and **unmeasured as a quiet window**. The figure was the call's total deadline, "several times the largest
///  figure on record (1.4 s in `doc/audit/standards-review-gate-shadow.md`)"; that is a whole time, and a whole time is an upper
///  bound of a quiet gap, not the gap. The gap of every call is now kept in the ledger (`quiet_ledger.rs`).
pub const CALL_QUIET_WINDOW: Duration = Duration::from_secs(10);

/// What:
///  The common Git directory of a worktree's Git directory: the directory its `commondir` file names, else the directory
///  itself.
/// Why:
///   A linked worktree's items carry that worktree's own Git directory (`.git/worktrees/<name>`), which Git deletes with the
///  worktree, while the repository's one log lives in the common directory. Git strips every trailing carriage return and
///  line feed and resolves a relative path against the Git directory (`get_common_dir_noenv` in `path.c`), as the layout
///  reader does; a path that cannot be resolved is used as written, so the entry still goes to the common directory.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// existsSync(join(gitDir, 'commondir')) ? realpath(resolve(gitDir, readFile(...).trimEnd())) : gitDir
/// ```
pub fn common_dir_of(git_dir: &Path) -> PathBuf {
    let Ok(text) = std::fs::read(git_dir.join("commondir")) else {
        return git_dir.to_path_buf();
    };
    let end: usize = text.iter().rposition(|byte| { return *byte != b'\r' && *byte != b'\n'; }).map_or(0, |last| { return last + 1; });
    if end == 0 {
        return git_dir.to_path_buf();
    }
    #[cfg(unix)]
    let named: PathBuf = PathBuf::from(<std::ffi::OsStr as std::os::unix::ffi::OsStrExt>::from_bytes(&text[..end]));
    #[cfg(not(unix))]
    let named: PathBuf = PathBuf::from(String::from_utf8_lossy(&text[..end]).into_owned());
    let joined: PathBuf = git_dir.join(named);
    return std::fs::canonicalize(&joined).unwrap_or(joined);
}

/// What:
///  The options for one item: the script's environment variables read from the service's environment, and the call
///  deadline; the log is the item's repository's live log in its common Git directory.
/// Why:
///   Every worktree of a repository appends to that repository's one log, and a service that serves several repositories
///   writes each one's own; the item names its worktree's Git directory, and the common one follows from it with no Git start.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// optionsFor(item, process.env)
/// ```
pub fn options_for(item: &WorkItem, variable: &dyn Fn(&str) -> Option<String>) -> ReviewOptions {
    let common: PathBuf = common_dir_of(Path::new(item.git_dir.as_str()));
    let mut options: ReviewOptions = options_from_environment(common.as_path(), variable);
    options.quiet_window = CALL_QUIET_WINDOW;
    return options;
}

/// What:
///  The variable lookup the review's options read: the credential variables answer from the key that came in the wake
///  message and from nowhere else, and every other variable answers from the service's environment.
/// Why:
///   The credential is never in the service's environment or in a unit file, so a service that did not receive a key in
///   the message must record "no key" and not pick up a stray value; the service's environment carries no secret.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// (name) => keyNames.includes(name) ? fromMessage(name) : process.env[name]
/// ```
pub fn review_variables(key: Option<&ReviewKey>) -> impl Fn(&str) -> Option<String> {
    let exposed: Option<String> = key.map(|held| { return held.expose().to_string(); });
    return move |name: &str| {
        if name == KEY_VARIABLES[0] {
            return exposed.clone();
        }
        if name == KEY_VARIABLES[1] {
            return None;
        }
        return std::env::var(name).ok();
    };
}

/// The Git reads, the subject and the review, without the budget.
fn run_review(context: &GitContext, item: &WorkItem, options: &ReviewOptions, now_millis: &dyn Fn() -> u64) -> ReviewOutcome {
    let cwd: PathBuf = PathBuf::from(item.repository.as_str());
    let names: Vec<String> = match read_names(context, cwd.as_path(), item.oid.as_str()) {
        Ok(found) => found,
        Err(message) => return ReviewOutcome::Unread(message),
    };
    let subject: String = match read_message(context, cwd.as_path(), item.oid.as_str()) {
        Ok(message) => commit_subject(message.as_str()),
        Err(message) => return ReviewOutcome::Unread(message),
    };
    let read = |files: &[String]| { return read_landed_commit(context, cwd.as_path(), item.oid.as_str(), subject.as_str(), files); };
    return review_landed(names.as_slice(), item.oid.as_str(), subject.as_str(), &read, options, now_millis);
}

/// The wall clock in milliseconds since 1970.
fn wall_clock_millis() -> u64 {
    return std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map_or(0, |elapsed| { return u64::try_from(elapsed.as_millis()).unwrap_or(u64::MAX); });
}

/// What:
///  Review one item: `Done` when an entry was written, was not needed, or the worktree does not hold the tracked shadow log that
///  switches the review on; `Failed` with the reason when the commit could not be read, the log could not be written, or the
///  review stopped with an internal error.
/// Why:
///   The caller settles `Failed` items into `failed`, so a review that cannot finish is a plain record and never a stuck claim.
///  No budget covers the whole run; each step ends on no progress by itself.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// await reviewItem(context, item, options)
/// ```
pub fn review_item(context: &GitContext, item: &WorkItem, options: ReviewOptions) -> Verdict {
    if !has_shadow_log(Path::new(item.repository.as_str())) {
        return Verdict::Done;
    }
    // The service serves many repositories, so its own context names none; the Git command that takes input needs the
    // item's Git directory for its input file, as the landing sets it for each request.
    let owned_context: GitContext = GitContext { common_dir: Some(PathBuf::from(item.git_dir.as_str())), ..context.clone() };
    let owned: WorkItem = item.clone();
    let outcome: Contained<ReviewOutcome> = run_contained(move || { return run_review(&owned_context, &owned, &options, &wall_clock_millis); }, crate::wait_ceilings::REVIEW_CEILING);
    return match outcome {
        Contained::Panicked => Verdict::Failed(format!("the review of {} stopped with an internal error", item.oid)),
        Contained::CeilingReached(ceiling) => Verdict::Failed(ceiling_reason(item.oid.as_str(), ceiling)),
        Contained::Finished(ReviewOutcome::Unread(message) | ReviewOutcome::Unwritable(message)) => Verdict::Failed(message),
        Contained::Finished(ReviewOutcome::NoEntry | ReviewOutcome::Skipped | ReviewOutcome::Reviewed(_) | ReviewOutcome::AlreadyLogged) => Verdict::Done,
    };
}

/// What:
///  The reason of a review that ran as long as the service lets one run.
/// Why:
///   It names what was running (the standards review of the commit), the ceiling, and the command that does it again.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// `the standards review of ${oid} ran for ${seconds} seconds, ...; run SHADOW_REVIEW_SHA=${oid} mise run shadow-review`
/// ```
pub fn ceiling_reason(oid: &str, ceiling: Duration) -> String {
    return format!(
        "the standards review of {oid} ran for {} seconds, the longest the service lets one review run, and the service stopped waiting for it; \
         review it again with `SHADOW_REVIEW_SHA={oid} mise run shadow-review`",
        ceiling.as_secs()
    );
}

/// Review controls stay out of the release executable.
#[cfg(test)]
#[path = "service_review_tests.rs"]
mod tests;