atproto-devtool 0.1.1

//! Builder for the sentinel `reason` field used in conformance-test reports.
//!
//! Every committing check's report body carries a stable, recognizable
//! string in its `reason` field so that labeler operators can identify and
//! dismiss reports submitted by `atproto-devtool` without mistaking them
//! for real user reports.
//!
//! Format: `atproto-devtool conformance test <RFC3339-UTC> <run-id>`
//!
//! Example: `atproto-devtool conformance test 2026-04-17T12:34:56Z 5f9c1a3b4d7e8a0f`
//!
//! The run-id is a 16-hex-char random nonce generated once per pipeline run
//! (not per check); the same run-id is reused across all report submissions
//! within a single `test labeler` invocation so operators can trace a group
//! of test reports back to one run.

use std::time::{SystemTime, UNIX_EPOCH};

/// Prefix used so operators can grep their moderation queue for
/// conformance-test reports with a single query.
pub const SENTINEL_PREFIX: &str = "atproto-devtool conformance test";

/// Build a sentinel reason string. `run_id` should be a stable 16-hex-char
/// identifier for the current test invocation; `now` is the current wall-clock
/// time, typically `SystemTime::now()`.
pub fn build(run_id: &str, now: SystemTime) -> String {
    let rfc3339 = format_rfc3339_utc(now);
    format!("{SENTINEL_PREFIX} {rfc3339} {run_id}")
}

/// Hand-rolled RFC 3339 UTC formatter: `YYYY-MM-DDTHH:MM:SSZ`.
///
/// Avoids a `chrono` / `time` dependency. Leap seconds are not handled;
/// the sentinel reason is a human-readable label, not a parseable timestamp.
/// For times before the UNIX epoch or more than `i64::MAX` seconds in the
/// future we degrade gracefully to `1970-01-01T00:00:00Z`.
pub fn format_rfc3339_utc(ts: SystemTime) -> String {
    let secs = ts
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_secs() as i64)
        .unwrap_or(0);
    let (year, month, day, hour, min, sec) = unix_to_civil(secs);
    format!("{year:04}-{month:02}-{day:02}T{hour:02}:{min:02}:{sec:02}Z")
}

/// Convert UNIX seconds to a civil date-time (UTC) using Howard Hinnant's
/// algorithm for the Gregorian calendar. Correct for all years in [1, 9999].
pub fn unix_to_civil(secs: i64) -> (i32, u32, u32, u32, u32, u32) {
    // Seconds-of-day.
    let days = secs.div_euclid(86_400);
    let sod = secs.rem_euclid(86_400);
    let hour = (sod / 3600) as u32;
    let min = ((sod % 3600) / 60) as u32;
    let sec = (sod % 60) as u32;

    // Days since 1970-01-01 -> civil date. Algorithm from
    // http://howardhinnant.github.io/date_algorithms.html#civil_from_days.
    let z = days + 719_468;
    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
    let doe = (z - era * 146_097) as u32; // [0, 146096]
    let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146_096) / 365; // [0, 399]
    let y = yoe as i32 + era as i32 * 400;
    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); // [0, 365]
    let mp = (5 * doy + 2) / 153; // [0, 11]
    let d = doy - (153 * mp + 2) / 5 + 1; // [1, 31]
    let m = if mp < 10 { mp + 3 } else { mp - 9 }; // [1, 12]
    let year = if m <= 2 { y + 1 } else { y };
    (year, m, d, hour, min, sec)
}

/// Generate a random 16-hex-char run identifier. Uses `getrandom`
/// (panics if the OS CSPRNG is unavailable, which cannot happen on supported
/// platforms).
pub fn new_run_id() -> String {
    let mut bytes = [0u8; 8];
    getrandom::getrandom(&mut bytes).expect("OS CSPRNG is always available on supported platforms");
    #[expect(clippy::format_collect)]
    {
        bytes.iter().map(|b| format!("{b:02x}")).collect()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn format_rfc3339_utc_pins_known_points() {
        // Pre-epoch time degrades gracefully to 1970-01-01T00:00:00Z.
        let before_epoch = UNIX_EPOCH.checked_sub(std::time::Duration::from_secs(1));
        if let Some(t) = before_epoch {
            assert_eq!(format_rfc3339_utc(t), "1970-01-01T00:00:00Z");
        }

        // 1970-01-01T00:00:00Z (epoch).
        assert_eq!(format_rfc3339_utc(UNIX_EPOCH), "1970-01-01T00:00:00Z");

        // 2024-02-29T00:00:00Z (leap year, leap day).
        let t = UNIX_EPOCH + std::time::Duration::from_secs(1_709_164_800);
        assert_eq!(format_rfc3339_utc(t), "2024-02-29T00:00:00Z");

        // 2024-02-29T12:34:56Z (leap year, leap day with time).
        let t = UNIX_EPOCH + std::time::Duration::from_secs(1_709_210_096);
        assert_eq!(format_rfc3339_utc(t), "2024-02-29T12:34:56Z");

        // 2000-02-29T00:00:00Z (leap year, leap day in year 2000).
        let t = UNIX_EPOCH + std::time::Duration::from_secs(951_782_400);
        assert_eq!(format_rfc3339_utc(t), "2000-02-29T00:00:00Z");

        // 1972-02-29T00:00:00Z (leap year).
        let t = UNIX_EPOCH + std::time::Duration::from_secs(68_169_600);
        assert_eq!(format_rfc3339_utc(t), "1972-02-29T00:00:00Z");

        // Year 9999-12-31T23:59:59Z (boundary).
        let t = UNIX_EPOCH + std::time::Duration::from_secs(253_402_300_799);
        assert_eq!(format_rfc3339_utc(t), "9999-12-31T23:59:59Z");
    }

    #[test]
    fn build_contains_prefix_and_run_id() {
        let s = build("abcdef1234567890", UNIX_EPOCH);
        assert!(s.starts_with(SENTINEL_PREFIX));
        assert!(s.ends_with("abcdef1234567890"));
        assert!(s.contains("1970-01-01T00:00:00Z"));
    }

    #[test]
    fn new_run_id_is_16_hex_chars() {
        let id = new_run_id();
        assert_eq!(id.len(), 16);
        assert!(id.chars().all(|c| c.is_ascii_hexdigit()));
    }

    #[test]
    fn new_run_id_is_unique_between_calls() {
        let a = new_run_id();
        let b = new_run_id();
        assert_ne!(a, b);
    }
}