Skip to main content

oscyl_conformance/
lib.rs

1//! Conformance suite for Oscyl synth drivers.
2//!
3//! Every driver calls [`run`] from its own `tests/conformance.rs`, against
4//! its own simulator. A failure panics with `"<driver id>: <check>: <what>"`.
5
6pub mod pump;
7
8use oscyl_driver::{
9    Control, Curation, Driver, DriverError, DriverSession, LibProgram, LibraryData, Macros,
10    Mutability, Page, Palette, Recipe, SessionEvent, SessionOp, Simulator,
11};
12
13use oscyl_driver::sysex::DEVICE_INQUIRY;
14use pump::{run_until_idle, settle};
15
16/// Every check, in order.
17pub fn run(driver: &dyn Driver) {
18    init_program(driver);
19    fields(driver);
20    names(driver);
21    wrong_length_programs(driver);
22    rejects_bad_targets(driver);
23    file_formats_round_trip(driver);
24    write_then_read_back(driver);
25    audition(driver);
26    progress(driver);
27    faults_never_report_false_success(driver);
28    lost_replies_fail(driver);
29    curation_covers_every_field(driver);
30    formats_every_value(driver);
31    generation_is_deterministic_and_valid(driver);
32    live_messages_are_well_formed(driver);
33    presentation_is_consistent(driver);
34    recognizes_its_simulator(driver);
35    app_hooks(driver);
36}
37
38macro_rules! check {
39    ($d:expr, $check:literal, $cond:expr, $($what:tt)+) => {
40        assert!($cond, "{}: {}: {}", $d.info().id, $check, format!($($what)+))
41    };
42}
43
44pub fn init_program(d: &dyn Driver) {
45    let p = d.init_program();
46    check!(
47        d,
48        "init_program",
49        d.check_program(&p).is_ok(),
50        "init program is invalid"
51    );
52    let name = d.name(&p).unwrap_or_default();
53    let allowed = d.name_rules().allowed;
54    check!(
55        d,
56        "init_program",
57        !name.is_empty() && name.chars().all(allowed),
58        "init name {name:?} empty or not allowed"
59    );
60}
61
62pub fn fields(d: &dyn Driver) {
63    let base = d.init_program();
64    for (i, f) in d.fields().iter().enumerate() {
65        for v in [f.min, f.max] {
66            let mut p = base.clone();
67            let set = d.set(&mut p, i, v);
68            check!(d, "fields", set.is_ok(), "{} = {v}: {set:?}", f.name);
69            check!(
70                d,
71                "fields",
72                d.get(&p, i) == Ok(v),
73                "{} reads back wrong",
74                f.name
75            );
76            for (j, g) in d.fields().iter().enumerate().filter(|(j, _)| *j != i) {
77                check!(
78                    d,
79                    "fields",
80                    d.get(&p, j) == d.get(&base, j),
81                    "setting {} changed {}",
82                    f.name,
83                    g.name
84                );
85            }
86        }
87        let mut p = base.clone();
88        if f.max < u16::MAX {
89            check!(
90                d,
91                "fields",
92                d.set(&mut p, i, f.max + 1).is_err(),
93                "{} accepts max + 1",
94                f.name
95            );
96        }
97        if f.min > 0 {
98            check!(
99                d,
100                "fields",
101                d.set(&mut p, i, f.min - 1).is_err(),
102                "{} accepts min - 1",
103                f.name
104            );
105        }
106    }
107}
108
109/// A name of `len` allowed characters.
110fn name_of(d: &dyn Driver, len: usize) -> String {
111    let allowed = d.name_rules().allowed;
112    let pool: Vec<char> = ('A'..='Z')
113        .chain('0'..='9')
114        .filter(|c| allowed(*c))
115        .collect();
116    assert!(
117        !pool.is_empty(),
118        "{}: names: no letters or digits allowed",
119        d.info().id
120    );
121    (0..len).map(|i| pool[i % pool.len()]).collect()
122}
123
124pub fn names(d: &dyn Driver) {
125    let max = d.name_rules().max_len;
126    let mut p = d.init_program();
127    let name = name_of(d, max);
128    check!(
129        d,
130        "names",
131        d.set_name(&mut p, &name).is_ok(),
132        "{max}-char name rejected"
133    );
134    check!(
135        d,
136        "names",
137        d.name(&p).as_deref() == Ok(name.as_str()),
138        "name does not read back"
139    );
140    check!(
141        d,
142        "names",
143        d.set_name(&mut p, &name_of(d, max + 1)).is_err(),
144        "{}-char name accepted",
145        max + 1
146    );
147}
148
149/// First, second and last slot of every writable bank, each with a
150/// distinct program named after its slot.
151fn test_programs(d: &dyn Driver) -> Vec<(u16, Vec<u8>)> {
152    let max = d.name_rules().max_len;
153    let mut slots: Vec<u16> = d
154        .capabilities()
155        .banks
156        .iter()
157        .filter(|b| b.writable && b.len > 0)
158        .flat_map(|b| [b.first, b.first + 1.min(b.len - 1), b.first + b.len - 1])
159        .collect();
160    slots.dedup();
161    slots
162        .into_iter()
163        .map(|slot| {
164            let mut p = d.init_program();
165            let name: String = format!("C{slot}").chars().take(max).collect();
166            d.set_name(&mut p, &name)
167                .unwrap_or_else(|e| panic!("{}: test name {name:?}: {e}", d.info().id));
168            (slot, p)
169        })
170        .collect()
171}
172
173fn submit(d: &dyn Driver, s: &mut dyn DriverSession, op: SessionOp, check: &str) {
174    if let Err(e) = s.submit(op) {
175        panic!("{}: {check}: submit failed: {e}", d.info().id);
176    }
177}
178
179pub fn write_then_read_back(d: &dyn Driver) {
180    let (mut s, mut sim) = (d.session(0), d.simulator());
181    let programs = test_programs(d);
182    submit(
183        d,
184        &mut *s,
185        SessionOp::WritePrograms(programs.clone()),
186        "write_then_read_back",
187    );
188    let ev = run_until_idle(&mut *s, &mut *sim, d.info().id);
189    check!(
190        d,
191        "write_then_read_back",
192        ev.last() == Some(&SessionEvent::Done),
193        "write ended {:?}",
194        ev.last()
195    );
196    for (slot, p) in &programs {
197        check!(
198            d,
199            "write_then_read_back",
200            sim.program(*slot).as_ref() == Some(p),
201            "slot {slot} holds wrong data"
202        );
203    }
204    check!(
205        d,
206        "write_then_read_back",
207        sim.is_settled(),
208        "simulator not settled after the write"
209    );
210    let slots: Vec<u16> = programs.iter().map(|(n, _)| *n).collect();
211    submit(
212        d,
213        &mut *s,
214        SessionOp::ReadPrograms(slots),
215        "write_then_read_back",
216    );
217    let ev = run_until_idle(&mut *s, &mut *sim, d.info().id);
218    for (slot, p) in &programs {
219        check!(
220            d,
221            "write_then_read_back",
222            ev.contains(&SessionEvent::Program(*slot, p.clone())),
223            "slot {slot} did not read back"
224        );
225    }
226    check!(
227        d,
228        "write_then_read_back",
229        ev.last() == Some(&SessionEvent::Done),
230        "read ended {:?}",
231        ev.last()
232    );
233}
234
235pub fn audition(d: &dyn Driver) {
236    if !d.capabilities().edit_buffer {
237        return;
238    }
239    let (mut s, mut sim) = (d.session(0), d.simulator());
240    let (_, p) = test_programs(d).swap_remove(0);
241    submit(d, &mut *s, SessionOp::Audition(p.clone()), "audition");
242    let ev = run_until_idle(&mut *s, &mut *sim, d.info().id);
243    check!(
244        d,
245        "audition",
246        ev.last() == Some(&SessionEvent::Done),
247        "audition ended {:?}",
248        ev.last()
249    );
250    check!(
251        d,
252        "audition",
253        sim.edit_buffer() == p,
254        "edit buffer does not hold the program"
255    );
256    submit(d, &mut *s, SessionOp::ReadCurrent, "audition");
257    let ev = run_until_idle(&mut *s, &mut *sim, d.info().id);
258    check!(
259        d,
260        "audition",
261        ev.contains(&SessionEvent::Current(p)),
262        "current program does not read back"
263    );
264    settle(&mut *sim, d.info().id);
265}
266
267pub fn progress(d: &dyn Driver) {
268    let (mut s, mut sim) = (d.session(0), d.simulator());
269    let programs = test_programs(d);
270    let slots = programs.iter().map(|(n, _)| *n).collect();
271    for op in [
272        SessionOp::WritePrograms(programs),
273        SessionOp::ReadPrograms(slots),
274    ] {
275        submit(d, &mut *s, op, "progress");
276        let ev = run_until_idle(&mut *s, &mut *sim, d.info().id);
277        let steps: Vec<(usize, usize)> = ev
278            .iter()
279            .filter_map(|e| match e {
280                SessionEvent::Progress { done, total } => Some((*done, *total)),
281                _ => None,
282            })
283            .collect();
284        let ok = !steps.is_empty()
285            && steps.windows(2).all(|w| w[0].0 < w[1].0)
286            && steps.iter().all(|(_, t)| *t == steps[0].1)
287            && steps.last().is_some_and(|(done, total)| done == total);
288        check!(d, "progress", ok, "progress {steps:?}");
289        let last_progress = ev
290            .iter()
291            .rposition(|e| matches!(e, SessionEvent::Progress { .. }));
292        let done = ev.iter().position(|e| *e == SessionEvent::Done);
293        check!(
294            d,
295            "progress",
296            done > last_progress,
297            "Done before the last progress"
298        );
299    }
300}
301
302/// Did an op end in `Done` (true) or `Failed` (false)? Anything else fails
303/// the check.
304fn ended_done(d: &dyn Driver, ev: &[SessionEvent], fault: &str) -> bool {
305    match ev.last() {
306        Some(SessionEvent::Done) => true,
307        Some(SessionEvent::Failed(_)) => false,
308        other => panic!("{}: faults: {fault}: op ended {other:?}", d.info().id),
309    }
310}
311
312pub fn faults_never_report_false_success(d: &dyn Driver) {
313    for fault in d.simulator().faults() {
314        let (mut s, mut sim): (Box<dyn DriverSession>, Box<dyn Simulator>) =
315            (d.session(0), d.simulator());
316        sim.inject(fault);
317        let programs = test_programs(d);
318        submit(
319            d,
320            &mut *s,
321            SessionOp::WritePrograms(programs.clone()),
322            "faults",
323        );
324        let ev = run_until_idle(&mut *s, &mut *sim, d.info().id);
325        if ended_done(d, &ev, fault) {
326            for (slot, p) in &programs {
327                check!(
328                    d,
329                    "faults",
330                    sim.program(*slot).as_ref() == Some(p),
331                    "{fault}: write reported done but slot {slot} differs"
332                );
333            }
334        }
335        let slots = programs.iter().map(|(n, _)| *n).collect();
336        submit(d, &mut *s, SessionOp::ReadPrograms(slots), "faults");
337        let ev = run_until_idle(&mut *s, &mut *sim, d.info().id);
338        ended_done(d, &ev, fault);
339        for e in &ev {
340            if let SessionEvent::Program(slot, bytes) = e {
341                check!(
342                    d,
343                    "faults",
344                    sim.program(*slot).as_ref() == Some(bytes),
345                    "{fault}: read of slot {slot} returned data the synth does not hold"
346                );
347            }
348        }
349    }
350}
351
352pub fn wrong_length_programs(d: &dyn Driver) {
353    let p = d.init_program();
354    for bad in [&p[..p.len() - 1], &[p.clone(), vec![0]].concat()[..]] {
355        let mut b = bad.to_vec();
356        let n = b.len();
357        check!(
358            d,
359            "wrong_length_programs",
360            d.check_program(&b).is_err(),
361            "{n} bytes pass check_program"
362        );
363        check!(
364            d,
365            "wrong_length_programs",
366            d.get(&b, 0).is_err(),
367            "get accepts {n} bytes"
368        );
369        check!(
370            d,
371            "wrong_length_programs",
372            d.set(&mut b, 0, d.fields()[0].min).is_err(),
373            "set accepts {n} bytes"
374        );
375        check!(
376            d,
377            "wrong_length_programs",
378            d.name(&b).is_err(),
379            "name accepts {n} bytes"
380        );
381        check!(
382            d,
383            "wrong_length_programs",
384            d.set_name(&mut b, "A").is_err(),
385            "set_name accepts {n} bytes"
386        );
387    }
388}
389
390/// Writes to read-only banks or past the last bank, and reads past the
391/// last bank, are refused at `submit` and send nothing.
392pub fn rejects_bad_targets(d: &dyn Driver) {
393    let banks = d.capabilities().banks;
394    let past = banks.iter().map(|b| b.first + b.len).max().unwrap_or(0);
395    let mut writes: Vec<u16> = banks
396        .iter()
397        .filter(|b| !b.writable && b.len > 0)
398        .flat_map(|b| [b.first, b.first + b.len - 1])
399        .collect();
400    writes.push(past);
401    let p = d.init_program();
402    for slot in writes {
403        let mut s = d.session(0);
404        let r = s.submit(SessionOp::WritePrograms(vec![(slot, p.clone())]));
405        check!(
406            d,
407            "rejects_bad_targets",
408            r.is_err(),
409            "write to slot {slot} accepted"
410        );
411        check!(
412            d,
413            "rejects_bad_targets",
414            s.poll_transmit(std::time::Instant::now()).is_none(),
415            "write to slot {slot} sent bytes"
416        );
417    }
418    let mut s = d.session(0);
419    let r = s.submit(SessionOp::ReadPrograms(vec![past]));
420    check!(
421        d,
422        "rejects_bad_targets",
423        r.is_err(),
424        "read of slot {past} accepted"
425    );
426    check!(
427        d,
428        "rejects_bad_targets",
429        s.poll_transmit(std::time::Instant::now()).is_none(),
430        "read of slot {past} sent bytes"
431    );
432}
433
434/// Every simulator offers `lose_reply` (every reply lost). Under it every
435/// op must end `Failed`: a lost reply is never success.
436pub fn lost_replies_fail(d: &dyn Driver) {
437    check!(
438        d,
439        "lost_replies_fail",
440        d.simulator().faults().contains(&"lose_reply"),
441        "simulator has no lose_reply fault"
442    );
443    let (mut s, mut sim) = (d.session(0), d.simulator());
444    sim.inject("lose_reply");
445    let programs = test_programs(d);
446    let slots = programs.iter().map(|(n, _)| *n).collect();
447    let (_, one) = programs[0].clone();
448    let mut ops = vec![
449        SessionOp::WritePrograms(programs),
450        SessionOp::ReadPrograms(slots),
451        SessionOp::ReadCurrent,
452    ];
453    if d.capabilities().edit_buffer {
454        ops.push(SessionOp::Audition(one));
455    }
456    for op in ops {
457        let what = format!("{op:?}").chars().take(24).collect::<String>();
458        submit(d, &mut *s, op, "lost_replies_fail");
459        let ev = run_until_idle(&mut *s, &mut *sim, d.info().id);
460        check!(
461            d,
462            "lost_replies_fail",
463            matches!(ev.last(), Some(SessionEvent::Failed(_))),
464            "{what}… ended {:?}",
465            ev.last()
466        );
467    }
468}
469
470/// The driver names its ports and recognises its simulator's answer to
471/// the device inquiry, but not the inquiry itself (a port looping our
472/// output back).
473pub fn recognizes_its_simulator(d: &dyn Driver) {
474    let hints = d.port_hint();
475    check!(
476        d,
477        "recognizes_its_simulator",
478        !hints.is_empty() && hints.iter().all(|h| !h.is_empty()),
479        "port hints {hints:?} empty"
480    );
481    let replies = d.simulator().handle(&DEVICE_INQUIRY);
482    check!(
483        d,
484        "recognizes_its_simulator",
485        replies.iter().any(|r| d.recognize(r)),
486        "no recognised reply among {replies:02X?}"
487    );
488    check!(
489        d,
490        "recognizes_its_simulator",
491        !d.recognize(&DEVICE_INQUIRY),
492        "the inquiry itself is recognised"
493    );
494    // Byte 2 is the device's channel or 7F; any of them is still the synth.
495    if let Some(reply) = replies.iter().find(|r| d.recognize(r)) {
496        for ch in (0..16).chain([0x7F]) {
497            let mut r = reply.clone();
498            r[2] = ch;
499            check!(
500                d,
501                "recognizes_its_simulator",
502                d.recognize(&r),
503                "reply on channel {ch:#04x} not recognised"
504            );
505        }
506    }
507    // A reply from another vendor (7D: non-commercial id).
508    let foreign = [
509        0xF0, 0x7E, 0x00, 0x06, 0x02, 0x7D, 0x01, 0x02, 0x03, 0x04, 0x00, 0x00, 0x00, 0x00, 0xF7,
510    ];
511    check!(
512        d,
513        "recognizes_its_simulator",
514        !d.recognize(&foreign),
515        "a foreign identity reply is recognised"
516    );
517}
518
519/// Every vendor format gives back the program bytes it was given, and the
520/// author and comment unless it holds none; unknown extensions
521/// are refused.
522pub fn file_formats_round_trip(d: &dyn Driver) {
523    let lib = LibraryData {
524        programs: test_programs(d)
525            .into_iter()
526            .map(|(_, data)| LibProgram {
527                data,
528                author: "A".into(),
529                comment: "C".into(),
530            })
531            .collect(),
532        extras: Default::default(),
533    };
534    for f in d.file_formats() {
535        let bytes = d.export(f.ext, &lib).unwrap_or_else(|e| {
536            panic!(
537                "{}: file_formats_round_trip: export .{}: {e}",
538                d.info().id,
539                f.ext
540            )
541        });
542        let back = d.import(f.ext, &bytes).unwrap_or_else(|e| {
543            panic!(
544                "{}: file_formats_round_trip: import .{}: {e}",
545                d.info().id,
546                f.ext
547            )
548        });
549        // A format declares whether it keeps author and comment: if it
550        // does, they come back exactly; if not, they come back empty.
551        let same = back.programs.len() == lib.programs.len()
552            && back.programs.iter().zip(&lib.programs).all(|(b, p)| {
553                let meta = if f.keeps_metadata {
554                    (b.author.as_str(), b.comment.as_str())
555                        == (p.author.as_str(), p.comment.as_str())
556                } else {
557                    b.author.is_empty() && b.comment.is_empty()
558                };
559                b.data == p.data && meta
560            });
561        check!(
562            d,
563            "file_formats_round_trip",
564            same,
565            ".{} changed the programs",
566            f.ext
567        );
568        let again = d
569            .export(f.ext, &back)
570            .ok()
571            .and_then(|b| d.import(f.ext, &b).ok());
572        check!(
573            d,
574            "file_formats_round_trip",
575            again.as_ref() == Some(&back),
576            ".{} is not stable over a second round trip",
577            f.ext
578        );
579    }
580    check!(
581        d,
582        "file_formats_round_trip",
583        d.import("oscyl-no-such-format", &[]).is_err(),
584        "unknown format accepted"
585    );
586}
587
588/// Every field is in exactly one section or excluded, and what the editor
589/// shows is complete: titles, labels, and controls that fit the field.
590pub fn curation_covers_every_field(d: &dyn Driver) {
591    let c = d.curation();
592    let shape = curation_shape(&c, d.fields().len());
593    check!(d, "curation", shape.is_ok(), "{}", shape.unwrap_err());
594    // Controls may depend on the program: check init and generated ones.
595    let mut programs = vec![d.init_program()];
596    for character in 0..d.characters().len() {
597        let r = Recipe {
598            character,
599            seed: 11,
600            ..Recipe::default()
601        };
602        programs.extend(d.generate(&r, None));
603    }
604    for i in c
605        .pages
606        .iter()
607        .flat_map(|p| &p.sections)
608        .flat_map(|s| &s.fields)
609    {
610        let (i, f) = (*i, &d.fields()[*i]);
611        check!(
612            d,
613            "curation",
614            !d.short_label(i).is_empty(),
615            "{} has no short label",
616            f.name
617        );
618        for p in &programs {
619            let ok = match d.control(p, i) {
620                Control::Toggle => f.max - f.min == 1,
621                Control::Choice(names) => !names.is_empty(),
622                Control::Bands { names, width } => !names.is_empty() && width > 0,
623                Control::Continuous => true,
624            };
625            check!(d, "curation", ok, "{} has an unfit control", f.name);
626        }
627    }
628}
629
630/// Whether `c` lays out `n` fields: at least one page, not every field
631/// excluded (a raw dump or an empty editor is not curation), every index
632/// below `n` and in exactly one section or the excluded list, titles and
633/// sections non-empty.
634pub fn curation_shape(c: &Curation, n: usize) -> Result<(), String> {
635    if c.pages.is_empty() {
636        return Err("no pages".into());
637    }
638    let shown: Vec<usize> = c
639        .pages
640        .iter()
641        .flat_map(|p| &p.sections)
642        .flat_map(|s| s.fields.iter().copied())
643        .collect();
644    if shown.is_empty() {
645        return Err("every field is excluded".into());
646    }
647    let mut seen = vec![0usize; n];
648    for &i in shown.iter().chain(&c.excluded) {
649        *seen
650            .get_mut(i)
651            .ok_or_else(|| format!("field index {i} out of range"))? += 1;
652    }
653    if let Some((i, times)) = seen.iter().enumerate().find(|(_, t)| **t != 1) {
654        return Err(format!("field {i} appears {times} times"));
655    }
656    for p in &c.pages {
657        if p.title.is_empty() || p.sections.is_empty() {
658            return Err(format!("page {:?} is untitled or empty", p.title));
659        }
660        if let Some(s) = p
661            .sections
662            .iter()
663            .find(|s| s.title.is_empty() || s.fields.is_empty())
664        {
665            return Err(format!(
666                "page {}: section {:?} untitled or empty",
667                p.title, s.title
668            ));
669        }
670    }
671    Ok(())
672}
673
674/// Every field formats its minimum and maximum as non-empty text.
675pub fn formats_every_value(d: &dyn Driver) {
676    let base = d.init_program();
677    for (i, f) in d.fields().iter().enumerate() {
678        for v in [f.min, f.max] {
679            let mut p = base.clone();
680            if let Err(e) = d.set(&mut p, i, v) {
681                panic!("{}: formats: {} = {v}: {e}", d.info().id, f.name);
682            }
683            check!(
684                d,
685                "formats",
686                !d.format_value(&p, i).is_empty() && !d.format_raw(i, v).is_empty(),
687                "{} = {v} formats empty",
688                f.name
689            );
690        }
691    }
692}
693
694/// The editor's other data agrees with the curation and the schema:
695/// emphasized fields are shown, labels exist, categories list what
696/// `category` says, signature pages exist, and graphs, handles and drags
697/// stay within the pages and fields.
698pub fn presentation_is_consistent(d: &dyn Driver) {
699    let c = d.curation();
700    let n = d.fields().len();
701    let shown: Vec<usize> = c
702        .pages
703        .iter()
704        .flat_map(|p| &p.sections)
705        .flat_map(|s| s.fields.iter().copied())
706        .collect();
707    let mut programs = vec![d.init_program()];
708    for character in 0..d.characters().len() {
709        let r = Recipe {
710            character,
711            seed: 13,
712            ..Recipe::default()
713        };
714        programs.extend(d.generate(&r, None));
715    }
716    for i in 0..n {
717        let name = d.fields()[i].name;
718        check!(
719            d,
720            "presentation",
721            !d.emphasized(i) || shown.contains(&i),
722            "{name} is emphasized but not shown"
723        );
724        for p in &programs {
725            check!(
726                d,
727                "presentation",
728                !d.label_in(p, i).is_empty() || !shown.contains(&i),
729                "{name} has no label"
730            );
731        }
732    }
733    for p in &programs {
734        if let Some(cat) = d.category(p) {
735            check!(
736                d,
737                "presentation",
738                d.categories().contains(&cat),
739                "category {cat:?} is not in categories()"
740            );
741        }
742        for page in 0..c.pages.len() {
743            d.page_summary(p, page);
744            d.graphs(p, page, 64);
745            for (h, handle) in d.handles(p, page).iter().enumerate() {
746                let ok = [handle.x, handle.y].iter().flatten().all(|&i| i < n)
747                    && !handle.name.is_empty();
748                check!(d, "presentation", ok, "page {page}: bad handle {h}");
749                for (i, v) in d.drag(p, page, h, (0.5, 0.5)) {
750                    let f = d.fields().get(i);
751                    check!(
752                        d,
753                        "presentation",
754                        f.is_some_and(|f| (f.min..=f.max).contains(&v)),
755                        "page {page}: handle {h} drags field {i} to {v}"
756                    );
757                }
758            }
759        }
760    }
761    for ch in d.characters() {
762        check!(
763            d,
764            "presentation",
765            ch.signature_page.is_none_or(|s| s < c.pages.len()),
766            "{}: no signature page {:?}",
767            ch.id,
768            ch.signature_page
769        );
770    }
771    check!(
772        d,
773        "presentation",
774        d.macro_info().iter().all(|m| !m.title.is_empty()),
775        "a macro has no title"
776    );
777}
778
779/// A generated, varied or bred program, checked valid with every field in
780/// range.
781fn valid_generated(d: &dyn Driver, what: &str, p: Result<Vec<u8>, DriverError>) -> Vec<u8> {
782    let p = p.unwrap_or_else(|e| panic!("{}: generation: {what}: {e}", d.info().id));
783    check!(
784        d,
785        "generation",
786        d.check_program(&p).is_ok(),
787        "{what} is invalid"
788    );
789    for (i, f) in d.fields().iter().enumerate() {
790        let v = d.get(&p, i);
791        check!(
792            d,
793            "generation",
794            v.as_ref().is_ok_and(|v| (f.min..=f.max).contains(v)),
795            "{what}: {} = {v:?}",
796            f.name
797        );
798    }
799    p
800}
801
802/// Same recipe, same bytes; every program valid; restricted and fixed
803/// fields keep the base; kept pages come from the base; vary and breed
804/// are deterministic and leave fixed fields alone.
805pub fn generation_is_deterministic_and_valid(d: &dyn Driver) {
806    let init = d.init_program();
807    let pages = d.curation().pages;
808    let not_free: Vec<usize> = (0..d.fields().len())
809        .filter(|&i| d.mutability(i) != Mutability::Free)
810        .collect();
811    let same =
812        |a: &[u8], b: &[u8], fields: &[usize]| fields.iter().all(|&i| d.get(a, i) == d.get(b, i));
813    for character in 0..d.characters().len() {
814        let mut programs = vec![];
815        for seed in [0, 1, 0xDEAD_BEEF] {
816            let r = Recipe {
817                character,
818                seed,
819                ..Recipe::default()
820            };
821            let what = format!("character {character} seed {seed}");
822            let p = valid_generated(d, &what, d.generate(&r, None));
823            check!(
824                d,
825                "generation",
826                d.generate(&r, None).as_ref() == Ok(&p),
827                "{what} is not deterministic"
828            );
829            check!(
830                d,
831                "generation",
832                same(&p, &init, &not_free),
833                "{what} changed a restricted or fixed field"
834            );
835            programs.push(p);
836        }
837        let (a, b) = (&programs[0], &programs[2]);
838        for (what, made, again) in [
839            ("vary", d.vary(a, 0.7, 3), d.vary(a, 0.7, 3)),
840            ("breed", d.breed(a, b, 0.5, 3), d.breed(a, b, 0.5, 3)),
841        ] {
842            let p = valid_generated(d, what, made);
843            check!(
844                d,
845                "generation",
846                again.as_ref() == Ok(&p),
847                "{what} is not deterministic"
848            );
849        }
850        generation_keeps_the_base(d, character, &pages, b);
851        morph_goes_from_a_to_b(d, a, b);
852    }
853}
854
855/// A morph is valid and deterministic, starts at `a`, ends at `b`'s free
856/// fields, and no field turns back on the way.
857fn morph_goes_from_a_to_b(d: &dyn Driver, a: &[u8], b: &[u8]) {
858    let n = d.fields().len();
859    let values = |p: &[u8]| -> Vec<Option<u16>> { (0..n).map(|i| d.get(p, i).ok()).collect() };
860    let steps: Vec<Vec<Option<u16>>> = (0..=10)
861        .map(|k| {
862            let t = k as f32 / 10.0;
863            let p = valid_generated(d, "morph", d.morph(a, b, t, 5));
864            check!(
865                d,
866                "generation",
867                d.morph(a, b, t, 5).as_ref() == Ok(&p),
868                "morph is not deterministic"
869            );
870            values(&p)
871        })
872        .collect();
873    check!(
874        d,
875        "generation",
876        steps[0] == values(a),
877        "morph at 0 is not a"
878    );
879    let end = values(b);
880    for i in 0..n {
881        let name = d.fields()[i].name;
882        if d.mutability(i) == Mutability::Free {
883            check!(
884                d,
885                "generation",
886                steps[10][i] == end[i],
887                "morph at 1: {name} is not b's"
888            );
889        }
890        let (up, down) = steps.windows(2).fold((false, false), |(up, down), w| {
891            (up || w[1][i] > w[0][i], down || w[1][i] < w[0][i])
892        });
893        check!(d, "generation", !(up && down), "morph: {name} turns back");
894    }
895}
896
897/// With a base, every non-free field comes from it and kept pages come
898/// back from it whole; vary keeps every non-free field; breed takes
899/// non-free fields from its first parent. The base has every field at
900/// its maximum, so nothing matches init by accident.
901fn generation_keeps_the_base(d: &dyn Driver, character: usize, pages: &[Page], other: &[u8]) {
902    let mut base = d.init_program();
903    for (i, f) in d.fields().iter().enumerate() {
904        d.set(&mut base, i, f.max).expect("max is in range");
905    }
906    let not_free: Vec<usize> = (0..d.fields().len())
907        .filter(|&i| d.mutability(i) != Mutability::Free)
908        .collect();
909    let differs = |p: &[u8], fields: &[usize]| {
910        fields
911            .iter()
912            .find(|&&i| d.get(p, i) != d.get(&base, i))
913            .map(|&i| d.fields()[i].name)
914    };
915    let keep_page = |keep: Vec<usize>| {
916        let r = Recipe {
917            character,
918            seed: 2,
919            keep,
920            ..Recipe::default()
921        };
922        valid_generated(d, "generate with a base", d.generate(&r, Some(&base)))
923    };
924    let p = keep_page(vec![]);
925    let bad = differs(&p, &not_free);
926    check!(
927        d,
928        "generation",
929        bad.is_none(),
930        "generate with a base changed non-free {bad:?}"
931    );
932    if let Some(page) = pages.first() {
933        let mut fields: Vec<usize> = page
934            .sections
935            .iter()
936            .flat_map(|s| s.fields.iter().copied())
937            .collect();
938        fields.extend(&not_free);
939        let bad = differs(&keep_page(vec![0]), &fields);
940        check!(
941            d,
942            "generation",
943            bad.is_none(),
944            "page {} not kept: {bad:?}",
945            page.title
946        );
947    }
948    for (what, made) in [
949        ("vary", d.vary(&base, 0.9, 4)),
950        ("breed", d.breed(&base, other, 0.9, 4)),
951    ] {
952        let p = valid_generated(d, what, made);
953        let bad = differs(&p, &not_free);
954        check!(
955            d,
956            "generation",
957            bad.is_none(),
958            "{what} changed non-free {bad:?}"
959        );
960    }
961}
962
963/// What a driver's generated sounds must be beyond valid, by its own
964/// rules.
965pub struct Quality<'a> {
966    /// The program makes a sound a player hears.
967    pub audible: &'a dyn Fn(&[u8]) -> bool,
968    /// The program stays at or under the driver's level cap.
969    pub level_capped: &'a dyn Fn(&[u8]) -> bool,
970    /// The fewest fields any two sounds of a dealt hand differ in.
971    pub min_spread: usize,
972}
973
974/// The quality gate: every character, at 200 seeds and at every corner of
975/// the four macros (each at 0, 0.5 and 1), generates a valid, audible
976/// program at or under the level cap; and the six sounds of a dealt hand
977/// differ pairwise in at least `min_spread` fields, so a hand is never
978/// six of nearly the same sound. Each seed takes one corner, so the 81
979/// corners come round more than twice per character.
980pub fn generated_sounds_are_good(d: &dyn Driver, q: &Quality) {
981    const STEPS: [f32; 3] = [0.0, 0.5, 1.0];
982    let corner = |k: usize| Macros {
983        bright: STEPS[k % 3],
984        movement: STEPS[k / 3 % 3],
985        grit: STEPS[k / 9 % 3],
986        space: STEPS[k / 27 % 3],
987    };
988    // Only free fields can differ.
989    let free: Vec<usize> = (0..d.fields().len())
990        .filter(|&i| d.mutability(i) == Mutability::Free)
991        .collect();
992    for (character, ch) in d.characters().iter().enumerate() {
993        let recipe = |seed: u64, k: usize| Recipe {
994            character,
995            macros: corner(k),
996            seed,
997            ..Recipe::default()
998        };
999        for seed in 0..200u64 {
1000            let k = seed as usize + character;
1001            let what = format!("{} seed {seed} corner {}", ch.id, k % 81);
1002            let p = valid_generated(d, &what, d.generate(&recipe(seed, k), None));
1003            check!(d, "quality", (q.audible)(&p), "{what} is not audible");
1004            check!(d, "quality", (q.level_capped)(&p), "{what} is too loud");
1005        }
1006        // Hands at the middle of the macros and at their corners.
1007        for deal in 0..24usize {
1008            let k = if deal < 8 { 40 } else { deal * 5 };
1009            let hand = oscyl_core::generate::hand(d, character, deal as u64, 6, |s| {
1010                d.generate(&recipe(s, k), None)
1011            })
1012            .unwrap_or_else(|e| panic!("{}: quality: {}: {e}", d.info().id, ch.id));
1013            for (i, a) in hand.iter().enumerate() {
1014                for b in &hand[i + 1..] {
1015                    let spread = free.iter().filter(|&&f| d.get(a, f) != d.get(b, f)).count();
1016                    check!(
1017                        d,
1018                        "quality",
1019                        spread >= q.min_spread,
1020                        "{} deal {deal}: two sounds differ in only {spread} fields",
1021                        ch.id
1022                    );
1023                }
1024            }
1025        }
1026    }
1027    generated_sounds_use_units_well(d, q);
1028}
1029
1030/// The palettes the quality gate deals with on a synth that takes user
1031/// units: one oscillator (the first kind), then a unit of every kind in
1032/// its last slot. The oscillator declares a parameter of each kind.
1033fn gate_palettes(d: &dyn Driver) -> Vec<Palette> {
1034    use oscyl_driver::{PaletteUnit, UnitParam, UnitParamKind as K};
1035    let param = |name: &str, min, max, kind| UnitParam {
1036        name: name.into(),
1037        min,
1038        max,
1039        kind,
1040    };
1041    let unit = |kind: &oscyl_driver::UnitKind, slot| PaletteUnit {
1042        kind: *kind,
1043        slot,
1044        name: format!("Test {}", kind.name),
1045        params: Some(vec![
1046            param("Wave", 0, 45, K::Choice),
1047            param("Mix", 20, 80, K::Percent),
1048            param("Tilt", -30, 60, K::Bipolar),
1049        ]),
1050    };
1051    let kinds = d.capabilities().units;
1052    let Some(first) = kinds.first() else {
1053        return vec![];
1054    };
1055    vec![
1056        Palette {
1057            units: vec![unit(first, 0)],
1058        },
1059        Palette {
1060            units: kinds.iter().map(|k| unit(k, k.slots - 1)).collect(),
1061        },
1062    ]
1063}
1064
1065/// The quality gate with user units: with a palette, every sound is still
1066/// valid, audible and capped and relies only on slots the palette names;
1067/// with a unit of every kind, every sound uses one; and a variation, a
1068/// child or a morph step of such sounds selects no slot the palette lacks.
1069fn generated_sounds_use_units_well(d: &dyn Driver, q: &Quality) {
1070    let palettes = gate_palettes(d);
1071    for (n, palette) in palettes.iter().enumerate() {
1072        let named = |p: &[u8], what: &str| {
1073            let stray = d.needs(p).into_iter().find(|(kind, slot)| {
1074                !palette
1075                    .units
1076                    .iter()
1077                    .any(|u| u.kind == *kind && u.slot == *slot)
1078            });
1079            check!(
1080                d,
1081                "quality",
1082                stray.is_none(),
1083                "{what} needs {stray:?}, which the palette lacks"
1084            );
1085        };
1086        for (character, ch) in d.characters().iter().enumerate() {
1087            let make = |seed: u64| {
1088                let r = Recipe {
1089                    character,
1090                    seed,
1091                    palette: palette.clone(),
1092                    ..Recipe::default()
1093                };
1094                let what = format!("{} seed {seed} palette {n}", ch.id);
1095                let p = valid_generated(d, &what, d.generate(&r, None));
1096                check!(d, "quality", (q.audible)(&p), "{what} is not audible");
1097                check!(d, "quality", (q.level_capped)(&p), "{what} is too loud");
1098                named(&p, &what);
1099                check!(
1100                    d,
1101                    "quality",
1102                    d.generate(&r, None).as_ref() == Ok(&p),
1103                    "{what} is not deterministic"
1104                );
1105                p
1106            };
1107            let mut before: Option<Vec<u8>> = None;
1108            for seed in 0..40u64 {
1109                let p = make(seed);
1110                if n + 1 == palettes.len() {
1111                    check!(
1112                        d,
1113                        "quality",
1114                        !d.needs(&p).is_empty(),
1115                        "{} seed {seed}: no unit used though every kind is there",
1116                        ch.id
1117                    );
1118                }
1119                if let Some(a) = before.filter(|_| seed % 8 == 0) {
1120                    for (what, made) in [
1121                        ("vary", d.vary(&p, 0.9, seed)),
1122                        ("breed", d.breed(&a, &p, 0.5, seed)),
1123                        ("morph", d.morph(&a, &p, 0.5, seed)),
1124                    ] {
1125                        let child = valid_generated(d, what, made);
1126                        named(&child, what);
1127                    }
1128                }
1129                before = Some(p);
1130            }
1131        }
1132    }
1133}
1134
1135/// Exactly one complete channel-voice message on `channel`: a status byte
1136/// and its data bytes (1 for program change and channel pressure, else 2),
1137/// each below 0x80.
1138pub fn well_formed(msg: &[u8], channel: u8) -> bool {
1139    let Some((&status, data)) = msg.split_first() else {
1140        return false;
1141    };
1142    let n = match status & 0xF0 {
1143        0xC0 | 0xD0 => 1,
1144        _ => 2,
1145    };
1146    (0x80..0xF0).contains(&status)
1147        && status & 0x0F == channel
1148        && data.len() == n
1149        && data.iter().all(|b| *b < 0x80)
1150}
1151
1152/// Live messages exist exactly when the synth takes live changes, and
1153/// each is complete channel-voice MIDI on the channel asked for.
1154pub fn live_messages_are_well_formed(d: &dyn Driver) {
1155    const CH: u8 = 5;
1156    let base = d.init_program();
1157    let mut any = false;
1158    for (i, f) in d.fields().iter().enumerate() {
1159        for v in [f.min, f.max] {
1160            let mut p = base.clone();
1161            if let Err(e) = d.set(&mut p, i, v) {
1162                panic!("{}: live_messages: {} = {v}: {e}", d.info().id, f.name);
1163            }
1164            let Some(bytes) = d.live_messages(&p, i, CH) else {
1165                continue;
1166            };
1167            any = true;
1168            check!(
1169                d,
1170                "live_messages",
1171                d.capabilities().live_changes,
1172                "{} has live messages but live_changes is false",
1173                f.name
1174            );
1175            check!(
1176                d,
1177                "live_messages",
1178                !bytes.is_empty(),
1179                "{} = {v}: empty",
1180                f.name
1181            );
1182            for msg in &bytes {
1183                check!(
1184                    d,
1185                    "live_messages",
1186                    well_formed(msg, CH),
1187                    "{} = {v}: not one channel message {msg:02X?}",
1188                    f.name
1189                );
1190            }
1191        }
1192    }
1193    check!(
1194        d,
1195        "live_messages",
1196        any || !d.capabilities().live_changes,
1197        "live_changes is true but no field has a live message"
1198    );
1199}
1200
1201/// The hooks apps show around the editor: the demo library holds valid
1202/// programs that fit the writable slots, the demo simulator answers the
1203/// device inquiry as the driver's synth, the list facet is an in-range
1204/// choice field, and firmware text never panics on the simulator's reply.
1205pub fn app_hooks(d: &dyn Driver) {
1206    let id = d.info().id;
1207    let demo = d.demo_library();
1208    let writable: usize = d
1209        .capabilities()
1210        .banks
1211        .iter()
1212        .filter(|b| b.writable)
1213        .map(|b| usize::from(b.len))
1214        .sum();
1215    assert!(
1216        demo.programs.len() <= writable,
1217        "{id}: demo library too big"
1218    );
1219    for p in &demo.programs {
1220        d.check_program(&p.data)
1221            .unwrap_or_else(|e| panic!("{id}: demo program: {e}"));
1222    }
1223    let replies = d
1224        .demo_simulator()
1225        .handle(&oscyl_driver::sysex::DEVICE_INQUIRY);
1226    let reply = replies
1227        .iter()
1228        .find(|r| d.recognize(r))
1229        .unwrap_or_else(|| panic!("{id}: demo simulator is not recognised"));
1230    let _ = d.firmware(reply);
1231    if let Some(f) = d.list_facet() {
1232        assert!(f < d.fields().len(), "{id}: list facet out of range");
1233        assert!(
1234            matches!(d.control(&d.init_program(), f), Control::Choice(_)),
1235            "{id}: list facet is not a choice"
1236        );
1237    }
1238}
1239
1240#[cfg(test)]
1241mod tests {
1242    use super::{curation_shape, well_formed};
1243    use oscyl_driver::{Curation, Page, Section};
1244
1245    fn page(fields: Vec<usize>) -> Page {
1246        Page {
1247            title: "P",
1248            icon: None,
1249            help: "",
1250            sections: vec![Section { title: "S", fields }],
1251        }
1252    }
1253
1254    #[test]
1255    fn a_raw_dump_or_empty_editor_is_refused() {
1256        let ok = Curation {
1257            pages: vec![page(vec![0])],
1258            excluded: vec![1],
1259        };
1260        assert_eq!(curation_shape(&ok, 2), Ok(()));
1261        let none = Curation {
1262            pages: vec![],
1263            excluded: vec![0, 1],
1264        };
1265        assert!(curation_shape(&none, 2).is_err());
1266        let all_excluded = Curation {
1267            pages: vec![Page {
1268                sections: vec![],
1269                ..page(vec![])
1270            }],
1271            excluded: vec![0, 1],
1272        };
1273        assert!(curation_shape(&all_excluded, 2).is_err());
1274        let twice = Curation {
1275            pages: vec![page(vec![0, 1])],
1276            excluded: vec![1],
1277        };
1278        assert!(curation_shape(&twice, 2).is_err());
1279        let missing = Curation {
1280            pages: vec![page(vec![0])],
1281            excluded: vec![],
1282        };
1283        assert!(curation_shape(&missing, 2).is_err());
1284        let out_of_range = Curation {
1285            pages: vec![page(vec![0, 1, 2])],
1286            excluded: vec![],
1287        };
1288        assert!(curation_shape(&out_of_range, 2).is_err());
1289    }
1290
1291    #[test]
1292    fn one_message_per_vec() {
1293        assert!(well_formed(&[0xB5, 99, 0], 5));
1294        assert!(well_formed(&[0xC5, 3], 5));
1295        assert!(!well_formed(&[0xB5, 99, 0, 0xB5, 98, 1], 5));
1296        assert!(!well_formed(&[0xB4, 99, 0], 5));
1297        assert!(!well_formed(&[0xB5, 0x80, 0], 5));
1298        assert!(!well_formed(&[0xB5, 99], 5));
1299        assert!(!well_formed(&[], 5));
1300    }
1301}