(c680e24) Write a warning through a second stream on the sink, and bump to 0.33.2

check_blockers reported a blocker the board does not hold with eprintln!,
the one print site fa5662a left behind: a helper had no sink to reach, and
what it wrote was stderr rather than stdout. Harmless while main was the
only caller, and since 53ffb94 the command prompt runs the same handlers,
where stderr is the alternate screen with the columns on it. ratatui does
not repaint a cell it believes is unchanged, so the fragment stayed until
something else redrew them.

Sink carries two writers instead of one, because the CLI's two streams are
two: Sink::std hands the answer to stdout and an aside to stderr, so a
shell reads the same line on the same stream, and the integration test now
asserts that stderr whole rather than searching it. Sink::buffer holds its
warnings instead, and Board::run reads them back with Sink::warnings and
puts them above the answer on both outcomes -- a mv that warns about a
dangling blocker and is then refused by a real one wrote the aside first,
and it says why the refusal names one blocker and the ticket records two.

check_blockers and check_dependents both take the sink now, so their
refusals take the colour from it as well, rather than asking the process
about a stdout the board is not writing to.

no_handler_or_helper_reaches_a_print_macro walks src for the next print
site, each file cut at its own test module, since the rule is about every
future site rather than the one that broke.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ansho Rei
2026-09-10 11:53:10 +02:00
co-authored by Claude Opus 5
parent ead3c4340d
commit a017f9002e
8 changed files with 393 additions and 31 deletions
+183 -14
View File
@@ -501,7 +501,18 @@ fn move_ticket_file(
/// A target the board does not have warns and allows the move. Refusing there would
/// wedge the ticket behind a bookkeeping fault with no way out but `--force`, and a
/// dangling uuid is not a dependency.
fn check_blockers(worklane_dir: &Path, content: &str, title: &str, target: Status) -> Result<()> {
///
/// The warning goes through the `sink` rather than through `eprintln!`, which is why a
/// helper that says nothing on the happy path takes one at all: this runs from the
/// board's command prompt as well as from `main`, and there the process's stderr is the
/// alternate screen. The refusal takes its colour from the sink for the same reason.
fn check_blockers(
worklane_dir: &Path,
content: &str,
title: &str,
target: Status,
sink: &mut Sink,
) -> Result<()> {
let edges: Vec<Relation> = parse_relations(content, title)?
.into_iter()
.filter(|relation| relation.kind == RelationKind::BlockedBy)
@@ -522,15 +533,15 @@ fn check_blockers(worklane_dir: &Path, content: &str, title: &str, target: Statu
Some(blocker) if !blocks_move(target, &blocker.status) => {}
Some(blocker) => behind.push(format!(
" ({}) {} [{}]",
color_text(short_id(&blocker.uuid), Color::Red),
sink.color(short_id(&blocker.uuid), Color::Red),
blocker.title,
color_text(&blocker.status, Color::Orange),
sink.color(&blocker.status, Color::Orange),
)),
None => eprintln!(
None => sink.warnln(&format!(
"Warning: ticket '{}' is blocked by {}, which is not on the board.",
title,
short_id(&edge.target),
),
))?,
}
}
@@ -544,8 +555,8 @@ fn check_blockers(worklane_dir: &Path, content: &str, title: &str, target: Statu
// next stage is otherwise told nothing about what changed.
Err(anyhow!(
"Cannot move '{}' to {} while it is blocked by:\n{}\nA ticket cannot move ahead of what it waits on. Use --force (-f) to move it anyway.",
color_text(title, Color::Green),
color_text(target.as_str(), Color::Orange),
sink.color(title, Color::Green),
sink.color(target.as_str(), Color::Orange),
behind.join("\n"),
))
}
@@ -558,7 +569,11 @@ fn check_blockers(worklane_dir: &Path, content: &str, title: &str, target: Statu
///
/// Tickets already done or discarded do not hold it up: a dependency that was satisfied
/// or abandoned is nobody's plan anymore.
fn check_dependents(worklane_dir: &Path, uuid: &str, title: &str) -> Result<()> {
///
/// The `sink` is here for the colour alone, the rule [`check_blockers`] follows: this
/// refusal is drawn by the board as well as printed by the CLI, and a helper that asks
/// the process about its stdout answers about a terminal the message is not going to.
fn check_dependents(worklane_dir: &Path, uuid: &str, title: &str, sink: &mut Sink) -> Result<()> {
let index = RelationIndex::load(worklane_dir)?;
// Every open dependent, not the first, for the reason `check_blockers` names them
@@ -575,9 +590,9 @@ fn check_dependents(worklane_dir: &Path, uuid: &str, title: &str) -> Result<()>
.map(|ticket| {
format!(
" ({}) {} [{}]",
color_text(short_id(&ticket.uuid), Color::Red),
sink.color(short_id(&ticket.uuid), Color::Red),
ticket.title,
color_text(&ticket.status, Color::Orange),
sink.color(&ticket.status, Color::Orange),
)
})
.collect();
@@ -588,7 +603,7 @@ fn check_dependents(worklane_dir: &Path, uuid: &str, title: &str) -> Result<()>
Err(anyhow!(
"Cannot discard '{}' while open tickets are blocked by it:\n{}\nUse --force (-f) to discard it anyway.",
color_text(title, Color::Green),
sink.color(title, Color::Green),
waiting.join("\n"),
))
}
@@ -694,8 +709,10 @@ pub fn cmd_mv(args: &MvArgs, start: &Path, sink: &mut Sink) -> Result<()> {
// it.
if !force {
match discarding {
true => check_dependents(&worklane_dir, &parse_ticket_field(&resolved, "ID"), &title)?,
false => check_blockers(&worklane_dir, &resolved, &title, *target)?,
true => {
check_dependents(&worklane_dir, &parse_ticket_field(&resolved, "ID"), &title, sink)?
}
false => check_blockers(&worklane_dir, &resolved, &title, *target, sink)?,
}
}
@@ -2231,6 +2248,12 @@ mod sink_tests {
}
fn ticket(dir: &Path, status: &str, uuid: &str) {
ticket_with(dir, status, uuid, "");
}
/// The same ticket with `extra` appended, for a test about a section the plain
/// fixture does not carry.
fn ticket_with(dir: &Path, status: &str, uuid: &str, extra: &str) {
fs::write(
dir.join(status).join(format!("{}_ticket.md", uuid)),
format!(
@@ -2246,14 +2269,31 @@ mod sink_tests {
- **Tags**: _None_\n\
- **Owner**: alice\n\
- **Created At**: 2026-08-21 02:10:17\n\
- **Status**: {status}\n",
- **Status**: {status}\n\
{extra}",
u = uuid,
status = status,
extra = extra,
),
)
.unwrap();
}
/// A project directory with a real board under it, for a handler that takes the path
/// a shell would have been run from and walks up from it. [`temp_worklane`] is the
/// board itself, which is what a handler already handed one takes.
///
/// A [`Fixture`], so the tree goes when the test does whether it passed or not, which
/// is the rule for a unit-test fixture in this crate.
fn temp_project() -> Fixture {
let root = Fixture::new("wl-sink-project").child("project");
let dir = root.join(".worklane");
for status in status_dirs() {
fs::create_dir_all(dir.join(status)).unwrap();
}
root
}
/// A handler writes through the sink it is handed, and a caller can read the bytes
/// back without a terminal or a real stdout.
#[test]
@@ -2314,4 +2354,133 @@ mod sink_tests {
fs::remove_dir_all(&dir).ok();
}
/// The aside `check_blockers` writes for a blocker the board does not hold goes to
/// the sink's warnings, and not into what the caller collects as the answer.
///
/// Two destinations because the CLI's two are two: this has always been stderr and
/// the answer stdout, and the board reads the answer back to draw it, so a warning
/// folded into it would be indistinguishable from what the command said. What it
/// must not be is an `eprintln!`, which reaches the process's own stderr — under the
/// board that is the alternate screen with the columns on it.
#[test]
fn a_dangling_blocker_warns_through_the_sink() {
let root = temp_project();
let dir = root.join(".worklane");
ticket_with(
&dir,
"backlog",
"aaaa1111-aaaa-4000-8000-000000000000",
"\n## Relations\n\n- blocked by cccc3333-cccc-4000-8000-000000000000\n",
);
let args = MvArgs {
ticket: "aaaa1111".to_string(),
status: Status::Committed,
force: false,
actor: None,
actor_from_git: false,
reason: None,
};
let mut buf = Vec::new();
let warned = {
let mut sink = Sink::buffer(&mut buf);
// A dangling uuid is a bookkeeping fault rather than a dependency, so the
// move happens and the warning is the whole of what is said about it.
cmd_mv(&args, &root, &mut sink).unwrap();
sink.warnings()
};
assert!(
warned.contains("not on the board"),
"the warning did not reach the sink:\n{warned}"
);
let out = String::from_utf8(buf).unwrap();
assert!(out.contains("Moved ticket"), "the move said nothing:\n{out}");
assert!(
!out.contains("not on the board"),
"the warning landed in the answer:\n{out}"
);
}
/// A sink whose warnings have a stream of their own holds nothing back: those bytes
/// are gone to stderr, which is what [`Sink::std`] is for. Read back as empty rather
/// than as a copy, since a caller acting on both would report the warning twice.
#[test]
fn a_sink_with_a_stream_for_its_warnings_holds_none() {
let mut answer = Vec::new();
let mut aside = Vec::new();
let mut sink = Sink::with_warnings(Box::new(&mut answer), Box::new(&mut aside), false);
sink.warnln("Warning: a blocker nothing holds").unwrap();
sink.writeln("Moved ticket").unwrap();
assert_eq!(sink.warnings(), "", "a warning with a stream was held as well as sent");
sink.flush().unwrap();
drop(sink);
assert_eq!(String::from_utf8(aside).unwrap(), "Warning: a blocker nothing holds\n");
assert_eq!(String::from_utf8(answer).unwrap(), "Moved ticket\n");
}
/// No handler and no helper reaches a print macro. Nowhere in `src`, not only in
/// this file.
///
/// The caller chooses where a command's words go — `main` its own stdout and stderr,
/// the board a buffer it reads back and draws — and a `print!` writes to the
/// process's streams instead, which under the board is the alternate screen with the
/// columns on it. That is c680e24: one `eprintln!` in `check_blockers` outlived
/// fa5662a because a helper had no sink to reach, and ratatui does not repaint a cell
/// it believes is unchanged, so the fragment stayed on the columns until something
/// else redrew them.
///
/// Over the directory rather than over a list of `include_str!`s, so a module added
/// tomorrow is scanned the day it is added: a list is what the fifty-first print site
/// hides behind. Each file is cut at its own test module, and comments are dropped,
/// because the docs around here name these macros to say why they are not called.
#[test]
fn no_handler_or_helper_reaches_a_print_macro() {
// The one site outside a test module that may, and it is not output: the fixture
// guard naming a directory it was told to leave behind, for the person reading the
// run rather than for anything collecting an answer.
let allowed = "eprintln!(\"kept fixture {}\", self.root.display());";
let mut printing: Vec<String> = Vec::new();
for entry in fs::read_dir(concat!(env!("CARGO_MANIFEST_DIR"), "/src")).unwrap() {
let path = entry.unwrap().path();
if path.extension().and_then(|ext| ext.to_str()) != Some("rs") {
continue;
}
let source = fs::read_to_string(&path).unwrap();
let name = path.file_name().unwrap().to_string_lossy().to_string();
printing.extend(
body_of(&source)
.map(str::trim)
.filter(|line| !line.starts_with("//") && *line != allowed)
.filter(|line| {
["print!(", "println!(", "eprint!(", "eprintln!("]
.iter()
.any(|macro_call| line.contains(macro_call))
})
.map(|line| format!("{name}: {line}")),
);
}
assert!(
printing.is_empty(),
"a print macro writes to the process's own streams, which under the board is \
the alternate screen. Take a `Sink` and use `writeln` for an answer or \
`warnln` for an aside:\n{printing:#?}"
);
}
/// A file's lines up to its test module, which in this crate is the only inline
/// `mod` at column 0. A file's own assertions are allowed to name a macro the file
/// may not call, this test's own body first among them.
fn body_of(source: &str) -> impl Iterator<Item = &str> {
source
.lines()
.take_while(|line| !(line.starts_with("mod ") && line.ends_with(" {")))
}
}
+98 -4
View File
@@ -2535,14 +2535,22 @@ impl Board {
.filter(|(uuid, _)| !is_unknown_value(uuid));
let mut buffer: Vec<u8> = Vec::new();
let outcome = {
let (outcome, warned) = {
let mut sink = Sink::buffer(&mut buffer);
crate::dispatch(command, &root, &mut sink).and_then(|()| sink.flush())
let outcome = crate::dispatch(command, &root, &mut sink).and_then(|()| sink.flush());
// Read on both outcomes and reported on both: a `mv` that warns about a
// dangling blocker and is then refused by a real one wrote the warning
// first, and dropping it there would lose the half that says why the
// refusal names one blocker and the ticket records two.
(outcome, sink.warnings())
};
// The warning ahead of the answer, the order the handler wrote them in and the
// order a shell shows the two streams in.
//
// Plain by construction, since the sink is: stripped anyway, because an escape
// drawn into a ratatui paragraph is printed rather than obeyed, and this is the
// one seam where a handler's bytes become a frame.
let said = without_escapes(&String::from_utf8_lossy(&buffer))
let said = without_escapes(&format!("{warned}{}", String::from_utf8_lossy(&buffer)))
.trim_end()
.to_string();
@@ -2556,7 +2564,14 @@ impl Board {
let moved = held.and_then(|(uuid, id)| self.reselect(&uuid, &id, screen));
match outcome {
Err(err) => self.notice = Some(Notice::failed(error_lines(&err))),
// The warning above the refusal, the order they were written in.
Err(err) => {
let failure = match said.is_empty() {
true => error_lines(&err),
false => format!("{said}\n{}", error_lines(&err)),
};
self.notice = Some(Notice::failed(failure));
}
Ok(()) => {
self.prompt = None;
let words = match said.is_empty() {
@@ -8226,6 +8241,85 @@ approach";
);
}
/// A warning comes back with the answer instead of going to stderr, which under the
/// board is the alternate screen: `eprintln!` drew the line straight onto the
/// columns, and ratatui does not repaint a cell it believes is unchanged, so the
/// fragment stayed there until something else redrew them. That is c680e24.
///
/// Asserted on the notice for the reason `the_footer_reports_the_handlers_own_words`
/// is: the words being *there* is what says they were collected rather than printed.
#[test]
fn a_warning_is_reported_with_the_answer_rather_than_printed() {
let (root, mut board) = runnable();
write_ticket(
&root.join(".worklane"),
"backlog",
WAITER,
"The waiter",
&blocked_by(ELSEWHERE),
);
// A dangling blocker is a bookkeeping fault rather than a dependency, so the
// move happens and the warning is the whole of what is said about it.
run_line(&mut board, "mv bbbbbbb --status committed");
let notice = board.notice.as_ref().expect("the command said nothing");
assert!(!notice.failed, "a dangling blocker refused the move: {}", notice.text);
assert_eq!(column_of(&board, "The waiter"), Some("committed"));
let warning = notice.text.find("not on the board");
let answer = notice.text.find("Moved ticket");
assert!(warning.is_some(), "the warning never reached the board: {}", notice.text);
assert!(
warning < answer,
"the aside was not put above the answer it came before: {}",
notice.text
);
let screen = screen_text(&board);
for line in notice.lines() {
assert!(screen.contains(line.trim()), "`{line}` never reached the frame:\n{screen}");
}
}
/// Warned and then refused, which is one blocker the board does not hold and one it
/// does. Both are reported: the refusal names the blocker in the way and the ticket
/// records two, so dropping the aside is dropping the answer to why.
#[test]
fn a_refused_move_keeps_the_warning_that_came_before_it() {
let (root, mut board) = runnable();
write_ticket(
&root.join(".worklane"),
"backlog",
WAITER,
"The waiter",
// `Alpha first`, which `runnable` leaves in the backlog: a blocker a ticket
// may stand level with and not move ahead of.
&format!(
"\n## Relations\n\n- blocked by {ELSEWHERE}\n\
- blocked by 11111111-0000-4000-8000-000000000000\n"
),
);
run_line(&mut board, "mv bbbbbbb --status committed");
let notice = board.notice.as_ref().expect("the refusal said nothing");
assert!(notice.failed, "a refused move was reported as a success");
assert_eq!(
column_of(&board, "The waiter"),
Some("backlog"),
"the move happened anyway"
);
let warning = notice.text.find("not on the board");
let refusal = notice.text.find("Cannot move");
assert!(
warning.is_some(),
"the warning was dropped on the error path: {}",
notice.text
);
assert!(refusal.is_some(), "the refusal was dropped: {}", notice.text);
assert!(warning < refusal, "the aside came after the refusal: {}", notice.text);
}
/// A handler that errors leaves the prompt open with the line exactly as it was: the
/// usual cause is an ambiguous id, and the fix is two more characters rather than the
/// whole line retyped from `:`.
+94 -7
View File
@@ -349,12 +349,33 @@ pub fn without_escapes(text: &str) -> String {
/// `use_color` is the sink's answer, not a read of [`should_use_colors`]: a process
/// whose stdout is a pipe still wants colour when the sink is a buffer a renderer
/// will colour itself, and the board wants plain text however the terminal answers.
///
/// A warning is the second stream, [`Warnings`], for the same reason the first one
/// exists: `eprintln!` in a helper reaches the process's stderr, which under the board
/// is the alternate screen.
pub struct Sink<'a> {
writer: Box<dyn Write + 'a>,
/// Where a warning goes, which is not where the answer goes.
warnings: Warnings<'a>,
/// Whether the bytes this sink writes carry colour escapes.
pub use_color: bool,
}
/// What a sink does with a warning: the aside a command writes on its way to an
/// answer, which the reader wants and no caller parses.
///
/// Two streams rather than one, because the CLI's two are two: a warning has always
/// gone to stderr and the answer to stdout, and [`Sink::std`] cannot fold them
/// together without changing what a shell reads. Under the board neither is a stream
/// at all — stdout is the alternate screen in raw mode, and so is stderr — so the
/// warning is held instead and the board reports it beside the answer.
enum Warnings<'a> {
/// A writer of its own: `main`'s stderr.
Stream(Box<dyn Write + 'a>),
/// Kept in memory for a caller that reads it back through [`Sink::warnings`].
Held(Vec<u8>),
}
impl<'a> Sink<'a> {
/// The process's stdout, coloured by what the terminal wants.
///
@@ -362,8 +383,14 @@ impl<'a> Sink<'a> {
/// command wrote to stdout through `println!`, and this sink writes to the same
/// stdout through the same [`paint`].
pub fn std() -> Sink<'static> {
// Through `new` so the process's stdout is just another writer the sink wraps.
Sink::new(Box::new(std::io::stdout()), should_use_colors())
// The one sink whose warnings have a stream to go to, and the reason there is a
// choice at all: stderr here is a terminal or a pipe the caller is reading, and
// holding a warning back would take it off a shell's screen.
Sink::with_warnings(
Box::new(std::io::stdout()),
Box::new(std::io::stderr()),
should_use_colors(),
)
}
/// An in-memory buffer, plain, for a test or a caller that colours the text
@@ -373,15 +400,33 @@ impl<'a> Sink<'a> {
/// and the board styles them with ratatui, which is also why it must not be handed
/// a coloured one — a paragraph prints an escape rather than obeying it.
pub fn buffer(target: &'a mut Vec<u8>) -> Sink<'a> {
Sink::new(Box::new(target), false)
}
/// Any writer, with the colour decision given. Its warnings are held: a caller
/// that named one destination named nowhere for an aside to go, and `main`'s
/// stderr is [`Sink::std`]'s alone.
pub fn new(writer: Box<dyn Write + 'a>, use_color: bool) -> Sink<'a> {
Sink {
writer: Box::new(target),
use_color: false,
writer,
warnings: Warnings::Held(Vec::new()),
use_color,
}
}
/// Any writer, with the colour decision given.
pub fn new(writer: Box<dyn Write + 'a>, use_color: bool) -> Sink<'a> {
Sink { writer, use_color }
/// An answer and the asides that go with it, as two writers, with the colour
/// decision given. What [`Sink::std`] is built from, and the only way to a sink
/// whose warnings leave it rather than being held.
pub fn with_warnings(
writer: Box<dyn Write + 'a>,
warnings: Box<dyn Write + 'a>,
use_color: bool,
) -> Sink<'a> {
Sink {
writer,
warnings: Warnings::Stream(warnings),
use_color,
}
}
/// The writer, for a caller that already knows how to fill it (the completions
@@ -404,9 +449,51 @@ impl<'a> Sink<'a> {
Ok(())
}
/// Write `text` and a newline as a warning, the way `eprintln!` did.
///
/// For the aside a command makes on its way to an answer: something the reader
/// should know that does not stop the command and that nothing reading its output
/// should have to skip past. A handler reaching `eprintln!` instead wrote straight
/// to the process's stderr, which under the board is the alternate screen, and
/// ratatui does not repaint a cell it believes is unchanged — so the fragment stayed
/// on the columns until something else redrew them.
pub fn warnln(&mut self, text: &str) -> Result<()> {
match &mut self.warnings {
Warnings::Stream(writer) => {
writer.write_all(text.as_bytes())?;
writer.write_all(b"\n")?;
}
Warnings::Held(bytes) => {
bytes.extend_from_slice(text.as_bytes());
bytes.push(b'\n');
}
}
Ok(())
}
/// What this sink held back, for the caller that reads its warnings rather than
/// letting them reach a stream.
///
/// Empty for a sink whose warnings have somewhere of their own to go, since those
/// bytes are already gone. Read it after the handler returns and on both outcomes:
/// a command that warns and is then refused wrote both, and the warning is the half
/// that says why the refusal names one blocker and not two.
pub fn warnings(&self) -> String {
match &self.warnings {
Warnings::Stream(_) => String::new(),
Warnings::Held(bytes) => String::from_utf8_lossy(bytes).to_string(),
}
}
/// Flush the writer, so a prompt reaches the terminal before a read.
///
/// Both writers: a warning left in stderr's buffer while the answer reached stdout
/// is a warning the reader sees after the sentence it was about, or not at all.
pub fn flush(&mut self) -> Result<()> {
self.writer.flush()?;
if let Warnings::Stream(writer) = &mut self.warnings {
writer.flush()?;
}
Ok(())
}