effect-signature 0.1.0

Stable check effect signature types and hashing helpers
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

//! # effect-signature
//!
//! Stable effect payloads and hashing helpers for check outputs.
//!
//! This crate owns the normalized signature types that let execution results be
//! compared, attributed, and persisted across the Forge lane. It does not own
//! check execution or causal graph policy.

//! # effect-signature
//!
//! Shared effect identity types for internal verification flows.
//!
//! This Tier 3 crate keeps one narrow schema for observed check effects so
//! runners, attribution, and storage code do not fork their own effect models.

use std::path::PathBuf;

#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct EffectSignature {
    pub check_kind: String,
    pub outcome: String,
    pub severity: String,
    pub message_class: String,
    pub line_offset_from_edit: Option<i32>,
}

#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct LocatedEffect {
    pub file: Option<PathBuf>,
    pub line: Option<u32>,
    pub col: Option<u32>,
    pub message: String,
    pub sig: EffectSignature,
}

pub fn effect_signature_hash(signature: &EffectSignature) -> String {
    let payload = serde_json::to_vec(signature).unwrap_or_default();
    blake3::hash(&payload).to_hex().to_string()
}

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

    fn sample_signature() -> EffectSignature {
        EffectSignature {
            check_kind: "clippy".into(),
            outcome: "fail".into(),
            severity: "warning".into(),
            message_class: "unused_variable".into(),
            line_offset_from_edit: Some(2),
        }
    }

    #[test]
    fn effect_signature_hash_is_deterministic_and_sensitive_to_fields() {
        let baseline = sample_signature();
        let same_hash = effect_signature_hash(&baseline);
        assert_eq!(same_hash, effect_signature_hash(&baseline));

        let mut changed = baseline.clone();
        changed.message_class = "different".into();
        assert_ne!(same_hash, effect_signature_hash(&changed));
    }

    #[test]
    fn located_effect_round_trips_through_json() {
        let located = LocatedEffect {
            file: Some(PathBuf::from("src/lib.rs")),
            line: Some(12),
            col: Some(4),
            message: "unused variable".into(),
            sig: sample_signature(),
        };

        let encoded = serde_json::to_string(&located).unwrap();
        let decoded: LocatedEffect = serde_json::from_str(&encoded).unwrap();
        assert_eq!(decoded, located);
    }
}

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

    fn sample_signature() -> EffectSignature {
        EffectSignature {
            check_kind: "clippy".into(),
            outcome: "warning".into(),
            severity: "medium".into(),
            message_class: "lint".into(),
            line_offset_from_edit: Some(2),
        }
    }

    #[test]
    fn located_effect_round_trips_through_json() {
        let effect = LocatedEffect {
            file: Some("src/lib.rs".into()),
            line: Some(12),
            col: Some(4),
            message: "unused variable".into(),
            sig: sample_signature(),
        };

        let encoded = serde_json::to_string(&effect).unwrap();
        let decoded: LocatedEffect = serde_json::from_str(&encoded).unwrap();

        assert_eq!(decoded, effect);
    }

    #[test]
    fn hash_is_stable_for_identical_signatures() {
        let left = sample_signature();
        let right = sample_signature();

        assert_eq!(effect_signature_hash(&left), effect_signature_hash(&right));
    }

    #[test]
    fn hash_changes_when_signature_changes() {
        let baseline = sample_signature();
        let mut changed = sample_signature();
        changed.message_class = "type_mismatch".into();

        assert_ne!(
            effect_signature_hash(&baseline),
            effect_signature_hash(&changed)
        );
    }
}