(8556048) Take a relation off with relate --clear, and bump to 0.32.0

`relate` only added. A `--blocked-by` pointed at the wrong ticket was on that
ticket forever, refusing every move it made until the target was done or `-f`
was passed again, and a target that was deleted did not clean up either: the
board carried a dead edge that nothing could clear and every later read of the
ticket paid for.

`--clear <kind> <target>` takes one off. It is on `relate` rather than on `set`
for the reason `RELATIONS` is out of `section_args`: a relation names a target
that has to be resolved first, so one writer owns both directions, the way
`chown` owns setting an owner and clearing one. It names the target and not
just the kind, because a ticket can hold several relations of one kind and
emptying all of them is not what anybody is asking for. That is also why it is
not spelled the way `set --clear` is, which names a field and empties it whole.

Both spellings of the kind are taken, `blocked-by` from the flag and
`blocked by` from the label: both are in front of the reader, the flag being
what recorded the relation and the label what `show` prints and the file
stores, so refusing the printed form would trap anyone clearing a row they had
just read. `RelationKind::flag` is a match rather than a `replace` on the
label, so the flag, the `--clear` value and the completion list cannot drift.

`find_relation` searches the ticket's own edges by id prefix before it searches
the board, and that order is the feature rather than an optimisation: no search
of the board reaches a target whose ticket is gone, so the stored-target tier
is the only thing that can clear a dangling edge, which is the case most likely
to need clearing. Two stored targets under one prefix name the candidates
instead of guessing, as an ambiguous ticket search already does.

An edge the ticket does not hold reports no change, and a target naming nothing
at all is an error. The two are different facts: the first is the state the
caller asked for, and the second is a typo that a no-op would swallow. The
resolver's own reason is carried through, so an ambiguous search says it is
ambiguous rather than being reported as nothing found.

Recording and clearing the same relation in one call is refused, and the check
runs on what was *asked* for and not on what would be written. A relation
already in the file is not among the additions, so comparing against those
would have let `--blocked-by X --clear blocked-by X` quietly remove it.

Removals rewrite the section from what is left and additions are appended to
that, in that order and in two passes: a call with no `--clear` then takes
exactly the path it always took. The last edge leaves the placeholder, which is
the line `append` treats as no content, so the next `relate` replaces it rather
than writing underneath it.

The two values are one flag, so clap cannot type them apart. `num_args = 2` is
per occurrence, which makes an odd number a usage error and every chunk a full
pair, and `cleared` parses the kind before the ticket is resolved. Nothing is
logged, in either direction, since `relate` never has: a log recording only the
destructive half would read as though the additions had never happened.

`chowns_clear_is_completed_with_tickets_and_sets_is_not` found the first rule
carrying `-l clear` and there are now three, on three commands, each taking
something different. It is `each_clear_flag_is_completed_for_its_own_command`,
scoped per command, and `relate --clear` offers the kinds rather than a board
listing, since tickets where the kind goes would be candidates it refuses.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ansho Rei
2026-08-25 12:13:37 +02:00
co-authored by Claude Opus 5
parent 7994d98913
commit 0f0767ac00
10 changed files with 664 additions and 23 deletions
+326
View File
@@ -388,3 +388,329 @@ fn a_line_that_is_not_a_relation_is_an_error() {
assert!(stderr.contains("is not a relation"), "{stderr}");
assert!(stderr.contains("The gated one"), "{stderr}");
}
// --------------------------------------------------------------- clearing --
/// Two blockers, one taken off by name. The other survives, which is the whole reason
/// `--clear` names the target and not just the kind: a ticket can hold several of one
/// kind, and emptying all of them is not usually what is wanted.
#[test]
fn a_relation_is_taken_off_by_its_kind_and_its_target() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(
&temp,
&[
"relate",
GATED,
"--blocked-by",
BLOCKER,
"--blocked-by",
FIXED,
],
);
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by", BLOCKER]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(stdout(&out).contains("Cleared blocked by"), "{}", stdout(&out));
let content = ticket(&worklane, GATED);
assert!(
!content.contains(BLOCKER),
"the cleared relation is still there: {content}"
);
assert!(
content.contains(&format!("- blocked by {}", FIXED)),
"the other one went too: {content}"
);
}
/// Both spellings of the kind, because both are in front of the reader: `blocked-by` is
/// the flag that recorded it and `blocked by` is what `show` prints and what the file
/// stores. Refusing the form the tool itself prints would be a trap.
#[test]
fn the_kind_takes_the_flag_spelling_and_the_label_spelling() {
for kind in ["blocked-by", "blocked by", "Blocked-By"] {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let out = run(&temp, &["relate", GATED, "--clear", kind, BLOCKER]);
assert!(out.status.success(), "{kind}: {}", String::from_utf8_lossy(&out.stderr));
assert!(!ticket(&worklane, GATED).contains(BLOCKER), "{kind} did not clear it");
}
}
/// The target is a ticket argument like any other, so it resolves by title too.
#[test]
fn a_cleared_target_resolves_by_title() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by", "blocker"]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(!ticket(&worklane, GATED).contains(BLOCKER));
}
/// A relation the ticket does not hold is the state the caller asked for, so it reports
/// no change rather than failing. The target resolves; the edge is simply not there.
#[test]
fn clearing_a_relation_the_ticket_does_not_hold_reports_no_change() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let before = ticket(&worklane, GATED);
// A kind it does not hold at all, and a target it holds under another kind.
for args in [["relates-to", BLOCKER], ["blocked-by", FIXED]] {
let out = run(&temp, &["relate", GATED, "--clear", args[0], args[1]]);
assert!(out.status.success(), "{args:?}: {}", String::from_utf8_lossy(&out.stderr));
assert!(stdout(&out).contains("No changes"), "{args:?}: {}", stdout(&out));
assert_eq!(ticket(&worklane, GATED), before, "{args:?} wrote something");
}
}
/// A search naming nothing at all is a typo, not a state to report. Reporting no change
/// for it would swallow it, which is the one thing the no-change rule must not do.
#[test]
fn clearing_a_target_that_names_nothing_is_an_error() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let before = ticket(&worklane, GATED);
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by", "9999zzzz"]);
assert!(!out.status.success(), "{}", stdout(&out));
assert_eq!(ticket(&worklane, GATED), before);
}
/// The inverse is derived by a scan rather than stored, so taking the stored line off is
/// what takes it off both ends. The other ticket's own file was never touched either way.
#[test]
fn the_derived_inverse_goes_with_the_stored_line() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let untouched = ticket(&worklane, BLOCKER);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let shown = stdout(&run(&temp, &["show", BLOCKER]));
assert!(shown.contains("blocks"), "the inverse was never derived: {shown}");
run(&temp, &["relate", GATED, "--clear", "blocked-by", BLOCKER]);
let after = stdout(&run(&temp, &["show", BLOCKER]));
assert!(!after.contains("blocks"), "the inverse outlived the stored line: {after}");
assert_eq!(ticket(&worklane, BLOCKER), untouched, "the other ticket was written to");
}
/// The case most likely to need clearing, and the only one no search of the board can
/// reach: the target's ticket is gone, so the prefix tier over the stored targets is what
/// finds it. `show` renders it as `_missing_` until it is cleared, and `mv` warns about it
/// on every move.
#[test]
fn a_dangling_relation_can_be_cleared() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
fs::remove_file(find(&worklane, BLOCKER)).unwrap();
assert!(
stdout(&run(&temp, &["show", GATED])).contains("_missing_"),
"the fixture is not dangling"
);
// By the short id, which is all a reader has once the title is gone.
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by", &BLOCKER[..7]]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert!(!ticket(&worklane, GATED).contains(BLOCKER), "{}", ticket(&worklane, GATED));
assert!(!stdout(&run(&temp, &["show", GATED])).contains("_missing_"));
}
/// A prefix short enough to reach two stored targets names the candidates rather than
/// guessing, the way an ambiguous ticket search does, and writes nothing.
#[test]
fn an_ambiguous_prefix_over_the_stored_targets_names_the_candidates() {
const ONE: &str = "aaaa1111-0000-4000-8000-000000000000";
const TWO: &str = "aaaa2222-0000-4000-8000-000000000000";
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
create_ticket(&worklane, "backlog", "Twin one", ONE);
create_ticket(&worklane, "backlog", "Twin two", TWO);
run(&temp, &["relate", GATED, "--blocked-by", ONE, "--blocked-by", TWO]);
let before = ticket(&worklane, GATED);
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by", "aaaa"]);
assert!(!out.status.success(), "{}", stdout(&out));
// The stored-target tier and not the board search, which would find the same two
// tickets by their own uuid prefix and report them the same way. The wording is what
// tells the two apart, so it is what this asserts.
let reason = String::from_utf8_lossy(&out.stderr);
assert!(
reason.contains("'blocked by' relations on"),
"the board answered instead: {reason}"
);
assert!(reason.contains(&ONE[..7]) && reason.contains(&TWO[..7]), "{reason}");
assert_eq!(ticket(&worklane, GATED), before);
}
/// The last edge leaves the placeholder `add` writes, not an empty body, so the section
/// can be written to again without the placeholder ending up above what follows it.
#[test]
fn clearing_the_last_relation_leaves_the_placeholder() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
run(&temp, &["relate", GATED, "--clear", "blocked-by", BLOCKER]);
let content = ticket(&worklane, GATED);
assert!(
content.contains(
"## Relations
_No relations._
"
),
"{content}"
);
// And it is written to again without the placeholder being left behind.
run(&temp, &["relate", GATED, "--relates-to", FIXED]);
let again = ticket(&worklane, GATED);
assert!(again.contains(&format!("- relates to {}", FIXED)), "{again}");
assert!(
!again.contains("_No relations._"),
"the placeholder outlived the edge: {again}"
);
}
/// The same file surgery `relate` already does, so the tick, the handwritten section and
/// the prose survive a clear the way they survive a record.
#[test]
fn clearing_leaves_everything_it_was_not_asked_about_alone() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(
&temp,
&[
"relate",
GATED,
"--blocked-by",
BLOCKER,
"--relates-to",
FIXED,
],
);
run(&temp, &["relate", GATED, "--clear", "blocked-by", BLOCKER]);
let content = ticket(&worklane, GATED);
assert!(content.contains("- [x] Crit one"), "the tick was lost: {content}");
assert!(
content.contains("## Notes\nA handwritten note the tool knows nothing about.\n"),
"the unknown section was lost: {content}"
);
assert!(content.contains("1. Step one"), "{content}");
assert!(content.contains("- **Owner**: alice"), "{content}");
assert!(content.contains("- **Status**: backlog"), "{content}");
}
/// One call does both, and each half reports itself in its own words.
#[test]
fn one_call_records_and_clears_different_relations() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let out = run(
&temp,
&[
"relate",
GATED,
"--clear",
"blocked-by",
BLOCKER,
"--relates-to",
FIXED,
],
);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
let reported = stdout(&out);
assert!(reported.contains("Recorded relates to"), "{reported}");
assert!(reported.contains("Cleared blocked by"), "{reported}");
let content = ticket(&worklane, GATED);
assert!(!content.contains(BLOCKER), "{content}");
assert!(content.contains(&format!("- relates to {}", FIXED)), "{content}");
}
/// Recording and clearing the same relation in one call is refused outright, the way
/// `set` refuses a field it is also replacing: nothing is written rather than one of the
/// two silently winning.
///
/// It has to be caught on what the call *asked* for and not on what it would write. A
/// relation already in the file is not among the additions, so comparing against those
/// would let this call quietly remove one.
#[test]
fn recording_and_clearing_the_same_relation_is_refused() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let before = ticket(&worklane, GATED);
let out = run(
&temp,
&[
"relate",
GATED,
"--blocked-by",
BLOCKER,
"--clear",
"blocked-by",
BLOCKER,
],
);
assert!(!out.status.success(), "{}", stdout(&out));
assert!(
String::from_utf8_lossy(&out.stderr).contains("nothing was written"),
"{}",
String::from_utf8_lossy(&out.stderr)
);
assert_eq!(ticket(&worklane, GATED), before, "the relation was removed anyway");
}
/// A kind that is not one of the three is refused before the ticket is resolved, so
/// nothing is written. Exit 1 rather than clap's 2: the value is one of a pair clap
/// cannot type apart, so the kind is parsed by `RelateArgs::cleared`.
#[test]
fn an_unknown_kind_in_a_clear_is_refused() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
run(&temp, &["relate", GATED, "--blocked-by", BLOCKER]);
let before = ticket(&worklane, GATED);
let out = run(&temp, &["relate", GATED, "--clear", "depends-on", BLOCKER]);
assert!(!out.status.success(), "{}", stdout(&out));
let reason = String::from_utf8_lossy(&out.stderr);
assert!(reason.contains("not a relation kind"), "{reason}");
// The message names the three, in the spelling the flags and the completions use.
for kind in ["blocked-by", "regression-of", "relates-to"] {
assert!(reason.contains(kind), "{reason}");
}
assert_eq!(ticket(&worklane, GATED), before);
}
/// `--clear` takes exactly two values per occurrence, so clap refuses an odd number with
/// a usage error and nothing reaches the handler.
#[test]
fn a_clear_with_one_value_is_a_usage_error() {
let temp = TempDir::new().unwrap();
let worklane = board(&temp);
let before = ticket(&worklane, GATED);
let out = run(&temp, &["relate", GATED, "--clear", "blocked-by"]);
assert_eq!(out.status.code(), Some(2), "{}", stdout(&out));
assert_eq!(ticket(&worklane, GATED), before);
}