1use std::collections::BTreeSet;
10
11use serde::{Deserialize, Serialize};
12
13pub const COVERAGE_CONTRACT_SCHEMA_VERSION: u32 = 1;
15pub const COVERAGE_REPORT_SCHEMA_VERSION: u32 = 1;
17
18#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
20pub struct CoverageContractV1 {
21 pub schema_version: u32,
23 pub target: String,
25 pub revision: String,
27 pub surfaces: Vec<CoverageSurfaceV1>,
29 pub transitions: Vec<CoverageTransitionV1>,
31 #[serde(default)]
33 pub exclusions: Vec<CoverageExclusionV1>,
34}
35
36#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
38pub struct CoverageSurfaceV1 {
39 pub id: String,
41 pub platform: String,
43 pub required: bool,
45 pub description: String,
47}
48
49#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
51pub struct CoverageTransitionV1 {
52 pub id: String,
54 pub from: String,
56 pub action: String,
58 pub to: String,
60 pub platform: String,
62 pub required: bool,
64}
65
66#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
68pub struct CoverageExclusionV1 {
69 pub id: String,
71 pub reason: String,
73 pub owner: String,
75 pub review_after: String,
77}
78
79#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
81pub struct CoverageReportV1 {
82 pub schema_version: u32,
84 pub contract_sha256: String,
86 pub planned_ids: Vec<String>,
88 pub executed_ids: Vec<String>,
90 pub passed_ids: Vec<String>,
92 #[serde(default)]
94 pub failed_ids: Vec<String>,
95 #[serde(default)]
97 pub blocked_ids: Vec<String>,
98}
99
100impl CoverageContractV1 {
101 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 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 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 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}