(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
+30 -1
View File
@@ -852,12 +852,17 @@ pub struct AppendArgs {
/// Each flag repeats, so several relations of one kind land in a single call. The
/// targets are ticket searches, resolved by the same three tiers every other ticket
/// argument is, and stored as the target's uuid.
///
/// `--clear` is the other direction, and it is here rather than on `set` for the reason
/// Relations is absent from `section_args`: a relation names a target that has to be
/// resolved first, so its one writer owns both adding and removing, the way `chown` owns
/// both setting an owner and clearing one.
#[derive(clap::Args)]
#[command(group(
clap::ArgGroup::new("relation_kinds")
.required(true)
.multiple(true)
.args(["blocked_by", "regression_of", "relates_to"])
.args(["blocked_by", "regression_of", "relates_to", "clear"])
))]
pub struct RelateArgs {
/// Ticket UUID or title
@@ -874,6 +879,18 @@ pub struct RelateArgs {
/// Ticket this one is merely related to. Symmetric, so it is recorded once
#[arg(long, value_parser = non_empty)]
pub relates_to: Vec<String>,
/// Take a relation off: the kind, then the ticket it points at. Repeat the flag
///
/// Two values rather than one, because a ticket can hold several relations of one
/// kind and emptying every `blocked by` on it is not usually what is wanted. That is
/// also why this is not `set --clear`, which names a field and empties the whole of
/// it: the "value" here is one edge among several, so the target has to be named too.
///
/// A `Vec<String>` because clap cannot type the two values of one flag apart.
/// [`RelateArgs::cleared`] is where the pairs are split and the kind is parsed.
#[arg(long, num_args = 2, value_names = ["KIND", "TARGET"], value_parser = non_empty)]
pub clear: Vec<String>,
}
impl RelateArgs {
@@ -886,6 +903,18 @@ impl RelateArgs {
(RelationKind::RelatesTo, &self.relates_to),
]
}
/// The relations asked to be taken off, as a kind and the search naming the target.
///
/// `num_args = 2` is per occurrence, so clap has already refused an odd number of
/// values and every chunk is a full pair. A kind that is not one of the three is
/// refused here, before the ticket is resolved and long before anything is written.
pub fn cleared(&self) -> anyhow::Result<Vec<(RelationKind, &str)>> {
self.clear
.chunks(2)
.map(|pair| Ok((RelationKind::parse_value(&pair[0])?, pair[1].as_str())))
.collect()
}
}
/// `check` and `uncheck` are separate commands rather than one verb with a flag,
+55 -13
View File
@@ -22,7 +22,7 @@ use clap::{CommandFactory, ValueEnum};
use clap_complete::Shell;
use crate::install::SKILLS;
use crate::util::Status;
use crate::util::{RelationKind, Status};
/// Subcommands whose first positional is a ticket.
///
@@ -98,6 +98,11 @@ fn fish_dynamic() -> String {
let ticket_commands = TICKET_COMMANDS.join(" ");
let ticket_second_commands = TICKET_SECOND_COMMANDS.join(" ");
let ticket_flags = flag_list(&TICKET_FLAGS);
let relation_kinds = RelationKind::ALL
.iter()
.map(|kind| kind.flag())
.collect::<Vec<_>>()
.join(" ");
let campaign_commands = CAMPAIGN_COMMANDS.join(" ");
let campaign_nested = CAMPAIGN_NESTED_COMMANDS
.iter()
@@ -188,6 +193,14 @@ complete -c worklane \
complete -c worklane -n '__worklane_command_is relate' {ticket_flags} \
-x -a '(worklane ls --ids)'
# `--clear` is the one flag here whose first value is not a ticket, so it is not in
# `TICKET_FLAGS`: it takes the kind and then the target, and offering a board listing where
# the kind goes would be offering values it refuses. The kinds come from `RelationKind`
# rather than being spelled again. The target gets no rule at all, deliberately: fish
# completes the value after the flag, and the case this flag exists for is a target whose
# ticket is gone, which no listing of the board can offer.
complete -c worklane -n '__worklane_command_is relate' -l clear -x -a '{relation_kinds}'
# Campaigns, from `campaign ls --ids`, in the three places one is named: `assign`'s first
# argument, `campaign show`'s only one, and `ls --campaign`.
complete -c worklane \
@@ -464,22 +477,51 @@ mod tests {
}
}
/// `chown --clear` takes a ticket, so it is completed like one, and only under
/// `chown`: `set --clear` is the same flag name carrying a field.
/// Three commands carry a `--clear` and each one takes something different: `chown`
/// takes the ticket, `relate` takes the kind and then the target, and `set` takes a
/// field name clap already offers. So each rule is scoped to its own command, and a
/// bare search for `-l clear` cannot tell them apart, which is what this used to do.
#[test]
fn chowns_clear_is_completed_with_tickets_and_sets_is_not() {
fn each_clear_flag_is_completed_for_its_own_command() {
let script = fish_dynamic();
let rule = script
.lines()
.find(|line| line.starts_with("complete") && line.contains("-l clear"))
.expect("chown --clear has a rule of its own");
assert!(rule.contains("__worklane_command_is chown"), "{rule}");
assert!(rule.contains("worklane ls --ids"), "{rule}");
let chown = command().find_subcommand("chown").expect("chown exists").clone();
let cli = command();
let rule_for = |name: &str| {
let scope = format!("__worklane_command_is {name}");
script
.lines()
.find(|line| {
line.starts_with("complete")
&& line.contains("-l clear")
&& line.contains(&scope)
})
.unwrap_or_else(|| panic!("no --clear rule for {name}:\n{script}"))
};
let has_clear = |name: &str| {
cli.find_subcommand(name)
.unwrap_or_else(|| panic!("no such subcommand: {name}"))
.get_arguments()
.any(|arg| arg.get_long() == Some("clear"))
};
// `chown --clear` names the ticket in the flag, so the flag completes tickets.
assert!(has_clear("chown"), "`chown` has no --clear for the rule to complete");
assert!(rule_for("chown").contains("worklane ls --ids"), "{}", rule_for("chown"));
// `relate --clear` takes the kind first, so it offers the kinds and not a board
// listing: tickets there would be candidates the flag refuses. The target, the
// second value, is deliberately left uncompleted.
assert!(has_clear("relate"), "`relate` has no --clear for the rule to complete");
let relate = rule_for("relate");
for kind in RelationKind::ALL {
assert!(relate.contains(kind.flag()), "{kind:?} is not offered: {relate}");
}
assert!(
chown.get_arguments().any(|arg| arg.get_long() == Some("clear")),
"`chown` has no --clear for the rule to complete"
!relate.contains("worklane ls --ids"),
"tickets offered where the kind goes: {relate}"
);
assert!(
!TICKET_FLAGS.contains(&"clear"),
"--clear in TICKET_FLAGS would offer tickets to `set --clear`, which takes a field"
+146 -5
View File
@@ -1105,16 +1105,97 @@ pub fn cmd_append(args: &AppendArgs, start: &Path) -> Result<()> {
/// The kinds are a flag each rather than a `--kind` value, so an unknown kind is a
/// usage error at the door instead of a line written into the file and refused on the
/// way back out.
/// The stored relation a `--clear` names, or `None` when the ticket does not hold it.
///
/// Two tiers, in this order. A uuid prefix against the targets this ticket already
/// stores, which is the only tier that can reach a dangling edge: the target's ticket is
/// gone, so no search of the board resolves it, and that is the case most likely to need
/// clearing. Then the ordinary ticket search, so a title or a prefix of a live ticket
/// works here the way it does in every other argument.
///
/// The prefix tier is the ticket's own relations and not the board, so it stays cheap and
/// cannot be made ambiguous by a ticket somewhere else. `MIN_ID_SEARCH` is the same floor
/// `resolve_in` puts under its id tier, and the comparison is case insensitive for the
/// same reason: an id typed back off a listing has to resolve in whatever case it was
/// read.
///
/// A search that reaches neither tier is an error, not a no-op. A relation the ticket does
/// not hold reports no change, which is what the caller asked for either way, but a search
/// naming nothing at all is a typo and reporting no change for it would swallow it.
fn find_relation(
existing: &[Relation],
kind: RelationKind,
search: &str,
title: &str,
worklane_dir: &Path,
) -> Result<Option<Relation>> {
let held: Vec<&Relation> = existing.iter().filter(|held| held.kind == kind).collect();
let wanted = search.to_lowercase();
let by_prefix: Vec<&Relation> = held
.iter()
.copied()
.filter(|held| {
search.chars().count() >= MIN_ID_SEARCH
&& held.target.to_lowercase().starts_with(&wanted)
})
.collect();
match by_prefix.as_slice() {
[only] => return Ok(Some((*only).clone())),
// Named rather than guessed at, the way an ambiguous ticket search is: the
// candidates are printed and nothing is written.
[_, _, ..] => {
return Err(anyhow!(
"'{}' matches {} '{}' relations on '{}': {}. Name more of the id",
search,
by_prefix.len(),
kind.label(),
title,
by_prefix
.iter()
.map(|held| short_id(&held.target))
.collect::<Vec<_>>()
.join(", ")
));
}
[] => {}
}
match resolve_ticket(search, worklane_dir) {
Ok((_status, _target_title, target)) => {
let target_uuid = parse_ticket_field(&target, "ID");
Ok(held.into_iter().find(|held| held.target == target_uuid).cloned())
}
// The resolver's own reason is carried through, so an ambiguous search says it is
// ambiguous rather than being reported as nothing at all.
Err(reason) => Err(anyhow!(
"No '{}' relation on '{}' matches '{}': {}",
kind.label(),
title,
search,
reason
)),
}
}
pub fn cmd_relate(args: &RelateArgs, start: &Path) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let (status, title, original) = resolve_ticket(&args.ticket, &worklane_dir)?;
let uuid = parse_ticket_field(&original, "ID");
let existing = parse_relations(&original, &title)?;
// Every target resolved and every refusal raised before a byte is written, so a
// call naming one good ticket and one bad one records neither.
// Every target resolved, every kind parsed and every refusal raised before a byte is
// written, so a call naming one good ticket and one bad one records neither.
let asked = args.cleared()?;
let mut items: Vec<String> = Vec::new();
let mut changed: Vec<&str> = Vec::new();
// Every addition the call asked for, whether or not it is one to write. `items` drops
// the ones already held, and a contradiction has to be caught on what was *asked*: a
// relation already in the file is not in `items`, so comparing against that would let
// `--blocked-by X --clear blocked-by X` quietly remove it.
let mut requested: Vec<Relation> = Vec::new();
for (kind, targets) in args.requested() {
for search in targets {
@@ -1136,6 +1217,7 @@ pub fn cmd_relate(args: &RelateArgs, start: &Path) -> Result<()> {
}
let relation = Relation { kind, target: target_uuid };
requested.push(relation.clone());
// Already held, either in the file or earlier in this call. Recording it
// twice would read as two dependencies on one ticket.
@@ -1150,15 +1232,74 @@ pub fn cmd_relate(args: &RelateArgs, start: &Path) -> Result<()> {
}
}
if items.is_empty() {
let mut dropped: Vec<Relation> = Vec::new();
let mut cleared: Vec<&str> = Vec::new();
for (kind, search) in asked {
let Some(relation) = find_relation(&existing, kind, search, &title, &worklane_dir)? else {
continue;
};
// Both directions in one call, the way `set --clear` refuses a field it is also
// replacing: nothing is written rather than one of the two silently winning.
if requested.contains(&relation) {
return Err(anyhow!(
"--{} and --clear {} name the same relation to '{}', so nothing was written",
kind.flag(),
kind.flag(),
short_id(&relation.target)
));
}
if dropped.contains(&relation) {
continue;
}
dropped.push(relation);
if !cleared.contains(&kind.label()) {
cleared.push(kind.label());
}
}
if items.is_empty() && dropped.is_empty() {
report(&[], &title, "Recorded");
return Ok(());
}
let content = append_section_body(&ensure_section(&original, &RELATIONS), &RELATIONS, &items)?;
// Removals first, by rewriting the section from what is left, then additions appended
// to that. Two passes rather than one rebuild of the whole section: a call with no
// `--clear` then takes exactly the path it always took, and `append_section_body` goes
// on deciding where a new line lands.
let mut content = original.clone();
if !dropped.is_empty() {
let kept: Vec<String> = existing
.iter()
.filter(|held| !dropped.contains(held))
.map(|held| held.item())
.collect();
// The placeholder rather than an empty body when the last edge goes, which is the
// line `add` writes and the line `append` treats as no content, so the section can
// be written to again without it being left above what follows.
content = match kept.is_empty() {
true => clear_section_body(&content, &RELATIONS)?,
false => set_section_body(&content, &RELATIONS, &kept)?,
};
}
if !items.is_empty() {
content = append_section_body(&ensure_section(&content, &RELATIONS), &RELATIONS, &items)?;
}
save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?;
report(&changed, &title, "Recorded");
if !changed.is_empty() {
report(&changed, &title, "Recorded");
}
if !cleared.is_empty() {
report(&cleared, &title, "Cleared");
}
Ok(())
}
+76
View File
@@ -2129,6 +2129,45 @@ impl RelationKind {
RelationKind::RegressionOf,
RelationKind::RelatesTo,
];
/// How the kind is spelled at the command line: the flag that records it, without
/// the leading hyphens.
///
/// A match rather than `label().replace(' ', "-")`, so the pairing is pinned and the
/// completion list, the `--clear` value and the flag cannot drift apart.
pub fn flag(self) -> &'static str {
match self {
RelationKind::BlockedBy => "blocked-by",
RelationKind::RegressionOf => "regression-of",
RelationKind::RelatesTo => "relates-to",
}
}
/// One kind from the value `relate --clear` names, or an error listing the three.
///
/// Both spellings are accepted, the flag's `blocked-by` and the label's `blocked by`,
/// because both are in front of the reader: the flag is what recorded the relation and
/// the label is what `show` prints in the block and what the file stores. Refusing the
/// form the tool itself prints would be a trap for anyone clearing a row they just
/// read. Case insensitive, the bargain the id and codename tiers already take.
pub fn parse_value(value: &str) -> Result<Self> {
let wanted = value.trim().to_lowercase().replace('-', " ");
RelationKind::ALL
.into_iter()
.find(|kind| kind.label() == wanted)
.ok_or_else(|| {
anyhow!(
"'{}' is not a relation kind. The kinds are {}",
value,
RelationKind::ALL
.iter()
.map(|kind| kind.flag())
.collect::<Vec<_>>()
.join(", ")
)
})
}
}
/// One stored edge: a kind, and the full uuid of the ticket it points at.
@@ -5579,6 +5618,43 @@ Plain line with **bold** and a [link](http://x.test/a).
assert_eq!(seen.len(), 3, "{seen:?}");
}
/// Every kind is reachable by the flag that records it and by the label `show` prints,
/// in any case, and every kind has a flag of its own. Over `RelationKind::ALL` rather
/// than the three names, so a kind added later has to be spellable too.
#[test]
fn a_kind_parses_from_the_flag_spelling_and_the_label_spelling() {
let mut flags = std::collections::HashSet::new();
for kind in RelationKind::ALL {
assert!(flags.insert(kind.flag()), "{kind:?} shares its flag with another kind");
assert_eq!(kind.flag(), kind.label().replace(' ', "-"), "{kind:?}");
for spelling in [kind.flag().to_string(), kind.label().to_string()] {
for cased in [spelling.to_lowercase(), spelling.to_uppercase()] {
assert_eq!(
RelationKind::parse_value(&cased).unwrap(),
kind,
"{cased:?} does not parse as {kind:?}"
);
}
}
}
}
/// A value that is not a kind names the three, in the spelling the flags and the
/// completions use rather than the spelling the file stores: a reader who has just
/// been refused is about to retype the flag.
#[test]
fn a_value_that_is_not_a_kind_names_the_three() {
let refused = RelationKind::parse_value("depends-on").expect_err("accepted");
let message = refused.to_string();
assert!(message.contains("not a relation kind"), "{message}");
for kind in RelationKind::ALL {
assert!(message.contains(kind.flag()), "{kind:?} is not named: {message}");
}
}
/// Both directions of one kind carry the same mark, since the kind is what the mark
/// says and the label is what says which way it points.
#[test]