Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
2ddd0addf6 |
@@ -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
|
- `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
|
- **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
|
### Monitoring Several Boards
|
||||||
- `worklane tui <path>...` 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
|
- `worklane tui <path>...` 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
|
- 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
|
||||||
|
|||||||
Generated
+1
-1
@@ -1503,7 +1503,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "worklane"
|
name = "worklane"
|
||||||
version = "0.23.0"
|
version = "0.23.1"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"anyhow",
|
"anyhow",
|
||||||
"assert_cmd",
|
"assert_cmd",
|
||||||
|
|||||||
+1
-1
@@ -1,6 +1,6 @@
|
|||||||
[package]
|
[package]
|
||||||
name = "worklane"
|
name = "worklane"
|
||||||
version = "0.23.0"
|
version = "0.23.1"
|
||||||
edition = "2024"
|
edition = "2024"
|
||||||
|
|
||||||
[dependencies]
|
[dependencies]
|
||||||
|
|||||||
+177
-2
@@ -254,13 +254,87 @@ pub fn color_text(text: &str, color: Color) -> String {
|
|||||||
paint(text, color, should_use_colors())
|
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<Candidate> {
|
||||||
|
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<std::path::PathBuf> {
|
pub fn find_worklane_dir(start: &Path) -> Result<std::path::PathBuf> {
|
||||||
let mut current = start.canonicalize()?;
|
let mut current = start.canonicalize()?;
|
||||||
|
|
||||||
loop {
|
loop {
|
||||||
let worklane_dir = current.join(".worklane");
|
let worklane_dir = current.join(".worklane");
|
||||||
if worklane_dir.exists() {
|
match classify(&worklane_dir)? {
|
||||||
return Ok(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() {
|
if !current.pop() {
|
||||||
@@ -4777,4 +4851,105 @@ mod tests {
|
|||||||
"{rendered:?}"
|
"{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}");
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -597,3 +597,30 @@ fn add_names_the_ticket_and_the_path_when_the_write_fails() {
|
|||||||
chmod(&backlog, 0o755);
|
chmod(&backlog, 0o755);
|
||||||
assert_eq!(fs::read_dir(&backlog).unwrap().count(), 0);
|
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);
|
||||||
|
}
|
||||||
|
|||||||
Reference in New Issue
Block a user