oakum 0.12.1

A polyglot release tool that derives dependent version bumps from the dependency graph
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
//! The renders of a [`ReleaseState`]: the `status` summary and the pull
//! request comment `ci pr-status` posts, with the marker that finds it again.

use std::fmt::Write;

use oakum::state::{
    ChangedPackage, CoverageLook, EcosystemName, PackageRef, ReleaseSource, ReleaseState,
};

use super::config::{unresolved_scope_line, UNMANAGED_FIX};
use super::reasons;

/// Where intent comes from, which the state document does not carry, so the
/// renders can name the command that adds it. `None` where no one acts on the
/// plan: the version pull request body.
#[derive(Clone, Debug, PartialEq, Eq)]
pub(super) enum NextStep {
    BumpFiles {
        pending: usize,
        generate: bool,
        /// The quoted base `generate --from` covers this branch from, when
        /// `generate` is allowed and the branch has no bump file of its own.
        generate_from: Option<String>,
    },
    Commits,
}

impl NextStep {
    fn cover_uncovered(&self) -> String {
        match self {
            Self::BumpFiles { generate_from, .. } => {
                let mut line = String::from(
                    "Cover each with `oakum add --packages <package>:<level>`, or `<package>:none` to cover it without a release",
                );
                if let Some(base) = generate_from {
                    let _ = write!(
                        line,
                        "; `oakum generate --from {base}` writes them from conventional commits"
                    );
                }
                line.push('.');
                line
            }
            Self::Commits => {
                String::from("Name each in a conventional commit, or in a path that maps to it.")
            }
        }
    }
}

pub(super) fn render_summary(state: &ReleaseState, next: Option<&NextStep>) -> String {
    let mut out = String::from("## Release plan\n\n");
    if state.packages().is_empty() {
        out.push_str("No packages planned.\n");
        if let Some(NextStep::BumpFiles {
            pending: 0,
            generate,
            ..
        }) = next
        {
            if !state.manages_nothing() && !state.selection_empty() {
                out.push_str("\nNo bump file is pending in `.changeset`. `oakum add` writes one");
                if *generate {
                    out.push_str(", and `oakum generate` writes one from conventional commits");
                }
                out.push_str(".\n");
            }
        }
        // Without this the same sentence covers two states a reader must act on
        // differently: waiting for intent, and a config that will never produce
        // any. `check` refuses on the second; `status` only says so.
        if state.manages_nothing() {
            out.push_str(
                "\nThis config manages no package on either axis, so no plan can ever be non-empty; set `private-packages.version` / `private-packages.tag`, or adjust `include`/`exclude`.\n",
            );
        }
        // `check` stays silent here on purpose: a gate must not refuse a
        // decision the config wrote down. `status` is not a gate (`okm-404.32`).
        if state.selection_empty() {
            out.push_str(
                "\n`include`/`exclude` leave no package selected, so no plan can ever name one. `check` does not refuse this, because it is a decision this config states.\n",
            );
        }
    } else {
        out.push_str("| Package | From | To | Bump | Source |\n");
        out.push_str("| --- | --- | --- | --- | --- |\n");
        for pkg in state.packages() {
            let _ = match pkg.source() {
                ReleaseSource::Intent | ReleaseSource::DependencyUpdate => writeln!(
                    out,
                    "| {} (`{}`) | {} | {} | {} | {} |",
                    pkg.name(),
                    ecosystem_label(pkg.ecosystem()),
                    pkg.from_version(),
                    pkg.to_version(),
                    pkg.bump().as_str(),
                    if *pkg.source() == ReleaseSource::DependencyUpdate {
                        "dependency updates"
                    } else {
                        "intent"
                    },
                ),
                ReleaseSource::Cascade { trigger } => writeln!(
                    out,
                    "| {} (`{}`) | {} | {} | {} | cascade from {} ({}) |",
                    pkg.name(),
                    ecosystem_label(pkg.ecosystem()),
                    pkg.from_version(),
                    pkg.to_version(),
                    pkg.bump().as_str(),
                    trigger.name(),
                    ecosystem_label(trigger.ecosystem()),
                ),
            };
        }
    }
    push_summary_coverage(&mut out, state, next);
    if !state.unmanaged().is_empty() {
        let _ = write!(
            out,
            "\nChanged but not version-managed: {}\n{UNMANAGED_FIX}\n",
            package_list(state.unmanaged())
        );
    }
    if !state.named_unmanaged().is_empty() {
        let _ = write!(
            out,
            "\nNamed by a commit but not version-managed: {}\n{UNMANAGED_FIX}\n",
            package_list(state.named_unmanaged())
        );
    }
    push_unlinked(&mut out, state);
    push_unresolved_scopes(&mut out, state);
    if !state.awaiting_tag().is_empty() {
        let _ = write!(
            out,
            "\nReleased, awaiting its tag: {}\n{AWAITING_TAG}\n",
            package_list(state.awaiting_tag())
        );
    }
    if !state.updates_unread().is_empty() {
        let _ = write!(
            out,
            "\nDependency updates not read: {}\n{UPDATES_UNREAD}\n",
            package_list(state.updates_unread())
        );
    }
    push_hand_set(&mut out, state);
    // The JSON separates a look that ran from one that did not; this render is
    // what a reviewer reads, and stderr does not travel into a step
    // summary or a pull-request body.
    if state.coverage() == CoverageLook::Failed {
        out.push_str(
            "\nCoverage was not checked: git could not diff this tree, so an empty uncovered list is not a clean result.\n",
        );
    }
    out
}

const AWAITING_TAG: &str = "no commits are planned for it until `oakum release` tags the release";

const UPDATES_UNREAD: &str =
    "no tag records its last release, so `dependency-updates = \"release\"` reads no range for it; a bump file still releases it";

/// The comment's planned releases, a release made only of dependency updates
/// named as one.
fn push_releases(out: &mut String, state: &ReleaseState) {
    if state.packages().is_empty() {
        return;
    }
    out.push_str("\nThese packages will release:\n\n");
    for pkg in state.packages() {
        let by = if *pkg.source() == ReleaseSource::DependencyUpdate {
            ", dependency updates"
        } else {
            ""
        };
        let _ = writeln!(
            out,
            "- `{}` {} → {} ({}{by})",
            pkg.name(),
            pkg.from_version(),
            pkg.to_version(),
            pkg.bump().as_str(),
        );
    }
}

/// A comment list of `packages` under `heading`, each line ending in `why`.
fn push_listed(out: &mut String, heading: &str, packages: &[PackageRef], why: &str) {
    if packages.is_empty() {
        return;
    }
    let _ = write!(out, "\n{heading}:\n\n");
    for pkg in packages {
        let _ = writeln!(
            out,
            "- `{}` ({}) — {why}",
            pkg.name(),
            ecosystem_label(pkg.ecosystem()),
        );
    }
}

fn push_summary_coverage(out: &mut String, state: &ReleaseState, next: Option<&NextStep>) {
    if !state.uncovered().is_empty() {
        out.push_str("\nUncovered:\n\n");
        for pkg in uncovered(state) {
            let _ = writeln!(
                out,
                "- {} (`{}`){}",
                pkg.id().name(),
                ecosystem_label(pkg.id().ecosystem()),
                uncovered_detail(pkg)
            );
        }
        if let Some(next) = next {
            let _ = write!(out, "\n{}\n", next.cover_uncovered());
        }
    }
    let quiet = releasing_nothing(state);
    if !quiet.is_empty() {
        out.push_str("\nChanged, releasing nothing:\n\n");
        for pkg in quiet {
            let _ = writeln!(
                out,
                "- {} (`{}`){}: {}",
                pkg.id().name(),
                ecosystem_label(pkg.id().ecosystem()),
                reasons::via_clause(pkg),
                reasons::covered_phrase(pkg)
            );
        }
    }
}

fn uncovered(state: &ReleaseState) -> impl Iterator<Item = &ChangedPackage> {
    state.changed().iter().filter(|pkg| !pkg.is_covered())
}

/// Covered packages whose coverage releases nothing and that the plan does
/// not release some other way, such as a cascade: the change a reviewer would
/// otherwise not see.
fn releasing_nothing(state: &ReleaseState) -> Vec<&ChangedPackage> {
    state
        .changed()
        .iter()
        .filter(|pkg| {
            pkg.releases_nothing()
                && !state.packages().iter().any(|planned| {
                    planned.name() == pkg.id().name() && planned.ecosystem() == pkg.id().ecosystem()
                })
        })
        .collect()
}

fn uncovered_detail(pkg: &ChangedPackage) -> String {
    let via = reasons::via_clause(pkg);
    match reason_and_fix(pkg) {
        Some(rest) => format!("{via}: {rest}"),
        None => via,
    }
}

/// `<why>: <fix>`, the fix only where a commit names the level, since the
/// next step already shows the command with a placeholder.
fn reason_and_fix(pkg: &ChangedPackage) -> Option<String> {
    let reason = reasons::uncovered_reason_markdown(pkg)?;
    Some(match pkg.fix() {
        Some(fix) => format!("{reason}: `{fix}`"),
        None => reason,
    })
}

fn push_hand_set(out: &mut String, state: &ReleaseState) {
    if state.hand_set().is_empty() {
        return;
    }
    out.push_str(
        "\nBlocked by a version set by hand; `oakum version` refuses this plan until each is fixed:\n\n",
    );
    for entry in state.hand_set() {
        let _ = writeln!(out, "- {}", entry.fix());
    }
}

/// Filled for `status` alone (`release_state::unlinked`).
fn push_unlinked(out: &mut String, state: &ReleaseState) {
    if state.unlinked().is_empty() {
        return;
    }
    out.push_str("\nNamed like a member, installed from the registry:\n\n");
    for entry in state.unlinked() {
        let dependent = entry.dependent();
        let from = entry
            .catalog()
            .map_or_else(String::new, |catalog| format!(" from catalog `{catalog}`"));
        let alias = if entry.declared_as() == entry.on() {
            String::new()
        } else {
            format!(" as `{}`", entry.declared_as())
        };
        let _ = writeln!(
            out,
            "- {} (`{}`) {} `{}`{alias}{from}: `{}` does not match the member's {}",
            dependent.name(),
            ecosystem_label(dependent.ecosystem()),
            entry.table(),
            entry.on(),
            entry.range(),
            entry.member_version(),
        );
    }
    out.push_str(
        "\npnpm links none of these to the member. Write `workspace:` where the member is meant; a registry pin needs nothing.\n",
    );
}

fn push_unresolved_scopes(out: &mut String, state: &ReleaseState) {
    if state.unresolved_scopes().is_empty() {
        return;
    }
    out.push_str("\nReleased by a commit but reaching no package:\n\n");
    for commit in state.unresolved_scopes() {
        let _ = writeln!(out, "- {}", unresolved_scope_line(commit));
    }
}

fn package_list(packages: &[oakum::state::PackageRef]) -> String {
    packages
        .iter()
        .map(|pkg| format!("{} (`{}`)", pkg.name(), ecosystem_label(pkg.ecosystem())))
        .collect::<Vec<_>>()
        .join(", ")
}

pub(super) const PR_PLAN_MARKER: &str = "<!-- oakum:pr-plan -->";

/// `None` when the body would be nothing but the invisible marker. Emptiness is
/// the renderer's to decide: a separate predicate can agree with this today and
/// disagree after one of them grows a case, which posts a blank comment.
pub(super) fn render_comment(state: &ReleaseState, next: Option<&NextStep>) -> Option<String> {
    let mut out = String::from(PR_PLAN_MARKER);
    out.push('\n');
    // Before the list, so the comment does not first promise a release that
    // `version` will refuse.
    push_hand_set(&mut out, state);
    push_releases(&mut out, state);
    if !state.uncovered().is_empty() {
        out.push_str("\nUncovered:\n\n");
        for pkg in uncovered(state) {
            let _ = writeln!(
                out,
                "- `{}` ({}) changed{} with no covering intent{}",
                pkg.id().name(),
                ecosystem_label(pkg.id().ecosystem()),
                reasons::via_clause(pkg),
                reason_and_fix(pkg).map_or_else(String::new, |rest| format!("; {rest}"))
            );
        }
        if let Some(next) = next {
            let _ = write!(out, "\n{}\n", next.cover_uncovered());
        }
    }
    let quiet = releasing_nothing(state);
    if !quiet.is_empty() {
        out.push_str("\nChanged, releasing nothing:\n\n");
        for pkg in quiet {
            let _ = writeln!(
                out,
                "- `{}` ({}){} — {}",
                pkg.id().name(),
                ecosystem_label(pkg.id().ecosystem()),
                reasons::via_clause(pkg),
                reasons::covered_phrase(pkg)
            );
        }
    }
    if !state.unmanaged().is_empty() {
        out.push_str("\nChanged but not version-managed:\n\n");
        for pkg in state.unmanaged() {
            let _ = writeln!(
                out,
                "- `{}` ({}) — {UNMANAGED_FIX}",
                pkg.name(),
                ecosystem_label(pkg.ecosystem()),
            );
        }
    }
    if !state.named_unmanaged().is_empty() {
        out.push_str("\nNamed by a commit but not version-managed:\n\n");
        for pkg in state.named_unmanaged() {
            let _ = writeln!(
                out,
                "- `{}` ({}) — {UNMANAGED_FIX}",
                pkg.name(),
                ecosystem_label(pkg.ecosystem()),
            );
        }
    }
    push_unresolved_scopes(&mut out, state);
    push_listed(
        &mut out,
        "Released, awaiting its tag",
        state.awaiting_tag(),
        AWAITING_TAG,
    );
    push_listed(
        &mut out,
        "Dependency updates not read",
        state.updates_unread(),
        UPDATES_UNREAD,
    );
    if state.manages_nothing() {
        out.push_str(
            "\nThis config manages no package on either axis, so no plan can ever be non-empty.\n",
        );
    }
    if state.selection_empty() {
        out.push_str(
            "\n`include`/`exclude` leave no package selected, so no plan can ever name one.\n",
        );
    }
    if state.coverage() == CoverageLook::Failed {
        out.push_str(
            "\nCoverage was not checked: git could not diff this tree, so an empty uncovered list is not a clean result.\n",
        );
    }
    (out.trim_end() != PR_PLAN_MARKER).then_some(out)
}

const fn ecosystem_label(ecosystem: EcosystemName) -> &'static str {
    match ecosystem {
        EcosystemName::Cargo => "cargo",
        EcosystemName::Npm => "npm",
    }
}

/// The renders, over states built in memory. Every other assertion about a
/// `ReleaseState`'s shape goes through a fixture repository and a subprocess,
/// which is why the emit gate could disagree with the renderer it guarded
/// without a single test failing (`okm-404.33`).
#[cfg(test)]
mod renders {
    use oakum::plan::{
        aggregate, compose, BumpFile, BumpLevel, CascadeAs, Ecosystem, Package, PackageId,
        ResolvesDependenciesAt, Versioning, Workspace,
    };
    use oakum::state::{
        ChangedPackage, CoverSource, Coverage, CoverageOutcome, HandSet, ReleaseState,
        ReleasingCommit, RenderTarget,
    };
    use semver::Version;

    use super::{NextStep, PR_PLAN_MARKER};

    fn render_summary(state: &ReleaseState) -> String {
        super::render_summary(state, None)
    }

    fn render_comment(state: &ReleaseState) -> Option<String> {
        super::render_comment(state, None)
    }

    fn bump_files(pending: usize, generate: bool, generate_from: Option<&str>) -> NextStep {
        NextStep::BumpFiles {
            pending,
            generate,
            generate_from: generate_from.map(String::from),
        }
    }

    /// After `init`, an empty plan names the command that starts one.
    #[test]
    fn an_empty_plan_with_no_bump_file_names_add() {
        let state = empty_state(RenderTarget::Status, CoverageOutcome::NotAsked);
        let summary = super::render_summary(&state, Some(&bump_files(0, false, None)));
        assert!(
            summary.contains("No bump file is pending in `.changeset`. `oakum add` writes one.\n"),
            "{summary}"
        );
        assert!(
            super::render_summary(&state, Some(&bump_files(0, true, None)))
                .contains("and `oakum generate` writes one from conventional commits.")
        );
        for quiet in [
            super::render_summary(&state, Some(&bump_files(1, true, None))),
            super::render_summary(&state, Some(&NextStep::Commits)),
            super::render_summary(&state, None),
            super::render_summary(
                &state.clone().managing_nothing(),
                Some(&bump_files(0, false, None)),
            ),
            super::render_summary(
                &state.clone().selection_emptied(),
                Some(&bump_files(0, false, None)),
            ),
        ] {
            assert!(!quiet.contains("oakum add"), "{quiet}");
        }
    }

    /// `post-comment` and `pr-status` own only a comment that starts with the
    /// marker, so a comment that does not would be posted again every run.
    #[test]
    fn the_comment_starts_with_the_marker() {
        let state = empty_state(
            RenderTarget::Comment,
            CoverageOutcome::Ran(Coverage {
                unmanaged: Vec::new(),
                changed: vec![ChangedPackage::new(
                    cargo("demo"),
                    Vec::new(),
                    Vec::new(),
                    Vec::new(),
                    None,
                )],
            }),
        );
        for next in [None, Some(&NextStep::Commits)] {
            let comment = super::render_comment(&state, next).expect("comment");
            assert!(comment.starts_with(PR_PLAN_MARKER), "{comment}");
        }
    }

    /// `check` names the fix for an uncovered package; the summary and the
    /// comment a contributor reads do too.
    #[test]
    fn an_uncovered_package_names_the_command_that_covers_it() {
        let state = empty_state(
            RenderTarget::Comment,
            CoverageOutcome::Ran(Coverage {
                unmanaged: Vec::new(),
                changed: vec![ChangedPackage::new(
                    cargo("demo"),
                    Vec::new(),
                    Vec::new(),
                    Vec::new(),
                    None,
                )],
            }),
        );
        let add = "Cover each with `oakum add --packages <package>:<level>`, or `<package>:none` to cover it without a release.";
        let summary = super::render_summary(&state, Some(&bump_files(0, false, None)));
        assert!(
            summary.contains(&format!("Uncovered:\n\n- demo (`cargo`)\n\n{add}")),
            "{summary}"
        );
        let comment =
            super::render_comment(&state, Some(&bump_files(0, false, None))).expect("comment");
        assert!(comment.contains(add), "{comment}");
        let generate = super::render_summary(&state, Some(&bump_files(0, true, Some("abc123"))));
        assert!(
            generate.contains(
                "; `oakum generate --from abc123` writes them from conventional commits."
            ),
            "{generate}"
        );
        let commits = super::render_summary(&state, Some(&NextStep::Commits));
        assert!(
            commits.contains("Name each in a conventional commit"),
            "{commits}"
        );
        assert!(!render_summary(&state).contains("Cover each"));
    }

    fn cargo(name: &str) -> PackageId {
        PackageId::new(Ecosystem::Cargo, name)
    }

    fn quiet_and_released() -> Vec<ChangedPackage> {
        let file = || String::from(".changeset/a.md");
        let releaseless = |hash: &str, kind: &str| {
            CoverSource::commit(hash.to_owned(), Some(kind.to_owned()), BumpLevel::None)
        };
        vec![
            ChangedPackage::new(
                cargo("alpha"),
                Vec::new(),
                vec![CoverSource::file(file(), BumpLevel::Patch)],
                Vec::new(),
                None,
            ),
            ChangedPackage::new(
                cargo("beta"),
                Vec::new(),
                vec![CoverSource::file(file(), BumpLevel::None)],
                Vec::new(),
                None,
            ),
            ChangedPackage::new(
                cargo("delta"),
                vec![cargo("core")],
                vec![
                    releaseless("1111111aaaa", "refactor"),
                    releaseless("2222222bbbb", "refactor"),
                    releaseless("3333333cccc", "test"),
                ],
                Vec::new(),
                None,
            ),
            ChangedPackage::new(
                cargo("demo"),
                Vec::new(),
                vec![CoverSource::EmptyFile { file: file() }],
                Vec::new(),
                None,
            ),
            ChangedPackage::new(
                cargo("epsilon"),
                Vec::new(),
                vec![CoverSource::EmptyFile { file: file() }],
                Vec::new(),
                None,
            ),
        ]
    }

    #[test]
    fn both_renders_escape_a_backtick_in_a_commit_subject() {
        let state = empty_state(
            RenderTarget::Comment,
            CoverageOutcome::Ran(Coverage {
                unmanaged: Vec::new(),
                changed: vec![ChangedPackage::new(
                    cargo("demo"),
                    Vec::new(),
                    Vec::new(),
                    ReleasingCommit::new(
                        String::from("aaaaaaa111"),
                        String::from("fix: odd ` tick"),
                        Some(String::from("fix")),
                        BumpLevel::Patch,
                    )
                    .into_iter()
                    .collect(),
                    Some(String::from("oakum add --packages demo:patch")),
                )],
            }),
        );
        for render in [
            render_summary(&state),
            render_comment(&state).expect("comment"),
        ] {
            assert!(render.contains("\"fix: odd \\` tick\""), "{render}");
        }
    }

    /// A change that releases nothing is the one a reviewer would not see in
    /// the release list, so both renders name it; one that releases, or that
    /// the plan releases another way, is already listed.
    #[test]
    fn a_change_releasing_nothing_is_named_with_what_covers_it() {
        let state = planned_state(CoverageOutcome::Ran(Coverage {
            unmanaged: Vec::new(),
            changed: quiet_and_released(),
        }));
        let summary = render_summary(&state);
        assert!(
            summary.contains(
                "\nChanged, releasing nothing:\n\n\
                 - beta (`cargo`): covered by `none` in `.changeset/a.md`\n\
                 - delta (`cargo`) (via core): covered by commits that release nothing (refactor ×2, test)\n\
                 - epsilon (`cargo`): covered by the empty bump file `.changeset/a.md`\n"
            ),
            "{summary}"
        );
        let comment = render_comment(&state).expect("comment");
        assert!(
            comment.contains(
                "\nChanged, releasing nothing:\n\n\
                 - `beta` (cargo) — covered by `none` in `.changeset/a.md`\n\
                 - `delta` (cargo) (via core) — covered by commits that release nothing (refactor ×2, test)\n\
                 - `epsilon` (cargo) — covered by the empty bump file `.changeset/a.md`\n"
            ),
            "{comment}"
        );
        for render in [summary, comment] {
            assert!(!render.contains("alpha"), "it releases: {render}");
            assert!(
                !render.contains("demo (`cargo`): covered")
                    && !render.contains("`demo` (cargo) — covered"),
                "the plan releases it: {render}"
            );
        }
    }

    fn planned_state(coverage: CoverageOutcome) -> ReleaseState {
        let workspace = Workspace::new([Package::new(
            cargo("demo"),
            Version::new(0, 1, 0),
            ResolvesDependenciesAt::Install,
            true,
            Vec::new(),
        )])
        .expect("workspace");
        let plan = compose(
            &workspace,
            &aggregate([BumpFile {
                id: String::from("other.md"),
                entries: vec![(cargo("demo"), BumpLevel::Patch)],
                note: String::new(),
            }]),
            |_| Versioning::ZeroMajor,
            CascadeAs::Patch,
        )
        .expect("plan");
        ReleaseState::from_plan(&plan, coverage, RenderTarget::Status)
    }

    /// A state with no plan: the shape every branch below turns on.
    fn empty_state(target: RenderTarget, coverage: CoverageOutcome) -> ReleaseState {
        let workspace = Workspace::new([Package::new(
            cargo("demo"),
            Version::new(0, 1, 0),
            ResolvesDependenciesAt::Install,
            true,
            Vec::new(),
        )])
        .expect("workspace");
        let plan = compose(
            &workspace,
            &aggregate([]),
            |_| Versioning::ZeroMajor,
            CascadeAs::Patch,
        )
        .expect("plan");
        ReleaseState::from_plan(&plan, coverage, target)
    }

    fn unmanaged_only() -> Coverage {
        Coverage {
            unmanaged: vec![cargo("beta")],
            changed: Vec::new(),
        }
    }

    #[test]
    fn a_comment_carrying_only_unmanaged_packages_is_not_empty() {
        let body = render_comment(&empty_state(
            RenderTarget::Comment,
            CoverageOutcome::Ran(unmanaged_only()),
        ))
        .expect("a state with something to say renders a body");
        assert!(body.contains("beta"), "{body}");
        assert_ne!(body.trim_end(), PR_PLAN_MARKER);
    }

    /// The pull-request comment is where a commits-only repository reads it;
    /// a coverage look that did not run does not hide it.
    #[test]
    fn a_package_named_by_a_commit_reaches_both_renders() {
        let state = empty_state(RenderTarget::Comment, CoverageOutcome::NotAsked)
            .with_named_unmanaged(vec![cargo("beta")]);
        let body = render_comment(&state).expect("a named package is worth saying");
        assert!(
            body.contains("Named by a commit but not version-managed:\n\n- `beta` (cargo)"),
            "{body}"
        );
        let summary = render_summary(&state);
        assert!(
            summary.contains("Named by a commit but not version-managed: beta (`cargo`)"),
            "{summary}"
        );
    }

    #[test]
    fn a_commit_reaching_no_package_reaches_both_renders() {
        let state = empty_state(RenderTarget::Comment, CoverageOutcome::NotAsked)
            .with_unresolved_scopes(vec![oakum::state::UnresolvedScope {
                commit: String::from("0123456789abcdef"),
                scope: String::from("gamma"),
            }]);
        let line = "- commit 0123456 asks for a release under scope `gamma`";
        let body = render_comment(&state).expect("a dropped release is worth saying");
        assert!(body.contains(line), "{body}");
        assert!(render_summary(&state).contains(line), "{state:?}");
    }

    #[test]
    fn a_package_awaiting_its_tag_reaches_both_renders() {
        let state = empty_state(RenderTarget::Comment, CoverageOutcome::NotAsked)
            .with_awaiting_tag(vec![cargo("alpha")]);
        let body = render_comment(&state).expect("a pending tag is worth saying");
        assert!(
            body.contains("Released, awaiting its tag:\n\n- `alpha` (cargo)"),
            "{body}"
        );
        assert!(
            render_summary(&state).contains("Released, awaiting its tag: alpha (`cargo`)"),
            "{state:?}"
        );
    }

    #[test]
    fn a_release_made_only_of_dependency_updates_says_so_in_both_renders() {
        let state: ReleaseState = serde_json::from_str(
            r#"{"schema_version":1,"target":"comment","uncovered":[],"packages":[
                {"name":"app","ecosystem":"cargo","from":"0.1.0","to":"0.1.1","bump":"patch","source":{"kind":"dependency-update"}}]}"#,
        )
        .expect("state");
        let body = render_comment(&state).expect("a release is worth saying");
        assert!(
            body.contains("- `app` 0.1.0 → 0.1.1 (patch, dependency updates)"),
            "{body}"
        );
        assert!(
            render_summary(&state).contains("| patch | dependency updates |"),
            "{state:?}"
        );
    }

    #[test]
    fn a_unread_package_reaches_both_renders() {
        let state = empty_state(RenderTarget::Comment, CoverageOutcome::NotAsked)
            .with_updates_unread(vec![cargo("alpha")]);
        let body = render_comment(&state).expect("an unread package is worth saying");
        assert!(
            body.contains("Dependency updates not read:\n\n- `alpha` (cargo)"),
            "{body}"
        );
        assert!(
            render_summary(&state).contains("Dependency updates not read: alpha (`cargo`)"),
            "{state:?}"
        );
    }

    #[test]
    fn a_hand_set_version_reaches_both_renders_before_the_release() {
        let planned: ReleaseState = serde_json::from_str(
            r#"{"schema_version":1,"target":"comment","uncovered":[],
                "packages":[{"name":"demo","ecosystem":"cargo","from":"0.1.1","to":"0.1.2",
                             "bump":"patch","source":{"kind":"intent"}}]}"#,
        )
        .expect("state");
        let state = planned.with_hand_set(vec![HandSet::new(
            cargo("demo"),
            Version::new(0, 1, 1),
            String::from("demo (cargo): tag it"),
        )]);
        let body = render_comment(&state).expect("a block is worth saying");
        let block = body.find("- demo (cargo): tag it").expect(&body);
        assert!(
            block < body.find("These packages will release").expect(&body),
            "{body}"
        );
        assert!(
            render_summary(&state).contains("version set by hand; `oakum version` refuses this plan until each is fixed:\n\n- demo (cargo): tag it"),
            "{state:?}"
        );
    }

    #[test]
    fn a_comment_with_nothing_to_say_is_none() {
        let quiet = empty_state(
            RenderTarget::Comment,
            CoverageOutcome::Ran(Coverage::default()),
        );
        assert_eq!(render_comment(&quiet), None);
    }

    /// A look that failed is not a look that found nothing, and the render is
    /// what travels — stderr reaches neither a step summary nor a comment.
    ///
    /// The summary arm is reachable today; the comment arm is not, because
    /// `ci pr-status` passes `CoverageMode::Required` and refuses before it
    /// could build such a state. It guards the renderer against a future caller
    /// choosing `Reported`.
    #[test]
    fn a_failed_coverage_look_is_named_in_both_renders() {
        let failed = empty_state(RenderTarget::Comment, CoverageOutcome::Failed);
        let body = render_comment(&failed).expect("a failed look is worth saying");
        assert!(body.contains("Coverage was not checked"), "{body}");
        assert!(
            render_summary(&empty_state(RenderTarget::Summary, CoverageOutcome::Failed))
                .contains("Coverage was not checked")
        );
    }

    /// The version-PR body renders a plan already in hand: no look was
    /// attempted and none could have been. Blaming git there is a false
    /// sentence in the most-read artifact oakum writes.
    #[test]
    fn a_look_nobody_asked_for_is_not_reported_as_a_failure() {
        let summary = render_summary(&empty_state(
            RenderTarget::Status,
            CoverageOutcome::NotAsked,
        ));
        assert!(
            !summary.contains("Coverage was not checked"),
            "nothing asked, so nothing failed: {summary}"
        );
    }

    #[test]
    fn a_config_that_manages_nothing_is_named_in_both_renders() {
        let state = empty_state(
            RenderTarget::Comment,
            CoverageOutcome::Ran(Coverage::default()),
        )
        .managing_nothing();
        let body = render_comment(&state).expect("a config that can never release is worth saying");
        assert!(body.contains("manages no package on either axis"), "{body}");
        let summary = empty_state(
            RenderTarget::Summary,
            CoverageOutcome::Ran(Coverage::default()),
        )
        .managing_nothing();
        assert!(render_summary(&summary).contains("manages no package on either axis"));
    }

    /// Its sibling. `check` stays silent on an emptied selection, so the render
    /// is the only place a reader learns of it — in both targets, since the
    /// comment render is what a pull request shows.
    #[test]
    fn an_emptied_selection_is_named_in_both_renders() {
        let summary = render_summary(
            &empty_state(RenderTarget::Status, CoverageOutcome::NotAsked).selection_emptied(),
        );
        assert!(
            summary.contains("`include`/`exclude` leave no package selected"),
            "{summary}"
        );
        assert!(
            summary.contains("`check` does not refuse this"),
            "the divergence is the point: {summary}"
        );
        let comment = render_comment(
            &empty_state(RenderTarget::Comment, CoverageOutcome::NotAsked).selection_emptied(),
        )
        .expect("an emptied selection is worth a comment");
        assert!(
            comment.contains("`include`/`exclude` leave no package selected"),
            "{comment}"
        );
    }
}