diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/design.md | 38 |
1 files changed, 27 insertions, 11 deletions
diff --git a/docs/design.md b/docs/design.md index 9d7abb5..5b70183 100644 --- a/docs/design.md +++ b/docs/design.md @@ -678,7 +678,7 @@ krino log [-n N] list recent runs krino undo [RUN] reverse a run (default: the last one) -y apply without asking --n dry run: show the plan, change nothing +-n dry run: show the plan, change no file (the keyword cache may be refreshed) -v also list unmatched, ignored and busy files; full match reasons --json with -n: the plan as JSON (format unstable before 1.0) -c FILE use FILE instead of ~/.config/krino/krino.conf @@ -847,18 +847,31 @@ survives their corruption — a truncated line, a damaged cache, a hand-edited trashinfo — but does not defend against another local process with write access to them, which could already do anything krino can. -What that means, and the tests that hold it (plan 8): +What that means, and the tests that hold it (plans 8 and 9): -- A name never controls the terminal. Every name, path, reason and warning - is printed through `display`, which shows C0 controls, DEL, C1 controls, - Unicode bidirectional embeddings, overrides and isolates, and invalid - UTF-8 as escapes (`\x1b`, `\u202e`). -- A name never redirects a step. A rename whose placeholders produce "", - "." or "..", and a destination whose placeholders add a ".." segment, are - skipped with a reason. +- A name never controls the terminal. Everything printed from a name, path, + reason, warning, error, explain trace, JSON plan or log field is escaped: + C0 controls, DEL, C1 controls, every Unicode bidirectional control + (embeddings, overrides, isolates and the marks), line and paragraph + separators, and invalid UTF-8 (`\x1b`, `\u202e`). All of stderr goes + through the same escaping. Invisible format characters that are not + controls are printed as they are (known limitation). +- A name never redirects a step. A destination with a placeholder must + resolve at or under the directory its text names before the first + placeholder, so a capture of "..", "~" or nothing cannot move it + elsewhere; a rename whose placeholders produce "", "." or ".." is skipped + with a reason. - A file is acted on only while it is still the file that was planned: same size and modification time, still a regular file (not a symlink put - in its place), and, at its planned path, the same inode. + in its place), and, at its planned path, the same inode. A step that had + to land at a free name stops the rest of its chain. Overwrite trashes only + a regular file, never a directory or another file of the same plan. +- Every step is logged as soon as it has run, so a run killed mid-chain can + be undone as far as it got. +- Undo restores a trash entry only while it is still the file the run put + there (size, mtime, recorded path), re-checks every file at execution + time, and can finish an undo that stopped part way. +- An exclude whose content test cannot read the file holds (fails closed). - A file reaches an external tool only as an absolute path, so a name starting with `-` is never read as an option. - A trash entry name from the log must be a plain name inside the Trash, @@ -869,7 +882,10 @@ What that means, and the tests that hold it (plan 8): normalisation. - For generated trees and rules, apply then undo restores every file, and nothing is lost in between (property test, `KRINO_PROPERTY_RUNS`). -- Every value of every enum the output, the log or planning depends on is +- For generated trees and rules, apply then undo also restores every + directory, and the test fails if too few cases apply anything. +- Every value of the enums planning, the log and the summary depend on + (`plan.Kind`, `config.ActionKind`, `config.Conflict`, `scan.Reason`) is handled: tests read the constants from source. - `make vulncheck` checks the standard library and dependencies against the Go vulnerability database; `make race` runs the tests under the race |