diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/design.md | 53 |
1 files changed, 49 insertions, 4 deletions
diff --git a/docs/design.md b/docs/design.md index 3130870..271e2a6 100644 --- a/docs/design.md +++ b/docs/design.md @@ -5,7 +5,9 @@ duplicates are never deleted (§5.5), and coloured output with `--no-color` (§8.2, §11); amended again 2026-09-14 for 0.0.3: the plan shown as one block per file, wrapped to the terminal, and `-P` (§8.2, §8.3, §11); amended again 2026-09-14 for 0.0.4: `max-size` (§4.4), `(exclude ...)` -(§4.2, §4.3, §4.6) and `--min-age` (§11). +(§4.2, §4.3, §4.6) and `--min-age` (§11); amended again 2026-09-14 for +0.0.5: the keyword cache (§3, §6.1, §13), and `t`, `d` and `w` in review +(§8.3, §10). krino (from Greek κρίνω, "to separate, to judge, to decide") sorts files in chosen directories by rules. A rule tests a file's type, name, path, size, @@ -59,6 +61,8 @@ $XDG_CONFIG_HOME/krino/ default ~/.config/krino $XDG_STATE_HOME/krino/ default ~/.local/state/krino krino.log the log (§9) <name>.lock per-directory lock while a run is active +$XDG_CACHE_HOME/krino/ default ~/.cache/krino + <name>.cache keyword cache (§6.1), 0600, safe to delete ``` `krino init` creates the config directory with a commented `krino.conf` and @@ -323,6 +327,35 @@ so a keyword split across lines in a PDF still matches. Matching is substring: `"acme"` matches `"acmeco"`. Words hyphenated across lines in a PDF are not rejoined. +### 6.1 Keyword cache + +Extraction is nearly all of a run's time, so krino remembers what it found. +For each file it extracted, `<name>.cache` records which of the +directory's content keywords the text contains, against the full list of +keywords it was checked against. It stores no text and no file names; a +file is known by device, inode, size and modification time, which krino's +own moves and renames keep. The keywords themselves are stored, as they +appear in the config. + +- When a file is extracted, every content keyword of its directory is + answered at once, so one extraction serves every rule and exclude. +- A content test is answered from the cache when the file's entry covers + all of the test's keywords. Otherwise the file is extracted and its entry + replaced: a changed file, or a new keyword, costs one extraction. +- Files above `max-read` are refused before the cache is consulted. + Failures (unreadable, tool missing, timeout) are never cached. +- The cache is discarded whole when the extractor fingerprint changes: a + tool installed, removed or replaced, or krino's extraction code changing + (`extract.Version`). +- Planning a run (`-n` included) reads the cache and writes it back holding + only files still in the directory, under the directory's lock, via a + temporary file renamed into place; the directory is 0700, the file 0600. + `explain` reads it and never writes. A directory with no content tests + has no cache. +- Known gap: a file edited in place with its size and modification time + deliberately preserved keeps its old answers. Deleting + `~/.cache/krino` resets everything. + ## 7. Actions ### 7.1 Chains @@ -525,10 +558,17 @@ list: move → Work/Acme/2026/ rule acme because name \bacme\b - [y] yes [n] no [a] yes to this and all remaining [d] done, apply chosen so far [q] quit, apply nothing + [y] yes [n] no [a] yes to this and all remaining [t] trash [d] delete permanently [w] write, apply chosen so far [q] quit, apply nothing ``` -Approval is per file: the whole chain or none of it. +Approval is per file: the whole chain or none of it. `t` and `d` approve +the file with its chain replaced by a single step on the file itself: to the +Trash, or deleted permanently. They are the user's own decision, logged +under the rule name `(review)`; `(review)` steps are not subject to the +duplicate protection of §5.5, which governs rules. `d` asks +`delete NAME permanently? [y/N]`, and any key but `y` deletes nothing and +asks about the file again. `w` stops asking and applies what was chosen so +far. `q` applies nothing in this directory, choices included. ### 8.4 Modes @@ -569,7 +609,7 @@ not logged; declined files are. is undone by naming it: `krino undo RUN`. Undo runs cannot themselves be undone. - Undo builds a plan like any other, shown and approved the same way - (`-y` and `-n` apply). + (`-y` and `-n` apply). Its per-file prompt has no `t` or `d`. Reversals, last step first within each file: @@ -675,6 +715,11 @@ Rules for the GUI to come: about krino, and would fail or pass for reasons outside its control. Report the measurement; promise nothing. `make bench` runs the Go benchmarks on generated trees. +- Keyword cache (§6.1, 0.0.5): measured on the same kind of folder, 170 + files, a dry run took 12.78 s with an empty cache and 0.13 s with a warm + one, printing the identical plan. Without the cache, 59 `pdftotext` runs + took 21.5 s of wall time between them, one PDF 14.7 s alone; with + extraction answered instantly, the run took 0.25 s. ## 14. Build, dependencies, release |