padded_cell 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b89fce8fce6e50ada1a385206f76070b475a2f9e90f495170753d6d66a6f8332
-  data.tar.gz: 9ee3b35b649b6be14e016202f87989441145c8c3ace22e6061a0a61016bb8751
+  metadata.gz: 71107b6522d03ca5d3c7f11cb93cd0e6374f283b843a1b456699d69f2a131e11
+  data.tar.gz: efd0654d4986a1fca13380f8a5abcea88ead77944e7e7a92b4cd6a58a69208de
 SHA512:
-  metadata.gz: 9bf53e2049839807e263fa6af61852e63ee7574e2f3902448ef73fbf926b607b02e93bc6a7fbc61a603998321b8f7461f907666d59cdcb816be999665f4ed258
-  data.tar.gz: 90fc61b89533d99849333689f04ff149e079fb775a835cc4d26a0d9224d722a698fb9198f1a23ea0875fb4ac0be21a4949d641e6be45de1ca0f5d848a98886c5
+  metadata.gz: 64a6eca62591f0b9c6c887587ae7a00be9135f4b6addb9fb4e869fe9fae10b6be9145c9a3834d05e83a2e9e225319f846b91f85a92266038db1bf383b40d3c65
+  data.tar.gz: 53049afc045f49d8a3e62504780babf42a7800988055c2075a961c57fb124085c868a31fff5356f4bf8ed5fd1db3c61e2c771ae151b2d243e62d92facb304c81

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.2.0 (2026-10-11)
+
+- Built-in coverage: `--coverage[=lines,branches,methods,eval]` (or
+  `PADDED_CELL_COVERAGE`) measures the runner, every worker and every cell,
+  and sums them exactly. Configured with `PaddedCell.coverage` in the test
+  helper: tracked files, filters, groups, the `:rails` profile. Honors
+  `# :nocov:` blocks and `# simplecov:disable` comments. Writes
+  `coverage.md` (the code that never ran, for agents, reviews and CI
+  summaries), `lcov.info`, and `coverage.json` / `.resultset.json`.
+  `minimum`, `minimum_by_file`, `minimum_by_group` and `maximum_drop` fail a
+  whole passing run with exit 3. `--coverage-merge` merges shards' reports.
+- `--seed` must be 0 to 2**64 - 1; others crashed the planner.
+- `--asylum[=N]`: retry failed tests (N times, default 2) after the run,
+  alone and in fresh cells. Tests that pass on retry count as passed and are
+  reported as flaky, with the likely cause (timing and shared state, or
+  randomness and order) and their first failure; JUnit gets
+  `<flakyFailure>`, JSON a `flaky` field.
+- A `cleanup` hook that raises fails the run (exit 1), `--asylum` retries
+  included. It exited 0 when the tests passed.
+- A passing run filtered with `--name` exits 0: it exited 1, reporting that
+  nothing ran.
+- `--list` applies `--name` and `--exclude`, before `--shard`, as a run does.
+- An invalid `--name` or `--exclude` regexp is a usage error (exit 2), not a
+  crash.
+
 ## 0.1.0 (2026-10-11)
 
 First release, for CRuby 4.0+ and Minitest 6 on Linux, macOS and FreeBSD: a

data/Cargo.lock

@@ -220,7 +220,7 @@ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
 [[package]]
 name = "padded_cell"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "ruby-prism",
  "tempfile",
@@ -229,7 +229,7 @@ dependencies = [
 
 [[package]]
 name = "padded_cell_native"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "magnus",
  "padded_cell",

data/README.md

@@ -70,13 +70,15 @@ $ padded_cell -n /refund/ -e test_slow     # Minitest's --include / --exclude
 $ padded_cell -j 8 --seed 1234             # 8 workers, reproducible order
 $ padded_cell --timeout 30                 # kill and fail anything running 30s
 $ padded_cell --fail-fast
+$ padded_cell --asylum                     # retry failures; report the flaky ones (see below)
 $ padded_cell --list                       # what would run, without loading anything
 $ padded_cell --shard 2/4                  # CI: the second quarter of the classes
 $ padded_cell --junit tmp/junit.xml --json tmp/results.jsonl
+$ padded_cell --coverage                   # line and branch coverage (see Coverage)
 ```
 
 Exit status: 0 when everything passed, 1 otherwise, 2 for usage or load
-errors, 130 when interrupted.
+errors, 3 when only coverage is below a threshold, 130 when interrupted.
 
 ### How a run works
 
@@ -113,6 +115,38 @@ discards Active Record's connection pool, and every test would reload its
 fixtures, so those suites default to `worker`. The `Run options:` line shows
 which one a run uses; `--isolation` overrides it.
 
+### Flaky tests
+
+`--asylum[=N]` gives failed tests up to N more attempts (default 2) once the
+run is over: one test at a time, each in a fresh cell. A test that passes on
+retry counts as passed, but padded_cell shows every attempt, its seed, and
+what made the difference:
+
+```console
+4 runs, 4 assertions, 1 failures, 0 errors, 0 skips
+
+You're not crazy, the world is. 2 tests failed, then passed:
+
+  FlakyTest#test_passes_when_retried
+    seed 1      lost the race
+    seed 1      passed, alone → timing, contention or state left by other tests
+
+  FlakyTest#test_depends_on_the_seed
+    seed 1      unlucky seed.
+    seed 1      unlucky seed. (alone)
+    seed 15472  passed, alone → randomness or test order
+
+It's not the world, it's the test:
+  FlakyTest#test_always_fails failed all 3 attempts
+```
+
+The first retry keeps the run's seed and runs alone, so passing there points
+at timing, contention or leftover state; later retries change the seed, so
+passing only there points at randomness or order. A test that fails every
+attempt keeps its first failure, and the run fails. JUnit reports carry a
+`<flakyFailure>` per flaky test; JSON lines carry the attempts in a `flaky`
+field, or an `asylum` field for a test that never passed.
+
 ### Hooks
 
 For anything that must not be shared across forks:
@@ -125,7 +159,115 @@ PaddedCell.cleanup { |worker| Database.drop("app_test_#{worker}") }
 ```
 
 `before_fork` runs in the runner, `after_fork` and `cleanup` once per worker
-(`0...jobs`). Cells run no hooks: they inherit their worker's state.
+(`0...jobs`). Cells run no hooks: they inherit their worker's state. A
+failing `after_fork` fails every test of its worker; a failing `cleanup`
+fails the run, even when every test passed.
+
+## Coverage
+
+Ruby's `Coverage`, measured in the runner, in every worker and in every
+cell, and summed exactly: a parallel run reports the counts of a serial one.
+
+```console
+$ padded_cell --coverage test/                         # lines and branches
+$ padded_cell --coverage=lines,branches,methods test/
+$ PADDED_CELL_COVERAGE=1 bin/rails padded_cell
+```
+
+Measuring starts before the suite loads, so what is measured (`lines`,
+`branches`, `methods`, and `eval` for templates, experimental) comes from the
+command line. The report is configured in the test helper:
+
+```ruby
+# test/test_helper.rb
+PaddedCell.coverage(:rails) do
+  track "{app,lib}/**/*.rb"           # report files never loaded, at 0%
+  skip "app/legacy/"                  # also `filter`
+  group "Operations", "app/concepts"  # string, regexp, array or block
+  group("Contracts") { |file| file.filename.include?("contract") }
+  minimum line: 90, branch: 80
+  minimum_by_file line: 50
+  minimum_by_group "Operations", line: 95
+  maximum_drop line: 1                # since the previous whole run
+  formats :markdown, :lcov, :json
+  dir "coverage"                      # --coverage-dir wins
+end
+```
+
+- Paths are matched relative to the project root. A string matches whole
+  path segments (`"app/models"` takes `app/models/user.rb`, not
+  `app/models_old/`), `"lib/"` a directory anywhere, `"contract.rb"` a file
+  name ending; a regexp matches the path; a block gets the file
+  (`filename`, `project_filename`, `src`).
+- Left out by default: `vendor/bundle`, hidden files, `test/`, `spec/`,
+  `features/`. `clear_filters` drops these.
+- `:rails` skips `config/` and `db/`, groups `app/channels`,
+  `app/controllers`, `app/helpers`, `app/jobs` and `app/workers`, `lib/`,
+  `app/mailers`, `app/models` and `app/views`, and tracks
+  `{app,lib}/**/*.rb`. A file in no group is Ungrouped.
+- Thresholds compare percents floored to 2 decimals.
+
+`PaddedCell.coverage` configures only; without `--coverage` nothing is
+measured. Outside padded_cell, guard it with `if defined?(PaddedCell.coverage)`.
+
+Into `coverage/` go, by format:
+
+- `markdown`: `coverage.md`, for agents, reviews and CI summaries
+  (`cat coverage/coverage.md >> $GITHUB_STEP_SUMMARY`): the totals and
+  groups, then every file with code that never ran, the most missed first,
+  with its missed lines, branches and methods, and that code. It stops
+  listing files at 1 MB, the size of a GitHub job summary.
+- `lcov`: `lcov.info` (`SF:./path`), for CI and editors.
+- `json`: `coverage.json` and `.resultset.json`, in SimpleCov's formats, for
+  the tools reading them.
+
+Also, every run: `.padded_cell.json` (what the report is made of, and what
+`--coverage-merge` reads), and after a whole passing run `.last_run.json`.
+
+Lines and branches inside `# :nocov:` blocks, and under
+`# simplecov:disable [line|branch|method]` / `# simplecov:enable` comments,
+are skipped. A directive after code skips its own line.
+
+A run below a threshold exits 3. Thresholds hold for a whole, passing,
+complete run only: they are not checked when tests failed, when tests were
+picked by name or line, under `--shard`, or when a worker or cell died
+before handing over what it measured (the report then says it is partial).
+Reports are written either way, failing runs included.
+
+A suite that starts SimpleCov as well is refused (exit 2): two tools cannot
+share Ruby's `Coverage`.
+
+### Shards
+
+Each shard reports on its own; merge them, at the same commit, without
+running anything:
+
+```console
+$ padded_cell --coverage --coverage-dir coverage/1 --shard 1/2 test/   # machine 1
+$ padded_cell --coverage --coverage-dir coverage/2 --shard 2/2 test/   # machine 2
+$ padded_cell --coverage-merge coverage/1,coverage/2 --coverage-dir coverage
+```
+
+The merge refuses files that differ between shards or from the checkout,
+and checks thresholds when every shard of the run is there. Lines that run
+while the suite loads count once per shard.
+
+### Cost
+
+Measuring is opt-in: Ruby's instrumentation slows tests down. On a Rails
+suite of 6,300 tests, lines and branches took the run from 465 s to 638 s of
+CPU.
+
+A worker hands over what it measured every 10 seconds or more: each time,
+Ruby copies the coverage of every file it loaded, gems included (a few
+milliseconds in a small app, a few hundred in a big Rails one), so the
+interval stretches to keep this under 1% of the worker's time. A worker that
+dies loses what it measured since. With `--isolation test` every cell pays
+one such copy, at its end.
+
+Files never loaded report their branches in the order Ruby compiles them.
+With `eval`, code that `class_eval` runs from a heredoc counts as lines of
+its file; directives in templates are not read.
 
 ## Rails
 
@@ -144,8 +286,7 @@ $ bin/rails padded_cell ARGS="-j 8 test/models"
 Rails suites with fixtures run with `--isolation worker` unless told
 otherwise (see [Isolation](#isolation)).
 
-Coverage tools that write their results from an `at_exit` hook (SimpleCov)
-see only the runner, as with Rails' process parallelization.
+For coverage, see [Coverage](#coverage).
 
 ## Library
 
@@ -173,9 +314,9 @@ Needs Rust 1.99+ (`mise install` reads `mise.toml`).
 
 ```console
 bundle install
-rake test:all        # cargo test, then the Ruby suite (compiles the extension first)
-rake test            # the Ruby suite only
-rake dogfood         # this suite, run by padded_cell
+rake test:all        # cargo test, then this suite run by padded_cell itself
+rake dogfood         # this suite, run by padded_cell (compiles the extension first)
+rake test            # this suite on plain Minitest, for when padded_cell itself is broken
 rake lint            # dictator, cargo fmt --check, clippy
 ```
 

data/ext/padded_cell_native/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "padded_cell"
-version = "0.1.0"
+version = "0.2.0"
 description = "Static Minitest discovery and test scheduling for the padded_cell gem"
 publish = false
 edition.workspace = true

data/ext/padded_cell_native/core/src/chart/directives/tests.rs

@@ -0,0 +1,56 @@
+use super::*;
+
+fn skipped(text: &str) -> Skipped {
+    Skipped::of(&Source::new(text.as_bytes().to_vec()), "nocov")
+}
+
+/// Where the `#` is, disable, and the criteria named.
+type Found = Option<(usize, bool, [bool; 3])>;
+
+#[test]
+fn directives_found_in_comments() {
+    const CASES: &[(&str, Found)] = &[
+        ("# simplecov:disable", Some((0, true, [true; 3]))),
+        ("#simplecov : enable", Some((0, false, [true; 3]))),
+        ("# simplecov:disable branch", Some((0, true, [false, true, false]))),
+        ("# simplecov:disable line , method because", Some((0, true, [true, false, true]))),
+        // The longest list ending at a word boundary.
+        ("# simplecov:disable line, branchy", Some((0, true, [true, false, false]))),
+        ("# simplecov:disable lines", Some((0, true, [true; 3]))),
+        ("# note # simplecov:disable", Some((7, true, [true; 3]))),
+        ("# simplecov:disabled", None),
+        ("# simplecov disable", None),
+        ("# rubocop:disable Style", None),
+    ];
+    for (text, expected) in CASES {
+        let found = Directive::find(text.as_bytes())
+            .map(|(at, directive)| (at, directive.disable, directive.criteria));
+        assert_eq!(found, *expected, "comment: {text:?}");
+    }
+}
+
+#[test]
+fn blocks_inline_directives_and_nocov() {
+    let text = "\
+a
+# simplecov:disable branch
+b
+# simplecov:enable branch
+c # simplecov:disable
+# :nocov:
+d
+# :nocov:
+# simplecov:disable method
+e
+";
+    let skipped = skipped(text);
+    assert_eq!(skipped.line, [6..=8, 5..=5]);
+    assert_eq!(skipped.branch, [6..=8, 2..=4, 5..=5]);
+    assert_eq!(skipped.method, [6..=8, 5..=5, 9..=10], "an open block runs to the end");
+}
+
+#[test]
+fn only_real_comments_count() {
+    let text = "x = \"# simplecov:disable\"\ny = <<~TEXT\n  # simplecov:disable\nTEXT\n";
+    assert_eq!(skipped(text), Skipped::default());
+}

data/ext/padded_cell_native/core/src/chart/directives.rs

@@ -0,0 +1,144 @@
+use std::ops::RangeInclusive;
+
+use ruby_prism::CommentType;
+
+use super::Source;
+use super::source::{ruby_space, trim_start as skip_space};
+
+#[cfg(test)]
+mod tests;
+
+/// Blocks of lines, inclusive.
+pub type Blocks = Vec<RangeInclusive<u32>>;
+
+/// The lines each criterion ignores.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct Skipped {
+    pub line: Blocks,
+    pub branch: Blocks,
+    pub method: Blocks,
+}
+
+impl Skipped {
+    #[must_use]
+    pub fn of(source: &Source, nocov_token: &str) -> Self {
+        let nocov = source.nocov(nocov_token);
+        let mut skipped = Self { line: nocov.clone(), branch: nocov.clone(), method: nocov };
+        // Parsing only sources that may hold one.
+        if source.bytes().windows(9).any(|window| window == b"simplecov") {
+            skipped.add_directives(source);
+        }
+        skipped
+    }
+
+    fn add_directives(&mut self, source: &Source) {
+        let result = ruby_prism::parse(source.bytes());
+        let mut open: [Option<u32>; 3] = [None; 3];
+        let comments =
+            result.comments().filter(|comment| comment.type_() == CommentType::InlineComment);
+        for comment in comments {
+            let Some((at, directive)) = Directive::find(comment.text()) else {
+                continue;
+            };
+            let offset = comment.location().start_offset().strict_add(at);
+            let (line, _) = source.position(offset);
+            let before = &source.bytes()[source.line_start(offset)..offset];
+            let inline = before.iter().any(|&byte| !ruby_lstrip_space(byte));
+            let blocks = self.blocks_mut().into_iter().zip(&mut open);
+            for ((blocks, open), _) in blocks.zip(directive.criteria).filter(|&(_, named)| named) {
+                directive.apply(line, inline, blocks, open);
+            }
+        }
+        let last = u32::try_from(source.len()).unwrap_or(u32::MAX);
+        for (blocks, open) in self.blocks_mut().into_iter().zip(open) {
+            blocks.extend(open.map(|start| start..=last));
+        }
+    }
+
+    const fn blocks_mut(&mut self) -> [&mut Blocks; 3] {
+        [&mut self.line, &mut self.branch, &mut self.method]
+    }
+}
+
+/// A `# simplecov:disable` or `enable`, and the criteria it names: line,
+/// branch, method.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct Directive {
+    disable: bool,
+    criteria: [bool; 3],
+}
+
+impl Directive {
+    /// The first directive in a comment, and where its `#` is:
+    /// `/#\s*simplecov\s*:\s*(disable|enable)\b(?:\s+(criteria)\b)?/`.
+    fn find(text: &[u8]) -> Option<(usize, Self)> {
+        text.iter().enumerate().filter(|&(_, &byte)| byte == b'#').find_map(|(at, _)| {
+            Self::parse(&text[at.strict_add(1)..]).map(|directive| (at, directive))
+        })
+    }
+
+    fn parse(text: &[u8]) -> Option<Self> {
+        let text = skip_space(skip_space(text).strip_prefix(b"simplecov")?).strip_prefix(b":")?;
+        let text = skip_space(text);
+        let (disable, rest) = match text.strip_prefix(b"disable") {
+            Some(rest) => (true, rest),
+            None => (false, text.strip_prefix(b"enable")?),
+        };
+        if starts_with_word(rest) {
+            return None;
+        }
+        Some(Self { disable, criteria: criteria(rest).unwrap_or([true; 3]) })
+    }
+
+    /// After code, a directive covers its own line; alone on its line, it
+    /// opens or closes a block (a block already open stays as it is).
+    fn apply(self, line: u32, inline: bool, blocks: &mut Blocks, open: &mut Option<u32>) {
+        if inline {
+            if self.disable {
+                blocks.push(line..=line);
+            }
+        } else if self.disable {
+            open.get_or_insert(line);
+        } else if let Some(start) = open.take() {
+            blocks.push(start..=line);
+        }
+    }
+}
+
+/// `\s+(line|branch|method)(\s*,\s*(line|branch|method))*\b`, the longest
+/// list that ends at a word boundary.
+fn criteria(text: &[u8]) -> Option<[bool; 3]> {
+    if !text.first().is_some_and(|&byte| ruby_space(byte)) {
+        return None;
+    }
+    let (mut text, mut found, mut accepted) = (skip_space(text), [false; 3], None);
+    while let Some((index, rest)) = criterion(text) {
+        found[index] = true;
+        if starts_with_word(rest) {
+            break;
+        }
+        accepted = Some(found);
+        let Some(next) = skip_space(rest).strip_prefix(b",") else {
+            break;
+        };
+        text = skip_space(next);
+    }
+    accepted
+}
+
+fn criterion(text: &[u8]) -> Option<(usize, &[u8])> {
+    [&b"line"[..], b"branch", b"method"]
+        .iter()
+        .enumerate()
+        .find_map(|(index, name)| text.strip_prefix(*name).map(|rest| (index, rest)))
+}
+
+/// What Ruby's `String#lstrip` strips.
+const fn ruby_lstrip_space(byte: u8) -> bool {
+    byte == 0 || ruby_space(byte)
+}
+
+/// Not at a word boundary: Ruby's `\w` comes next.
+fn starts_with_word(text: &[u8]) -> bool {
+    text.first().is_some_and(|&byte| byte.is_ascii_alphanumeric() || byte == b'_')
+}

data/ext/padded_cell_native/core/src/chart/json/tests.rs

@@ -0,0 +1,46 @@
+use super::*;
+
+fn render(pretty: bool, write: impl FnOnce(&mut Json<'_, Vec<u8>>) -> io::Result<()>) -> String {
+    let mut out = Vec::new();
+    let mut json = if pretty { Json::pretty(&mut out) } else { Json::compact(&mut out) };
+    write(&mut json).unwrap();
+    String::from_utf8(out).unwrap()
+}
+
+/// Ruby's output for `{a: [], b: {}, c: [1, {d: nil}]}`.
+#[test]
+fn layouts_of_pretty_generate_and_generate() {
+    let document = |json: &mut Json<'_, Vec<u8>>| {
+        json.object(|json| {
+            json.key("a")?.array(|_| Ok(()))?;
+            json.key("b")?.object(|_| Ok(()))?;
+            json.key("c")?.array(|json| {
+                json.item()?.uint(1)?;
+                json.item()?.object(|json| json.key("d")?.null())
+            })
+        })
+    };
+    assert_eq!(
+        render(true, document),
+        "{\n  \"a\": [],\n  \"b\": {},\n  \"c\": [\n    1,\n    {\n      \"d\": null\n    }\n  ]\n}"
+    );
+    assert_eq!(render(false, document), r#"{"a":[],"b":{},"c":[1,{"d":null}]}"#);
+}
+
+/// Ruby's `JSON.generate(["\x1f\x01\b\f\n\r\t\"\\/é ", 100.0, 66.66666666666667, 0.1 + 0.2])`.
+#[test]
+fn strings_and_floats_as_ruby_writes_them() {
+    let rendered = render(false, |json| {
+        json.array(|json| {
+            json.item()?.str("\u{1f}\u{1}\u{8}\u{c}\n\r\t\"\\/é ")?;
+            json.item()?.float(100.0)?;
+            json.item()?.float(200.0 / 3.0)?;
+            json.item()?.float(0.1 + 0.2)?;
+            json.item()?.bool(false)
+        })
+    });
+    assert_eq!(
+        rendered,
+        r#"["\u001f\u0001\b\f\n\r\t\"\\/é ",100.0,66.66666666666667,0.30000000000000004,false]"#
+    );
+}

data/ext/padded_cell_native/core/src/chart/json.rs

@@ -0,0 +1,175 @@
+use std::io::{self, Write};
+
+#[cfg(test)]
+mod tests;
+
+/// A JSON writer. Containers take a closure writing their members:
+///
+/// ```text
+/// json.object(|json| {
+///     json.key("lines")?.array(|json| json.item()?.uint(1))
+/// })
+/// ```
+pub struct Json<'w, W: Write> {
+    out: &'w mut W,
+    pretty: bool,
+    depth: usize,
+    /// The innermost container has no member yet.
+    empty: bool,
+}
+
+impl<'w, W: Write> Json<'w, W> {
+    /// `JSON.pretty_generate`'s layout: two-space indents, one member per
+    /// line, `[]` and `{}` when empty.
+    pub const fn pretty(out: &'w mut W) -> Self {
+        Self { out, pretty: true, depth: 0, empty: true }
+    }
+
+    /// `JSON.generate`'s: no whitespace.
+    pub const fn compact(out: &'w mut W) -> Self {
+        Self { out, pretty: false, depth: 0, empty: true }
+    }
+
+    /// # Errors
+    ///
+    /// What writing returns.
+    pub fn object(&mut self, members: impl FnOnce(&mut Self) -> io::Result<()>) -> io::Result<()> {
+        self.container(b'{', b'}', members)
+    }
+
+    /// # Errors
+    ///
+    /// What writing returns.
+    pub fn array(&mut self, items: impl FnOnce(&mut Self) -> io::Result<()>) -> io::Result<()> {
+        self.container(b'[', b']', items)
+    }
+
+    /// Starts an object member: its value comes next.
+    ///
+    /// # Errors
+    ///
+    /// What writing returns.
+    pub fn key(&mut self, key: &str) -> io::Result<&mut Self> {
+        self.separate()?;
+        self.raw_str(key)?;
+        self.out.write_all(if self.pretty { b": " } else { b":" })?;
+        Ok(self)
+    }
+
+    /// Starts an array item: its value comes next.
+    ///
+    /// # Errors
+    ///
+    /// What writing returns.
+    pub fn item(&mut self) -> io::Result<&mut Self> {
+        self.separate()?;
+        Ok(self)
+    }
+
+    /// # Errors
+    ///
+    /// What writing returns.
+    pub fn str(&mut self, value: &str) -> io::Result<()> {
+        self.raw_str(value)
+    }
+
+    /// # Errors
+    ///
+    /// What writing returns.
+    pub fn uint(&mut self, value: u64) -> io::Result<()> {
+        write!(self.out, "{value}")
+    }
+
+    /// Ruby's way: `100.0`, not `100`.
+    ///
+    /// # Errors
+    ///
+    /// What writing returns.
+    pub fn float(&mut self, value: f64) -> io::Result<()> {
+        let mut text = value.to_string();
+        if !text.contains(['.', 'e', 'N', 'i']) {
+            text.push_str(".0");
+        }
+        self.out.write_all(text.as_bytes())
+    }
+
+    /// # Errors
+    ///
+    /// What writing returns.
+    pub fn bool(&mut self, value: bool) -> io::Result<()> {
+        self.out.write_all(if value { b"true" } else { b"false" })
+    }
+
+    /// # Errors
+    ///
+    /// What writing returns.
+    pub fn null(&mut self) -> io::Result<()> {
+        self.out.write_all(b"null")
+    }
+
+    fn container(
+        &mut self,
+        open: u8,
+        close: u8,
+        members: impl FnOnce(&mut Self) -> io::Result<()>,
+    ) -> io::Result<()> {
+        self.out.write_all(&[open])?;
+        self.depth = self.depth.strict_add(1);
+        self.empty = true;
+        members(self)?;
+        self.depth = self.depth.strict_sub(1);
+        if !self.empty {
+            self.newline()?;
+        }
+        // The enclosing container has this one as a member.
+        self.empty = false;
+        self.out.write_all(&[close])
+    }
+
+    fn separate(&mut self) -> io::Result<()> {
+        if !self.empty {
+            self.out.write_all(b",")?;
+        }
+        self.empty = false;
+        self.newline()
+    }
+
+    fn newline(&mut self) -> io::Result<()> {
+        if self.pretty {
+            self.out.write_all(b"\n")?;
+            for _ in 0..self.depth {
+                self.out.write_all(b"  ")?;
+            }
+        }
+        Ok(())
+    }
+
+    /// Escapes what JSON requires, in runs: no copy of the string.
+    fn raw_str(&mut self, value: &str) -> io::Result<()> {
+        self.out.write_all(b"\"")?;
+        let bytes = value.as_bytes();
+        let mut start = 0;
+        for (index, &byte) in bytes.iter().enumerate() {
+            let escape: &[u8] = match byte {
+                b'"' => b"\\\"",
+                b'\\' => b"\\\\",
+                0x08 => b"\\b",
+                0x0c => b"\\f",
+                b'\n' => b"\\n",
+                b'\r' => b"\\r",
+                b'\t' => b"\\t",
+                0x20.. => continue,
+                _ => b"",
+            };
+            self.out.write_all(&bytes[start..index])?;
+            if escape.is_empty() {
+                write!(self.out, "\\u{byte:04x}")?;
+            } else {
+                self.out.write_all(escape)?;
+            }
+            start = index.strict_add(1);
+        }
+        self.out.write_all(&bytes[start..])?;
+        self.out.write_all(b"\"")
+    }
+}