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); +}