From 2ddd0addf65066985ca87b3a75601e1f02edd883 Mon Sep 17 00:00:00 2001 From: Ansho Rei Date: Sun, 23 Aug 2026 13:47:31 +0200 Subject: [PATCH] (59b23b7) Stop the board walk on a link that does not resolve, and bump to 0.23.1 `find_worklane_dir` asked `exists()`, which follows a symlink. A `.worklane` that was a dangling link therefore answered exactly as no `.worklane` at all: the walk carried on up the tree, the first board above the project became the board, and every write landed in it. Silently, and in the board belonging to someone else's project. Latent while a board is a real directory inside the project it belongs to. Once boards live in one shared directory and `.worklane` is a link into it, a dangling link stops being a corrupted tree and becomes an ordinary state: it is what you have before the boards repo is cloned, and after a board directory is renamed. So this is reachable on an ordinary day rather than only with a hand-made link. `classify` reads `symlink_metadata` first, so the answer is about the entry rather than about its target, and it is one of four: `Absent`, `Board`, `Dangling` or `NotADirectory`. `Absent` is the only one the walk carries on from. A `.worklane` that is there but unusable is this project's board and is reported here, not handed to whatever sits above it. Anything other than `NotFound` out of `symlink_metadata` is an error too, since reading a filesystem that could not answer as nothing-there is how the walk-past worked in the first place. The failure names the target and says the boards repo may not be cloned. The old message, no board found and run `worklane init`, was wrong twice over even with no board above: it describes an empty tree, and it points at creating a board when the cause is an unsynced machine, which is the one action that produces two boards with one name. A regular file at that path is an error as well. It is a plausible future pointer form and reading it as one is that change's decision to make; stepping over it and writing above is the answer that is wrong today. A link that resolves is still indistinguishable from a real directory, and what comes back is the link rather than its target, so `.worklane/backlog/*.md` reads the same either way and nothing downstream learns whether the board is local. Every writing command resolves the board before it writes, so the refusal costs nothing halfway. `add` is where that is pinned end to end, against an empty board above the project that stays empty. `init` is untouched: it does not go through this walk, it writes nothing on a dangling link today, and its symlink cases belong to the layout change. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 7 ++ Cargo.lock | 2 +- Cargo.toml | 2 +- src/util.rs | 179 ++++++++++++++++++++++++++++++++++++++++++++++- tests/cmd_add.rs | 27 +++++++ 5 files changed, 213 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index eb2d2d1..a63a2f1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -303,6 +303,13 @@ and this file is for what someone changing worklane's own code needs. - `detail_body` closes a line only where the text says, so a part that does not end on a newline runs on into the next one. The seam between text and rows is wherever the body put it rather than wherever a part happened to end - **The relations block is the only coloured part of the overlay body, and that is a decision, not an oversight.** The headings, the plan numbers, the criteria marks, the bold runs and the grey unset values are all painted by `show` and all flat on the board. The block earned its colour because it is where a reader compares several references at once, and because it was already data rather than prose: it arrives as rows for the status mark, so styling it cost nothing extra. Colouring the rest means giving every painted run in `content_parts` the `Cell` treatment, which is a much larger change with no reader's question behind it, and it is its own ticket. Do not paint one more section here without taking that on: two coloured sections and five plain ones reads as a bug, where one clearly does not +### Finding the Board +- **`find_worklane_dir` classifies the entry before it follows it.** `exists()` follows a link, so a `.worklane` that was a dangling symlink answered the same as no `.worklane` at all: the walk carried on up the tree and the first board above the project became the one every write landed in, silently. `classify` reads `symlink_metadata` first and answers one of four, `Absent`, `Board`, `Dangling` or `NotADirectory`, and **`Absent` is the only one the walk carries on from**. A `.worklane` that is there but unusable is this project's board and is reported, not handed upward +- Anything other than `NotFound` from `symlink_metadata` is an error rather than an `Absent`. Reading a filesystem that could not answer as nothing-there is how the walk-past worked in the first place +- The dangling failure **names the target and says the boards repo may not be cloned**, and deliberately does not say to run `worklane init`. Once the boards live outside the project a dangling link is an ordinary state, what you have before the boards repo is cloned and after a board directory is renamed, so "no board found, run init" points at the wrong problem +- **A link that resolves is indistinguishable from a real directory, and what comes back is the link rather than its target.** `.worklane/backlog/*.md` has to read the same either way and nothing downstream learns whether the board is local, which is the property the shared-boards layout rests on +- A regular file at that path is an error as well. It is a plausible future pointer form, and reading it as one is that change's decision to make; stepping over it and writing to a board above is the one answer that is wrong today + ### Monitoring Several Boards - `worklane tui ...` takes any number of paths, each resolved through `find_worklane_dir` the way the working directory is: the first `.worklane` at or above it. No path is the working directory, so a bare `worklane` and `worklane tui` are unchanged - The failure **names the path** that had no board, since with several arguments "No .worklane directory found" does not say which one was wrong. Only when a path was given: a bare `worklane` has no path to name and keeps the message every other command gives, which is what its integration test asserts diff --git a/Cargo.lock b/Cargo.lock index abd5f94..c539649 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1503,7 +1503,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.23.0" +version = "0.23.1" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 6ceafb2..dab08f2 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.23.0" +version = "0.23.1" edition = "2024" [dependencies] diff --git a/src/util.rs b/src/util.rs index 3201ccf..9f56b79 100644 --- a/src/util.rs +++ b/src/util.rs @@ -254,13 +254,87 @@ pub fn color_text(text: &str, color: Color) -> String { paint(text, color, should_use_colors()) } +/// What sits at a candidate `.worklane` path. +/// +/// The distinction the walk turns on is between nothing there and something +/// unusable there. `exists()` follows a link, so a dangling one answered the same +/// as an empty parent and the walk carried on upward until it met a board above +/// the project, which then became the board every write went to. Silently. With +/// the boards kept outside the project a dangling link is an ordinary state +/// rather than a corrupted tree: it is what you have before the boards repo is +/// cloned, and after a board directory is renamed. +#[derive(Debug, PartialEq)] +enum Candidate { + /// Nothing at that path, which is the one answer the walk carries on from. + Absent, + /// A directory, or a link that resolves to one. + Board, + /// A link that resolves to nothing, carrying the target it names. + Dangling(std::path::PathBuf), + /// There, and not a directory: a regular file, or a link to one. + NotADirectory, +} + +/// Which of the four a `.worklane` path is. +/// +/// `symlink_metadata` first, so the answer is about the entry itself and absence +/// cannot be confused with a target that is gone. Only then is the link followed, +/// which is what makes a resolvable one indistinguishable from a real directory. +fn classify(path: &Path) -> Result { + let entry = match fs::symlink_metadata(path) { + Ok(entry) => entry, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(Candidate::Absent), + // Anything other than absence is a filesystem that could not answer, and + // reading that as absence is how the walk-past worked in the first place. + Err(error) => return Err(anyhow!("Could not read {}: {error}", path.display())), + }; + + if !entry.is_symlink() { + return Ok(match entry.is_dir() { + true => Candidate::Board, + false => Candidate::NotADirectory, + }); + } + + // Read whether or not it resolves: the target is the only part of the failure + // that says what to go and fix. + let target = fs::read_link(path).unwrap_or_else(|_| path.to_path_buf()); + + Ok(match fs::metadata(path) { + Ok(resolved) if resolved.is_dir() => Candidate::Board, + Ok(_) => Candidate::NotADirectory, + Err(_) => Candidate::Dangling(target), + }) +} + +/// The first `.worklane` at or above `start`. +/// +/// The symlink stays unresolved in what is returned, so a board reached through a +/// link is the same path to everything downstream as one sitting in the project. pub fn find_worklane_dir(start: &Path) -> Result { let mut current = start.canonicalize()?; loop { let worklane_dir = current.join(".worklane"); - if worklane_dir.exists() { - return Ok(worklane_dir); + match classify(&worklane_dir)? { + Candidate::Board => return Ok(worklane_dir), + // The only answer that hands the search upward. A `.worklane` that is + // there but unusable is this project's board and is reported here, + // rather than quietly becoming a write to whatever sits above it. + Candidate::Absent => {} + Candidate::Dangling(target) => { + return Err(anyhow!( + "{} is a symlink to {}, which does not exist. The boards repo may not be cloned on this machine.", + worklane_dir.display(), + target.display() + )); + } + Candidate::NotADirectory => { + return Err(anyhow!( + "{} is not a directory. A board is a directory of ticket files.", + worklane_dir.display() + )); + } } if !current.pop() { @@ -4777,4 +4851,105 @@ mod tests { "{rendered:?}" ); } + + // ----------------------------------------------------- finding the board -- + + /// A project directory under a temp root. + /// + /// The root is canonicalized because `find_worklane_dir` canonicalizes its + /// start: on a system whose temp path runs through a link, the two spellings + /// of the same directory would not compare equal. + fn project_in(root: &tempfile::TempDir) -> std::path::PathBuf { + let dir = root.path().canonicalize().unwrap().join("project"); + fs::create_dir_all(&dir).unwrap(); + dir + } + + /// The failure names the target, since the link is not the thing to fix, and it + /// does not say to run `init`: that answer belongs to an empty tree, and giving + /// it here points at the wrong problem. + #[test] + fn a_dangling_board_link_is_reported_with_its_target() { + let root = tempfile::tempdir().unwrap(); + let project = project_in(&root); + let target = project.parent().unwrap().join("boards/2fed877-the-board"); + std::os::unix::fs::symlink(&target, project.join(".worklane")).unwrap(); + + let error = find_worklane_dir(&project).unwrap_err().to_string(); + assert!(error.contains(&target.display().to_string()), "{error}"); + assert!(error.contains("boards repo"), "{error}"); + assert!(!error.contains("worklane init"), "{error}"); + } + + /// The bug this was written for: `exists()` follows the link, so a dangling one + /// answered false, the walk carried on up the tree, and the board above the + /// project became the board every write landed in. + #[test] + fn a_dangling_board_link_does_not_reach_the_board_above_it() { + let root = tempfile::tempdir().unwrap(); + let project = project_in(&root); + let above = project.parent().unwrap().join(".worklane"); + fs::create_dir_all(&above).unwrap(); + let link = project.join(".worklane"); + std::os::unix::fs::symlink(project.parent().unwrap().join("gone"), &link).unwrap(); + + let error = find_worklane_dir(&project).unwrap_err().to_string(); + assert!(error.contains(&link.display().to_string()), "{error}"); + + // And the walk really would have reached it, so the assertion above is + // about where the walk stopped rather than about an empty tree. + assert_eq!(find_worklane_dir(project.parent().unwrap()).unwrap(), above); + } + + /// Nothing at that path is still the one answer the walk carries on from. + #[test] + fn no_worklane_at_all_lets_the_walk_carry_on_upward() { + let root = tempfile::tempdir().unwrap(); + let project = project_in(&root); + let above = project.parent().unwrap().join(".worklane"); + fs::create_dir_all(&above).unwrap(); + + assert_eq!(find_worklane_dir(&project).unwrap(), above); + } + + /// A link that resolves is the board, and what comes back is the link rather + /// than its target: `.worklane/backlog` has to read the same either way. + #[test] + fn a_link_to_a_board_resolves_the_way_a_directory_does() { + let root = tempfile::tempdir().unwrap(); + let project = project_in(&root); + let board = project.parent().unwrap().join("boards/2fed877-the-board"); + fs::create_dir_all(&board).unwrap(); + let link = project.join(".worklane"); + std::os::unix::fs::symlink(&board, &link).unwrap(); + + assert_eq!(find_worklane_dir(&project).unwrap(), link); + } + + /// A regular file is reported rather than stepped over, and a board above it + /// does not make it the walk's problem to solve. + #[test] + fn a_regular_file_where_the_board_goes_is_an_error() { + let root = tempfile::tempdir().unwrap(); + let project = project_in(&root); + fs::write(project.join(".worklane"), "board = \"2fed877\"\n").unwrap(); + fs::create_dir_all(project.parent().unwrap().join(".worklane")).unwrap(); + + let error = find_worklane_dir(&project).unwrap_err().to_string(); + assert!(error.contains("not a directory"), "{error}"); + } + + /// A link that resolves to a file, which the follow catches and the entry check + /// on its own cannot: the entry is a symlink and the target is not a directory. + #[test] + fn a_link_to_a_file_is_not_a_board_either() { + let root = tempfile::tempdir().unwrap(); + let project = project_in(&root); + let file = project.parent().unwrap().join("pointer.toml"); + fs::write(&file, "board = \"2fed877\"\n").unwrap(); + std::os::unix::fs::symlink(&file, project.join(".worklane")).unwrap(); + + let error = find_worklane_dir(&project).unwrap_err().to_string(); + assert!(error.contains("not a directory"), "{error}"); + } } diff --git a/tests/cmd_add.rs b/tests/cmd_add.rs index 72a98e6..965747e 100644 --- a/tests/cmd_add.rs +++ b/tests/cmd_add.rs @@ -597,3 +597,30 @@ fn add_names_the_ticket_and_the_path_when_the_write_fails() { chmod(&backlog, 0o755); assert_eq!(fs::read_dir(&backlog).unwrap().count(), 0); } + +/// The board above the project is real and empty, and stays empty: a dangling +/// `.worklane` link used to read as no board here, and the walk then wrote the +/// ticket into whatever board sat above it. +#[test] +fn add_writes_nothing_when_the_board_link_does_not_resolve() { + let temp = TempDir::new().unwrap(); + let above = setup_worklane(&temp); + + let project = temp.child("project"); + project.create_dir_all().unwrap(); + let target = temp.path().join("boards/2fed877-the-board"); + std::os::unix::fs::symlink(&target, project.path().join(".worklane")).unwrap(); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + let assert = cmd + .current_dir(project.path()) + .args(["add", "--title", "Should not land"]) + .assert() + .failure(); + + let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap(); + assert!(stderr.contains(&target.display().to_string()), "{stderr}"); + assert!(stderr.contains("boards repo"), "{stderr}"); + + assert_eq!(fs::read_dir(above.join("backlog")).unwrap().count(), 0); +}