Architecture¶

Roughly 2,700 lines of Rust, about a third of which is tests, plus 79 lines of Python and ten dependencies.

Module map¶

flowchart TD
    main[main.rs<br/>CLI only] --> exec[exec.rs<br/>the workflow]
    exec --> config[config.rs]
    exec --> mutate[mutate.rs]
    exec --> diff[diff.rs]
    exec --> cov[coverage.rs]
    exec --> batch[batch.rs]
    exec --> runner[runner.rs]
    exec --> report[report.rs]
    exec --> db[(db.rs)]
    runner --> warm[warm.rs]
    runner --> pytest[pytest.rs]
    warm --> py[worker.py]
    cov --> db

Three rules¶

Types own their behaviour¶

If a function takes an X and branches on it, it belongs on X. Hence SuiteResult::status(), Batch::accepts(), TestCase::node_id() rather than a pile of free functions taking six arguments each.

Async is quarantined¶

turso's API is async only. Rather than colour the whole program, db.rs owns a single threaded tokio runtime and blocks on every call. Everything outside that file is ordinary synchronous Rust.

Cleanup is automatic¶

Anything that must be undone implements Drop, so it is undone even on an early return or a panic.

Drop cannot return errors. PatchedFiles therefore swallows a failed restore on purpose: the next batch checks the original bytes before patching, so a bad restore becomes an error verdict rather than a wrong one.

Concurrency¶

flowchart LR
    Q[shared counter:<br/>next batch] -.-> W1[worker 1]
    Q -.-> W2[worker 2]
    Q -.-> W3[worker N]
    W1 -->|channel| D[(main thread<br/>owns the database)]
    W2 -->|channel| D
    W3 -->|channel| D

Scoped threads, one atomic integer as the work queue, and a channel for results. Every database write happens on the main thread, so there is no locking anywhere in the program.

Scoped threads are also what allow a worker to hold plain references rather than reference counted pointers, because the compiler can prove the threads finish before the borrowed data goes away.

Data lives in data files¶

Both are embedded into the binary at compile time, so there is still only one file to ship.

The operator table is a macro, so the lookup and the list its tests iterate are generated from the same lines and cannot drift apart.

Dependencies¶

Three were removed by hand rolling small replacements: walkdir became a twelve line recursive copy, tempfile became a Drop implementation, and serde_json became a newline joined list plus a twenty line reply parser.