reef-core 0.4.0

Provider-neutral primitives for building LLM agents: run lifecycle, transcript, tools, hooks
Documentation
#![cfg(test)]

use std::fmt::Debug;

use crate::redact::{Bytes, Items, Locked, Presence};

/// The one string every redaction test hides inside a value's content.
///
/// A redaction policy is only real if a test proves it, and the test only
/// proves it if the sentinel is distinctive enough that finding it in formatted
/// output cannot be a coincidence.
pub(crate) const SECRET: &str = "sk-REDACTION-SENTINEL";

/// Collects every `<…>` redaction token a rendering emitted, in order.
fn tokens(rendering: &str) -> Vec<&str> {
    let mut found = Vec::new();
    let mut rest = rendering;
    while let Some(open) = rest.find('<') {
        rest = &rest[open..];
        let Some(close) = rest.find('>') else {
            break;
        };
        found.push(&rest[..=close]);
        rest = &rest[close + 1..];
    }
    found
}

/// Asserts the two formatting flags differ in layout and in nothing else.
///
/// ADR-018 refused an alternate-flag escape hatch, and `{:#?}` is what `dbg!`
/// uses, so the refusal survives only while something keeps checking it. This
/// is that something: the sentinel must be absent from both renderings, and
/// both must emit the same redaction tokens in the same order.
#[track_caller]
pub(crate) fn assert_redacted<T: Debug>(value: &T) {
    let compact = format!("{value:?}");
    let alternate = format!("{value:#?}");
    assert!(
        !compact.contains(SECRET),
        "`{{:?}}` leaked the sentinel: {compact}"
    );
    assert!(
        !alternate.contains(SECRET),
        "`{{:#?}}` leaked the sentinel: {alternate}"
    );
    assert_eq!(
        tokens(&compact),
        tokens(&alternate),
        "the alternate flag changed what was redacted, not just the layout"
    );
}

/// Asserts the shape facts a redacted rendering owes its reader.
///
/// Redaction that says nothing is the `Type { .. }` failure mode ADR-018 exists
/// to prevent, so every redaction test states what *should* appear as well as
/// what must not. Facts are checked against `{:?}`, whose layout is stable;
/// `assert_redacted` is what ties `{:#?}` to it.
#[track_caller]
pub(crate) fn assert_states<T: Debug>(value: &T, facts: &[&str]) {
    let rendering = format!("{value:?}");
    for fact in facts {
        assert!(
            rendering.contains(fact),
            "redacted output dropped `{fact}`: {rendering}"
        );
    }
}

#[test]
fn bytes_states_a_size_and_never_a_content_byte() {
    assert_eq!(format!("{:?}", Bytes(0)), "<0 bytes>");
    assert_eq!(format!("{:?}", Bytes(42)), "<42 bytes>");
    assert_eq!(format!("{:#?}", Bytes(42)), "<42 bytes>");
}

#[test]
fn items_states_a_length() {
    assert_eq!(format!("{:?}", Items(0)), "<0 items>");
    assert_eq!(format!("{:?}", Items(3)), "<3 items>");
    assert_eq!(format!("{:#?}", Items(3)), "<3 items>");
}

#[test]
fn presence_distinguishes_absent_from_present_without_a_size() {
    assert_eq!(format!("{:?}", Presence(true)), "<present>");
    assert_eq!(format!("{:?}", Presence(false)), "<absent>");
    assert_eq!(format!("{:#?}", Presence(true)), "<present>");
}

#[test]
fn locked_names_the_lock_this_debug_refused_to_wait_for() {
    assert_eq!(format!("{:?}", Locked), "<locked>");
    assert_eq!(format!("{:#?}", Locked), "<locked>");
}

#[test]
fn the_token_scanner_sees_every_marker_and_survives_an_unclosed_one() {
    assert_eq!(
        tokens("text: <4 bytes>, raw: <absent>"),
        ["<4 bytes>", "<absent>"]
    );
    assert_eq!(tokens("nothing here"), Vec::<&str>::new());
    assert_eq!(tokens("<3 items> then <oops"), ["<3 items>"]);
}

#[test]
fn assert_redacted_accepts_a_value_that_hides_its_content() {
    assert_redacted(&Bytes(SECRET.len()));
    assert_redacted(&Presence(true));
    assert_states(&Bytes(7), &["<7 bytes>"]);
}