Skip to main content

visual_rubric/
coverage.rs

1//! Shared semantic coverage contracts for autonomous visual QA.
2//!
3//! A producer owns the vocabulary of visible surfaces and interaction
4//! transitions.  The controller only consumes this versioned contract and
5//! proves that every required identifier was executed and evaluated.  Keeping
6//! this data model in the rubric crate prevents project-specific registries
7//! from becoming disconnected, false-green bookkeeping.
8
9use std::collections::BTreeSet;
10
11use serde::{Deserialize, Serialize};
12
13/// Current semantic coverage-contract schema version.
14pub const COVERAGE_CONTRACT_SCHEMA_VERSION: u32 = 1;
15/// Current semantic coverage-report schema version.
16pub const COVERAGE_REPORT_SCHEMA_VERSION: u32 = 1;
17
18/// A complete producer-owned inventory of semantic UI and interaction work.
19#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
20pub struct CoverageContractV1 {
21    /// Schema discriminator.
22    pub schema_version: u32,
23    /// Stable visual target identifier.
24    pub target: String,
25    /// Source revision used to create the contract.
26    pub revision: String,
27    /// Visible semantic surfaces that must be observed.
28    pub surfaces: Vec<CoverageSurfaceV1>,
29    /// User actions and state transitions that must be exercised.
30    pub transitions: Vec<CoverageTransitionV1>,
31    /// Explicitly excluded work, with an accountable owner and expiry.
32    #[serde(default)]
33    pub exclusions: Vec<CoverageExclusionV1>,
34}
35
36/// One visible semantic surface in the coverage contract.
37#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
38pub struct CoverageSurfaceV1 {
39    /// Stable producer-owned surface identifier.
40    pub id: String,
41    /// Platform scope, for example `portable`, `steam_desktop`, or `android`.
42    pub platform: String,
43    /// Whether this surface is required for a complete pass.
44    pub required: bool,
45    /// Human-readable description of the visible state.
46    pub description: String,
47}
48
49/// One semantic interaction transition in the coverage contract.
50#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
51pub struct CoverageTransitionV1 {
52    /// Stable producer-owned transition identifier.
53    pub id: String,
54    /// Surface before the action, or an empty string for an external entry.
55    pub from: String,
56    /// Stable action identifier.
57    pub action: String,
58    /// Surface after the action, or an empty string for an external exit.
59    pub to: String,
60    /// Platform scope on which the transition is supported.
61    pub platform: String,
62    /// Whether this transition is required for a complete pass.
63    pub required: bool,
64}
65
66/// A time-bounded exclusion from the semantic coverage contract.
67#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
68pub struct CoverageExclusionV1 {
69    /// Stable exclusion identifier.
70    pub id: String,
71    /// Why the item cannot be covered yet.
72    pub reason: String,
73    /// Person or team accountable for removing the exclusion.
74    pub owner: String,
75    /// ISO-8601 calendar date after which the exclusion is invalid.
76    pub review_after: String,
77}
78
79/// Deterministic execution result for a coverage contract.
80#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
81pub struct CoverageReportV1 {
82    /// Schema discriminator.
83    pub schema_version: u32,
84    /// SHA-256 of the canonical contract JSON.
85    pub contract_sha256: String,
86    /// Required IDs planned by the producer.
87    pub planned_ids: Vec<String>,
88    /// IDs for which a journey actually executed.
89    pub executed_ids: Vec<String>,
90    /// IDs whose deterministic and semantic checks passed.
91    pub passed_ids: Vec<String>,
92    /// IDs that executed and produced a failure.
93    #[serde(default)]
94    pub failed_ids: Vec<String>,
95    /// IDs that could not execute because required infrastructure was absent.
96    #[serde(default)]
97    pub blocked_ids: Vec<String>,
98}
99
100impl CoverageContractV1 {
101    /// Returns all required surface and transition identifiers in stable order.
102    pub fn required_ids(&self) -> Vec<String> {
103        self.surfaces
104            .iter()
105            .filter(|surface| surface.required)
106            .map(|surface| surface.id.clone())
107            .chain(
108                self.transitions
109                    .iter()
110                    .filter(|transition| transition.required)
111                    .map(|transition| transition.id.clone()),
112            )
113            .collect()
114    }
115
116    /// Validates the contract without requiring filesystem access.
117    pub fn validate(&self) -> Result<(), Vec<String>> {
118        let mut issues = Vec::new();
119        if self.schema_version != COVERAGE_CONTRACT_SCHEMA_VERSION {
120            issues.push(format!(
121                "unsupported coverage contract schema_version {}; expected {}",
122                self.schema_version, COVERAGE_CONTRACT_SCHEMA_VERSION
123            ));
124        }
125        required("target", &self.target, &mut issues);
126        required("revision", &self.revision, &mut issues);
127        if self.surfaces.is_empty() {
128            issues.push("coverage contract must contain at least one surface".to_owned());
129        }
130        if self.transitions.is_empty() {
131            issues.push("coverage contract must contain at least one transition".to_owned());
132        }
133
134        let surface_ids = unique_ids(
135            self.surfaces.iter().map(|surface| surface.id.as_str()),
136            "surface",
137            &mut issues,
138        );
139        unique_ids(
140            self.transitions
141                .iter()
142                .map(|transition| transition.id.as_str()),
143            "transition",
144            &mut issues,
145        );
146        unique_ids(
147            self.surfaces
148                .iter()
149                .map(|surface| surface.id.as_str())
150                .chain(
151                    self.transitions
152                        .iter()
153                        .map(|transition| transition.id.as_str()),
154                ),
155            "contract",
156            &mut issues,
157        );
158        for surface in &self.surfaces {
159            required("surface.id", &surface.id, &mut issues);
160            required("surface.platform", &surface.platform, &mut issues);
161            required("surface.description", &surface.description, &mut issues);
162        }
163        for transition in &self.transitions {
164            required("transition.id", &transition.id, &mut issues);
165            required("transition.action", &transition.action, &mut issues);
166            required("transition.platform", &transition.platform, &mut issues);
167            if !transition.from.is_empty() && !surface_ids.contains(transition.from.as_str()) {
168                issues.push(format!(
169                    "transition {:?} references unknown from surface {:?}",
170                    transition.id, transition.from
171                ));
172            }
173            if !transition.to.is_empty() && !surface_ids.contains(transition.to.as_str()) {
174                issues.push(format!(
175                    "transition {:?} references unknown to surface {:?}",
176                    transition.id, transition.to
177                ));
178            }
179        }
180        for exclusion in &self.exclusions {
181            required("exclusion.id", &exclusion.id, &mut issues);
182            required("exclusion.reason", &exclusion.reason, &mut issues);
183            required("exclusion.owner", &exclusion.owner, &mut issues);
184            if !is_iso_date(&exclusion.review_after) {
185                issues.push(format!(
186                    "exclusion {:?} review_after must be YYYY-MM-DD",
187                    exclusion.id
188                ));
189            }
190        }
191        if issues.is_empty() {
192            Ok(())
193        } else {
194            Err(issues)
195        }
196    }
197}
198
199impl CoverageReportV1 {
200    /// Validates execution accounting against a coverage contract.
201    pub fn validate_against(&self, contract: &CoverageContractV1) -> Result<(), Vec<String>> {
202        let mut issues = Vec::new();
203        if self.schema_version != COVERAGE_REPORT_SCHEMA_VERSION {
204            issues.push(format!(
205                "unsupported coverage report schema_version {}; expected {}",
206                self.schema_version, COVERAGE_REPORT_SCHEMA_VERSION
207            ));
208        }
209        if self.contract_sha256.len() != 64
210            || !self
211                .contract_sha256
212                .bytes()
213                .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
214        {
215            issues.push("coverage report contract_sha256 must be lowercase SHA-256".to_owned());
216        }
217        let required = contract.required_ids().into_iter().collect::<BTreeSet<_>>();
218        let planned = unique_set("planned", &self.planned_ids, &mut issues);
219        let executed = unique_set("executed", &self.executed_ids, &mut issues);
220        let passed = unique_set("passed", &self.passed_ids, &mut issues);
221        let failed = unique_set("failed", &self.failed_ids, &mut issues);
222        let blocked = unique_set("blocked", &self.blocked_ids, &mut issues);
223        if planned != required {
224            issues.push("planned coverage IDs do not match required contract IDs".to_owned());
225        }
226        if !executed.is_subset(&planned) {
227            issues.push("executed coverage IDs must be planned IDs".to_owned());
228        }
229        if !passed.is_subset(&executed) {
230            issues.push("passed coverage IDs must be executed IDs".to_owned());
231        }
232        if !failed.is_subset(&executed) {
233            issues.push("failed coverage IDs must be executed IDs".to_owned());
234        }
235        if !blocked.is_subset(&planned) {
236            issues.push("blocked coverage IDs must be planned IDs".to_owned());
237        }
238        if !passed.is_disjoint(&failed)
239            || !passed.is_disjoint(&blocked)
240            || !failed.is_disjoint(&blocked)
241        {
242            issues.push("passed, failed, and blocked coverage IDs must be disjoint".to_owned());
243        }
244        if passed.len() + failed.len() != executed.len() {
245            issues.push("every executed coverage ID must be exactly passed or failed".to_owned());
246        }
247        let mut accounted = executed.clone();
248        accounted.extend(blocked.iter().cloned());
249        if accounted != planned {
250            issues.push("every planned coverage ID must be exactly executed or blocked".to_owned());
251        }
252        if issues.is_empty() {
253            Ok(())
254        } else {
255            Err(issues)
256        }
257    }
258
259    /// Returns true only when every required item executed and passed.
260    pub fn is_complete_pass(&self, contract: &CoverageContractV1) -> bool {
261        self.validate_against(contract).is_ok()
262            && self.executed_ids.len() == self.passed_ids.len()
263            && self.blocked_ids.is_empty()
264            && self.failed_ids.is_empty()
265    }
266}
267
268fn unique_ids<'a>(
269    ids: impl Iterator<Item = &'a str>,
270    kind: &str,
271    issues: &mut Vec<String>,
272) -> BTreeSet<String> {
273    let mut result = BTreeSet::new();
274    for id in ids {
275        if !result.insert(id.to_owned()) {
276            issues.push(format!("duplicate {kind} id {id:?}"));
277        }
278    }
279    result
280}
281
282fn unique_set(kind: &str, ids: &[String], issues: &mut Vec<String>) -> BTreeSet<String> {
283    let mut result = BTreeSet::new();
284    for id in ids {
285        if id.trim().is_empty() {
286            issues.push(format!("{kind} coverage IDs must not be empty"));
287        }
288        if !result.insert(id.clone()) {
289            issues.push(format!("duplicate {kind} coverage ID {id:?}"));
290        }
291    }
292    result
293}
294
295fn required(name: &str, value: &str, issues: &mut Vec<String>) {
296    if value.trim().is_empty() {
297        issues.push(format!("{name} must not be empty"));
298    }
299}
300
301fn is_iso_date(value: &str) -> bool {
302    let bytes = value.as_bytes();
303    bytes.len() == 10
304        && bytes[4] == b'-'
305        && bytes[7] == b'-'
306        && bytes
307            .iter()
308            .enumerate()
309            .all(|(index, byte)| matches!(index, 4 | 7) || byte.is_ascii_digit())
310}
311
312#[cfg(test)]
313mod tests {
314    use super::*;
315
316    fn contract() -> CoverageContractV1 {
317        CoverageContractV1 {
318            schema_version: COVERAGE_CONTRACT_SCHEMA_VERSION,
319            target: "demo/game".to_owned(),
320            revision: "abc123".to_owned(),
321            surfaces: vec![
322                CoverageSurfaceV1 {
323                    id: "menu".to_owned(),
324                    platform: "portable".to_owned(),
325                    required: true,
326                    description: "Main menu".to_owned(),
327                },
328                CoverageSurfaceV1 {
329                    id: "lobby".to_owned(),
330                    platform: "portable".to_owned(),
331                    required: true,
332                    description: "Lobby".to_owned(),
333                },
334            ],
335            transitions: vec![CoverageTransitionV1 {
336                id: "menu_to_lobby".to_owned(),
337                from: "menu".to_owned(),
338                action: "start".to_owned(),
339                to: "lobby".to_owned(),
340                platform: "portable".to_owned(),
341                required: true,
342            }],
343            exclusions: vec![],
344        }
345    }
346
347    #[test]
348    fn rejects_unknown_transition_surfaces() {
349        let mut value = contract();
350        value.transitions[0].to = "missing".to_owned();
351        assert!(value.validate().is_err());
352    }
353
354    #[test]
355    fn rejects_surface_and_transition_id_collisions() {
356        let mut value = contract();
357        value.transitions[0].id = value.surfaces[0].id.clone();
358        assert!(value.validate().is_err());
359    }
360
361    #[test]
362    fn requires_exact_execution_accounting() {
363        let value = contract();
364        let report = CoverageReportV1 {
365            schema_version: COVERAGE_REPORT_SCHEMA_VERSION,
366            contract_sha256: "a".repeat(64),
367            planned_ids: value.required_ids(),
368            executed_ids: value.required_ids(),
369            passed_ids: value.required_ids(),
370            failed_ids: vec![],
371            blocked_ids: vec![],
372        };
373        assert!(report.validate_against(&value).is_ok());
374        assert!(report.is_complete_pass(&value));
375    }
376
377    #[test]
378    fn rejects_unclassified_execution() {
379        let value = contract();
380        let report = CoverageReportV1 {
381            schema_version: COVERAGE_REPORT_SCHEMA_VERSION,
382            contract_sha256: "a".repeat(64),
383            planned_ids: value.required_ids(),
384            executed_ids: value.required_ids(),
385            passed_ids: vec!["menu".to_owned()],
386            failed_ids: vec![],
387            blocked_ids: vec![],
388        };
389        assert!(report.validate_against(&value).is_err());
390    }
391
392    #[test]
393    fn allows_explicit_blocked_planned_ids_without_calling_them_executed() {
394        let value = contract();
395        let required = value.required_ids();
396        let report = CoverageReportV1 {
397            schema_version: COVERAGE_REPORT_SCHEMA_VERSION,
398            contract_sha256: "a".repeat(64),
399            planned_ids: required.clone(),
400            executed_ids: vec![required[0].clone()],
401            passed_ids: vec![required[0].clone()],
402            failed_ids: vec![],
403            blocked_ids: required.into_iter().skip(1).collect(),
404        };
405        assert!(report.validate_against(&value).is_ok());
406        assert!(!report.is_complete_pass(&value));
407    }
408}